{"openapi":"3.1.0","info":{"title":"newcharactersheet.com API","version":"1.0.0","description":"Generate and manage AI character reference sheets and scenes. Authenticate with an API key via the X-API-Key header."},"servers":[{"url":"https://newcharactersheet.com","description":"Production"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-API-Key","description":"API key prefixed with ncs_. Generate one from Settings or POST /api/api-keys."}},"schemas":{"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]}}},"SheetImage":{"type":"object","properties":{"storagePath":{"type":"string"},"publicUrl":{"type":"string","format":"uri"},"contentType":{"type":"string"},"width":{"type":"integer"},"height":{"type":"integer"}}},"SheetVideo":{"type":"object","properties":{"storagePath":{"type":"string"},"publicUrl":{"type":"string","format":"uri"},"contentType":{"type":"string"}}},"PanelCut":{"type":"object","properties":{"id":{"type":"string"},"x":{"type":"number","minimum":0,"maximum":1},"y":{"type":"number","minimum":0,"maximum":1},"width":{"type":"number","minimum":0,"maximum":1},"height":{"type":"number","minimum":0,"maximum":1}}},"Sheet":{"type":"object","properties":{"id":{"type":"string"},"ownerUid":{"type":"string"},"sheetType":{"type":"string","enum":["character","scene"]},"visibility":{"type":"string","enum":["public","private"]},"prompt":{"type":"string"},"keywords":{"type":"array","items":{"type":"string"}},"handle":{"type":"string"},"createdAt":{"type":"integer"},"updatedAt":{"type":"integer"},"image":{"$ref":"#/components/schemas/SheetImage"},"video":{"$ref":"#/components/schemas/SheetVideo"},"accessUrl":{"type":"string","format":"uri","description":"Resolved image URL (signed for private, public for public)"},"videoAccessUrl":{"type":"string","format":"uri"},"feedVideoUrl":{"type":"string","format":"uri","description":"Short-form feed video URL"},"feedPosterUrl":{"type":"string","format":"uri","description":"Feed video poster image URL"},"panelCuts":{"type":"array","items":{"$ref":"#/components/schemas/PanelCut"}},"stats":{"type":"object","properties":{"savesCount":{"type":"integer"},"likesCount":{"type":"integer"},"commentsCount":{"type":"integer"}}},"project":{"type":"object","description":"Project this sheet belongs to","properties":{"id":{"type":"string"},"name":{"type":"string"}}},"savedFrom":{"type":"object","description":"Source sheet if this is a remix/save","properties":{"sheetId":{"type":"string"},"ownerUid":{"type":"string"}}},"characterRefs":{"type":"array","items":{"type":"string"},"description":"Sheet IDs of characters referenced in this scene"},"viewerHasLiked":{"type":"boolean","description":"Whether the authenticated viewer has liked this sheet"}}},"GenerateResult":{"type":"object","properties":{"id":{"type":"string","description":"ID of the created sheet. Fetch full sheet via GET /api/sheets/{id}."}}},"ApiKeyInfo":{"type":"object","properties":{"keyId":{"type":"string"},"label":{"type":"string"},"last4":{"type":"string"},"createdAt":{"type":"integer"}}}}},"paths":{"/api/auth/me":{"get":{"operationId":"getMe","summary":"Get current authenticated user","tags":["Auth"],"responses":{"200":{"description":"Current user info","content":{"application/json":{"schema":{"type":"object","properties":{"uid":{"type":"string"}}}}}},"401":{"description":"Not authenticated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/generate":{"post":{"operationId":"generateCharacterSheet","summary":"Generate a character reference sheet","tags":["Generation"],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"prompt":{"type":"string","description":"Character description prompt"},"keywords":{"type":"string","description":"Comma-separated keywords"},"visibility":{"type":"string","enum":["public","private"],"default":"private"},"style":{"type":"string","description":"Art style"},"referenceImages":{"type":"array","items":{"type":"string","format":"binary"},"description":"Reference images for the character"}},"required":["prompt"]}}}},"responses":{"201":{"description":"Character sheet generated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenerateResult"}}}},"401":{"description":"Not authenticated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/sheets/{id}":{"get":{"operationId":"getSheet","summary":"Get a character sheet by ID","tags":["Sheets"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Sheet details","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Sheet"}}}},"404":{"description":"Sheet not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"operationId":"updateSheet","summary":"Update sheet keywords, handle, or character refs","tags":["Sheets"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"keywords":{"oneOf":[{"type":"array","items":{"type":"string"}},{"type":"string"}]},"handle":{"type":"string","nullable":true},"characterRefs":{"type":"array","items":{"type":"string"}}}}}}},"responses":{"200":{"description":"Updated sheet","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Sheet"}}}}}},"delete":{"operationId":"deleteSheet","summary":"Delete a sheet you own","tags":["Sheets"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"Deleted"},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/sheets/search":{"get":{"operationId":"searchSheets","summary":"Search character sheets","tags":["Sheets"],"parameters":[{"name":"q","in":"query","description":"Search query","schema":{"type":"string"}}],"responses":{"200":{"description":"Search results","content":{"application/json":{"schema":{"type":"object","properties":{"results":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"prompt":{"type":"string"},"keywords":{"type":"array","items":{"type":"string"}},"handle":{"type":"string"},"imageUrl":{"type":"string","format":"uri"}}}}}}}}}}}},"/api/visibility/{id}":{"patch":{"operationId":"updateVisibility","summary":"Change sheet visibility","tags":["Sheets"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"visibility":{"type":"string","enum":["public","private"]}},"required":["visibility"]}}}},"responses":{"200":{"description":"Updated sheet","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Sheet"}}}}}}},"/api/scene/generate":{"post":{"operationId":"generateScene","summary":"Generate a scene image featuring characters","tags":["Scenes"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"prompt":{"type":"string","description":"Scene description"},"sheetIds":{"type":"array","items":{"type":"string"},"description":"Character sheet IDs to include in the scene (max 8)","maxItems":8},"outputMode":{"type":"string","enum":["picture","video"],"default":"picture"}}}}}},"responses":{"201":{"description":"Scene generated","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"imageBase64":{"type":"string"},"contentType":{"type":"string"},"outputMode":{"type":"string"}}}}}},"403":{"description":"Pro subscription required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/api-keys":{"get":{"operationId":"listApiKeys","summary":"List your API keys","tags":["API Keys"],"responses":{"200":{"description":"List of API keys (no secrets)","content":{"application/json":{"schema":{"type":"object","properties":{"keys":{"type":"array","items":{"$ref":"#/components/schemas/ApiKeyInfo"}}}}}}}}},"post":{"operationId":"createApiKey","summary":"Generate a new API key","tags":["API Keys"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"label":{"type":"string","description":"Human-readable label","default":"Default"}}}}}},"responses":{"201":{"description":"New API key created. The key field is shown only once.","content":{"application/json":{"schema":{"type":"object","properties":{"key":{"type":"string","description":"Plaintext API key (shown once)"},"keyId":{"type":"string"}}}}}}}},"delete":{"operationId":"revokeApiKey","summary":"Revoke an API key","tags":["API Keys"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"keyId":{"type":"string"}},"required":["keyId"]}}}},"responses":{"200":{"description":"Key revoked"},"404":{"description":"Key not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}}