{"openapi":"3.1.0","info":{"title":"The Gist API","description":"API for managing daily reading comprehension gists. Supports role-based access control for admins and team members.","version":"1.0.0"},"servers":[{"url":"https://your-app.vercel.app","description":"Production server"},{"url":"http://localhost:3000","description":"Development server"}],"components":{"responses":{"Unauthorized":{"description":"Authentication required or invalid token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"security":[{"bearerAuth":[]}],"paths":{"/api/auth/device/code":{"post":{"summary":"Request device code","description":"Start the device code OAuth flow. Returns a device code and user code.","security":[],"responses":{"200":{"description":"Device code created","content":{"application/json":{"schema":{"type":"object","properties":{"device_code":{"type":"string"},"user_code":{"type":"string","example":"ABC-DEF"},"verification_uri":{"type":"string","format":"uri"},"verification_uri_complete":{"type":"string","format":"uri"},"expires_in":{"type":"integer","description":"Seconds until expiration"},"interval":{"type":"integer","description":"Polling interval in seconds"}}}}}}}}},"/api/auth/device/token":{"post":{"summary":"Exchange device code for token","description":"Poll this endpoint with the device code to get an access token once the user approves.","security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"device_code":{"type":"string"}},"required":["device_code"]}}}},"responses":{"200":{"description":"Token granted","content":{"application/json":{"schema":{"type":"object","properties":{"access_token":{"type":"string"},"token_type":{"type":"string","example":"Bearer"},"expires_in":{"type":"integer"},"user":{"type":"object","properties":{"id":{"type":"string"},"role":{"type":"string","enum":["admin","team_member"]},"team_id":{"type":"string","nullable":true}}}}}}}},"400":{"description":"Still pending, expired, or invalid","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["authorization_pending","expired_token","invalid_grant"]},"error_description":{"type":"string"}}}}}}}}},"/api/gists":{"get":{"summary":"List gists","description":"Get a list of gists you have permission to view. Admins see all gists, team members see only their team's gists.","parameters":[{"name":"date","in":"query","schema":{"type":"string","format":"date"},"description":"Filter by date (YYYY-MM-DD)"},{"name":"category","in":"query","schema":{"type":"string","enum":["hot-take","tweet","literature","science","news","history","philosophy","pop-culture","business","sports","technology","health","travel","food","art"]},"description":"Filter by category"},{"name":"published","in":"query","schema":{"type":"boolean"},"description":"Only show published gists"}],"responses":{"200":{"description":"List of gists","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/Gist"}}}}},"401":{"$ref":"#/components/responses/Unauthorized"}}},"post":{"summary":"Create a gist","description":"Create a new draft gist. Requires exactly 5 true/false questions.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"category":{"type":"string","enum":["hot-take","tweet","literature","science","news","history","philosophy","pop-culture","business","sports","technology","health","travel","food","art"]},"date":{"type":"string","format":"date"},"title":{"type":"string"},"body":{"type":"string","description":"2-3 sentences"},"questions":{"type":"array","items":{"$ref":"#/components/schemas/Question"},"minItems":5,"maxItems":5}},"required":["category","date","title","body","questions"]}}}},"responses":{"201":{"description":"Gist created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Gist"}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"}}}},"/api/gists/{id}":{"get":{"summary":"Get a gist","description":"Get details of a specific gist by ID.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Gist details","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Gist"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"description":"Gist not found"}}},"patch":{"summary":"Update a gist","description":"Update an existing gist. All fields are optional.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"title":{"type":"string"},"body":{"type":"string"},"questions":{"type":"array","items":{"$ref":"#/components/schemas/Question"},"minItems":5,"maxItems":5},"category":{"type":"string"},"date":{"type":"string","format":"date"}}}}}},"responses":{"200":{"description":"Gist updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Gist"}}}},"401":{"$ref":"#/components/responses/Unauthorized"}}},"delete":{"summary":"Delete a gist","description":"Permanently delete a gist.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Gist deleted","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"}}}},"/api/gists/{id}/publish":{"post":{"summary":"Publish a gist","description":"Make a draft gist visible to users.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Gist published","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Gist"}}}},"401":{"$ref":"#/components/responses/Unauthorized"}}}},"/api/gists/{id}/unpublish":{"post":{"summary":"Unpublish a gist","description":"Make a published gist a draft again.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Gist unpublished","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Gist"}}}},"401":{"$ref":"#/components/responses/Unauthorized"}}}},"/api/gists/generate":{"post":{"summary":"Generate a gist with AI","description":"Use Claude AI to generate a new gist with title, body, and questions.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"category":{"type":"string","enum":["hot-take","tweet","literature","science","news","history","philosophy","pop-culture","business","sports","technology","health","travel","food","art"]},"date":{"type":"string","format":"date"},"topic":{"type":"string","description":"Optional specific topic"}},"required":["category","date"]}}}},"responses":{"201":{"description":"Gist generated and created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Gist"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"500":{"description":"Generation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}}