{"openapi":"3.1.0","info":{"title":"Talebench public API","version":"1","description":"Read and change the projects of a workspace with a key made in Workspace settings → API keys. Send it as “Authorization: Bearer tb_…”. Per key: 60 requests a minute, 10 changes a second and 500 file uploads an hour (429 with Retry-After); bodies up to 1 MB. Translations are written as the editor’s spreadsheet import writes them, a language not there yet added hidden from players unless the body says hidden: false; files are uploaded to a presigned POST (10 minutes) and count against the workspace’s storage; a file’s download link works 5 minutes. Changes within v1 only add."},"paths":{"/api/v1/key":{"get":{"operationId":"PublicApi_key","summary":"The key of this request: its workspace, role and projects","tags":["PublicApi"],"security":[{"apiKey":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1Key"}}}},"401":{"description":"Missing, unknown, revoked or expired key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests for this key: try again after the seconds in Retry-After","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/openapi.json":{"get":{"operationId":"PublicApiDoc_openapi","summary":"The OpenAPI document of the public API (/api/v1), each tool with its arguments","tags":["PublicApiDoc"],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","additionalProperties":{}}}}}}}},"/api/v1/projects":{"get":{"operationId":"PublicApi_projects","summary":"The projects this key may use, the most recently changed first","tags":["PublicApi"],"security":[{"apiKey":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/V1Project"}}}}},"401":{"description":"Missing, unknown, revoked or expired key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests for this key: try again after the seconds in Retry-After","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/projects/{project}/files":{"get":{"operationId":"PublicApiData_files","summary":"The project’s files (pictures, sounds, videos, captions, fonts), newest first","tags":["PublicApiData"],"security":[{"apiKey":[]}],"parameters":[{"name":"project","in":"path","required":true,"schema":{"type":"string"}},{"name":"kind","in":"query","required":false,"schema":{"type":"string","enum":["image","spritesheet","audio","video","subtitle","font"]}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/V1File"}}}}},"401":{"description":"Missing, unknown, revoked or expired key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"A project this key cannot use","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Invalid input (field errors in details.fields)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests for this key: try again after the seconds in Retry-After","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"operationId":"PublicApiData_register","summary":"Registers an upload and returns a presigned POST for it (10 minutes); the declared size counts against the workspace’s storage","tags":["PublicApiData"],"security":[{"apiKey":[]}],"parameters":[{"name":"project","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":200},"filename":{"type":"string","minLength":1,"maxLength":255},"contentType":{"type":"string"},"byteSize":{"type":"integer","minimum":0,"exclusiveMinimum":true},"kind":{"type":"string","enum":["image","spritesheet","audio","video","subtitle","font"]},"alt":{"type":"string","maxLength":500}},"required":["name","filename","contentType","byteSize","kind"],"additionalProperties":false}}}},"responses":{"201":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1FileUpload"}}}},"401":{"description":"Missing, unknown, revoked or expired key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"read_only: a viewer key changes nothing","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"A project this key cannot use","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"archived, or quota_exceeded: the workspace has no room for the file","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"unsupported_file: a type or size the kind does not take","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests for this key: try again after the seconds in Retry-After","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/projects/{project}/files/{file}":{"get":{"operationId":"PublicApiData_file","summary":"A file with a download link that works 5 minutes (ready files only)","tags":["PublicApiData"],"security":[{"apiKey":[]}],"parameters":[{"name":"project","in":"path","required":true,"schema":{"type":"string"}},{"name":"file","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1File"}}}},"401":{"description":"Missing, unknown, revoked or expired key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"A project this key cannot use, or no such file","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests for this key: try again after the seconds in Retry-After","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/projects/{project}/files/{file}/complete":{"post":{"operationId":"PublicApiData_complete","summary":"Finishes an upload: the file is moved, checked and counted against the workspace’s storage with its real size","tags":["PublicApiData"],"security":[{"apiKey":[]}],"parameters":[{"name":"project","in":"path","required":true,"schema":{"type":"string"}},{"name":"file","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"metadata":{"type":"object","properties":{"durationMs":{"type":"number"},"width":{"type":"number"},"height":{"type":"number"}},"additionalProperties":false}},"additionalProperties":false}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1File"}}}},"401":{"description":"Missing, unknown, revoked or expired key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"read_only: a viewer key changes nothing","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"A project this key cannot use, or no such file","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"already_completing, not_uploaded, archived or quota_exceeded (the file was deleted)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"file_rejected: the file is not what it says it is","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests for this key: try again after the seconds in Retry-After","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/projects/{project}/translations":{"get":{"operationId":"PublicApiData_languages","summary":"The project’s main language and its translations, each with its progress","tags":["PublicApiData"],"security":[{"apiKey":[]}],"parameters":[{"name":"project","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1Languages"}}}},"401":{"description":"Missing, unknown, revoked or expired key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"A project this key cannot use","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests for this key: try again after the seconds in Retry-After","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/projects/{project}/translations/{language}":{"get":{"operationId":"PublicApiData_language","summary":"Every text of the project with its translation into a language and its state","tags":["PublicApiData"],"security":[{"apiKey":[]}],"parameters":[{"name":"project","in":"path","required":true,"schema":{"type":"string"}},{"name":"language","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1Language"}}}},"401":{"description":"Missing, unknown, revoked or expired key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"A project this key cannot use, or a language the project does not have","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"main_language: the project’s main language has no translations","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests for this key: try again after the seconds in Retry-After","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"put":{"operationId":"PublicApiData_writeTranslations","summary":"Writes translations into a language as the editor’s spreadsheet import does: rows matched by address, kept in the History; a new language is added hidden from players unless hidden is false","tags":["PublicApiData"],"security":[{"apiKey":[]}],"parameters":[{"name":"project","in":"path","required":true,"schema":{"type":"string"}},{"name":"language","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1TranslationsWrite"}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1TranslationsWritten"}}}},"401":{"description":"Missing, unknown, revoked or expired key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"read_only: a viewer key changes nothing","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"A project this key cannot use","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"The project is archived, or was changed at the same moment","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"invalid (not a language code, or the body does not fit), main_language, wrong_file (no address or language column)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests for this key: try again after the seconds in Retry-After","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/tools":{"get":{"operationId":"PublicApi_list","summary":"The tools this key may use, with the JSON Schema of their arguments","tags":["PublicApi"],"security":[{"apiKey":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/V1Tool"}}}}},"401":{"description":"Missing, unknown, revoked or expired key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests for this key: try again after the seconds in Retry-After","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/tools/{tool}":{"post":{"operationId":"PublicApi_run","summary":"Runs a tool (as the MCP server does) with its arguments as the body; changes are checked and kept in the History","tags":["PublicApi"],"security":[{"apiKey":[]}],"parameters":[{"name":"tool","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1ToolArguments"}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1ToolResult"}}}},"401":{"description":"Missing, unknown, revoked or expired key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The key may not use this tool (a viewer key changes nothing; AI tools only when allowed)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such tool, or a project this key cannot use","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"The project cannot be changed now (archived, or changed at the same moment)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Invalid input (field errors in details.fields)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests for this key: try again after the seconds in Retry-After","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/tools/check_formula":{"post":{"operationId":"tool_check_formula","summary":"Check a formula","description":"Checks a formula (a condition like `gold >= 3 and has(\"thg_key\")` or a calculation) against the project: whether it works and what it gives (yes/no, a number, a text).","tags":["Tools"],"security":[{"apiKey":[]}],"x-effect":"reads","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"project":{"type":"string","description":"The project’s ID (from list_projects)"},"formula":{"type":"string","minLength":1,"maxLength":2000},"where":{"default":"world","type":"string","enum":["world","visual","battle"]}},"required":["project","formula"]}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1ToolResult"}}}},"401":{"description":"Missing, unknown, revoked or expired key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The key may not use this tool (a viewer key changes nothing; AI tools only when allowed)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such tool, or a project this key cannot use","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"The project cannot be changed now (archived, or changed at the same moment)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Invalid input (field errors in details.fields)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests for this key: try again after the seconds in Retry-After","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/tools/create_picture":{"post":{"operationId":"tool_create_picture","summary":"Create a picture","description":"Makes four pictures from a description in the project’s visual style (a scene background, a character, a thing or a cover). It takes a minute; then use generation_result and keep_generated. Counts against the workspace’s monthly AI limit.","tags":["Tools"],"security":[{"apiKey":[]}],"x-effect":"adds","x-ai":true,"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"project":{"type":"string","description":"The project’s ID (from list_projects)"},"kind":{"type":"string","enum":["scene","character","thing","cover","tile"]},"description":{"type":"string","minLength":1,"maxLength":1000}},"required":["project","kind","description"]}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1ToolResult"}}}},"401":{"description":"Missing, unknown, revoked or expired key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The key may not use this tool (a viewer key changes nothing; AI tools only when allowed)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such tool, or a project this key cannot use","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"The project cannot be changed now (archived, or changed at the same moment)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Invalid input (field errors in details.fields)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests for this key: try again after the seconds in Retry-After","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/tools/create_sound":{"post":{"operationId":"tool_create_sound","summary":"Create a sound","description":"Makes two sounds from a description (a sound effect, ambience or a music loop). It takes a minute; then use generation_result and keep_generated. Counts against the workspace’s monthly AI limit.","tags":["Tools"],"security":[{"apiKey":[]}],"x-effect":"adds","x-ai":true,"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"project":{"type":"string","description":"The project’s ID (from list_projects)"},"kind":{"type":"string","enum":["effect","music","ambience"]},"description":{"type":"string","minLength":1,"maxLength":1000},"durationSeconds":{"type":"number","minimum":0.5,"maximum":190}},"required":["project","kind","description"]}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1ToolResult"}}}},"401":{"description":"Missing, unknown, revoked or expired key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The key may not use this tool (a viewer key changes nothing; AI tools only when allowed)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such tool, or a project this key cannot use","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"The project cannot be changed now (archived, or changed at the same moment)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Invalid input (field errors in details.fields)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests for this key: try again after the seconds in Retry-After","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/tools/explain_formula":{"post":{"operationId":"tool_explain_formula","summary":"Explain a formula","description":"A formula in plain words, with the names the creator gave values, things and passages.","tags":["Tools"],"security":[{"apiKey":[]}],"x-effect":"reads","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"project":{"type":"string","description":"The project’s ID (from list_projects)"},"formula":{"type":"string","minLength":1,"maxLength":2000}},"required":["project","formula"]}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1ToolResult"}}}},"401":{"description":"Missing, unknown, revoked or expired key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The key may not use this tool (a viewer key changes nothing; AI tools only when allowed)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such tool, or a project this key cannot use","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"The project cannot be changed now (archived, or changed at the same moment)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Invalid input (field errors in details.fields)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests for this key: try again after the seconds in Retry-After","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/tools/fast_forward":{"post":{"operationId":"tool_fast_forward","summary":"Find the way to a passage","description":"Finds a way through the game from the start (or a test state) to a passage: the choices to take, or the option that blocks the way.","tags":["Tools"],"security":[{"apiKey":[]}],"x-effect":"reads","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"project":{"type":"string","description":"The project’s ID (from list_projects)"},"passage":{"type":"string","description":"The passage’s ID"},"testState":{"description":"A test state of the project, by name or ID, to start from","type":"string","maxLength":200}},"required":["project","passage"]}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1ToolResult"}}}},"401":{"description":"Missing, unknown, revoked or expired key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The key may not use this tool (a viewer key changes nothing; AI tools only when allowed)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such tool, or a project this key cannot use","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"The project cannot be changed now (archived, or changed at the same moment)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Invalid input (field errors in details.fields)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests for this key: try again after the seconds in Retry-After","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/tools/generation_result":{"post":{"operationId":"tool_generation_result","summary":"Picture or sound result","description":"Whether pictures or sounds asked for with create_picture or create_sound are ready, with a link to each variant (valid for a short time).","tags":["Tools"],"security":[{"apiKey":[]}],"x-effect":"reads","x-ai":true,"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"project":{"type":"string","description":"The project’s ID (from list_projects)"},"job":{"type":"string"}},"required":["project","job"]}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1ToolResult"}}}},"401":{"description":"Missing, unknown, revoked or expired key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The key may not use this tool (a viewer key changes nothing; AI tools only when allowed)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such tool, or a project this key cannot use","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"The project cannot be changed now (archived, or changed at the same moment)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Invalid input (field errors in details.fields)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests for this key: try again after the seconds in Retry-After","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/tools/keep_generated":{"post":{"operationId":"tool_keep_generated","summary":"Keep a picture or sound","description":"Keeps one variant of a finished picture or sound request as a file of the project (the others are discarded) and names it.","tags":["Tools"],"security":[{"apiKey":[]}],"x-effect":"changes","x-ai":true,"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"project":{"type":"string","description":"The project’s ID (from list_projects)"},"job":{"type":"string"},"variant":{"type":"integer","minimum":0,"maximum":9007199254740991},"name":{"type":"string","minLength":1,"maxLength":200}},"required":["project","job","variant","name"]}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1ToolResult"}}}},"401":{"description":"Missing, unknown, revoked or expired key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The key may not use this tool (a viewer key changes nothing; AI tools only when allowed)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such tool, or a project this key cannot use","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"The project cannot be changed now (archived, or changed at the same moment)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Invalid input (field errors in details.fields)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests for this key: try again after the seconds in Retry-After","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/tools/list_assets":{"post":{"operationId":"tool_list_assets","summary":"List pictures and sounds","description":"The project’s files (pictures, sounds, videos, fonts) with their IDs, names, alt texts and whether AI made them.","tags":["Tools"],"security":[{"apiKey":[]}],"x-effect":"reads","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"project":{"type":"string","description":"The project’s ID (from list_projects)"},"kind":{"type":"string","enum":["image","spritesheet","audio","video","subtitle","font"]}},"required":["project"]}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1ToolResult"}}}},"401":{"description":"Missing, unknown, revoked or expired key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The key may not use this tool (a viewer key changes nothing; AI tools only when allowed)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such tool, or a project this key cannot use","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"The project cannot be changed now (archived, or changed at the same moment)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Invalid input (field errors in details.fields)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests for this key: try again after the seconds in Retry-After","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/tools/list_projects":{"post":{"operationId":"tool_list_projects","summary":"List projects","description":"The interactive-story projects this connection may use, with their IDs. Start here: every other tool takes a project ID.","tags":["Tools"],"security":[{"apiKey":[]}],"x-effect":"reads","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1ToolResult"}}}},"401":{"description":"Missing, unknown, revoked or expired key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The key may not use this tool (a viewer key changes nothing; AI tools only when allowed)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such tool, or a project this key cannot use","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"The project cannot be changed now (archived, or changed at the same moment)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Invalid input (field errors in details.fields)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests for this key: try again after the seconds in Retry-After","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/tools/problems":{"post":{"operationId":"tool_problems","summary":"Problems","description":"The project’s problems and warnings (broken links, missing pictures, formulas that do not work …), each with where it is. One-click fixes are offered in Talebench.","tags":["Tools"],"security":[{"apiKey":[]}],"x-effect":"reads","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"project":{"type":"string","description":"The project’s ID (from list_projects)"}},"required":["project"]}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1ToolResult"}}}},"401":{"description":"Missing, unknown, revoked or expired key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The key may not use this tool (a viewer key changes nothing; AI tools only when allowed)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such tool, or a project this key cannot use","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"The project cannot be changed now (archived, or changed at the same moment)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Invalid input (field errors in details.fields)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests for this key: try again after the seconds in Retry-After","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/tools/project_overview":{"post":{"operationId":"tool_project_overview","summary":"Project overview","description":"A project at a glance: title, game type, language, features, style guide, chapters, how many passages, values, characters, things and endings it has, where the story starts and a summary of its problems.","tags":["Tools"],"security":[{"apiKey":[]}],"x-effect":"reads","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"project":{"type":"string","description":"The project’s ID (from list_projects)"}},"required":["project"]}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1ToolResult"}}}},"401":{"description":"Missing, unknown, revoked or expired key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The key may not use this tool (a viewer key changes nothing; AI tools only when allowed)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such tool, or a project this key cannot use","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"The project cannot be changed now (archived, or changed at the same moment)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Invalid input (field errors in details.fields)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests for this key: try again after the seconds in Retry-After","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/tools/propose_changes":{"post":{"operationId":"tool_propose_changes","summary":"Change the project","description":"Changes the project with a list of changes, applied together or not at all and checked by the engine; afterwards the new problems are listed. Each change has `do`: create_passage {title, text?, chapter?, ref?}, set_title {passage, title}, set_text {passage, text}, add_text {passage, text, speaker?}, add_option {passage, label, to: {passage}|{ending}, onlyIf?, changes?, ref?}, set_option {passage, option, label?, to?, onlyIf?}, remove_option {passage, option}, add_change {passage, option?, change}, create_value {name, type: yesno|number|text, start?, shown?, ref?}, create_ending {name, kind?, text?, ref?}, create_chapter {title, color?, ref?}, create_character {name, description?, ref?}, create_thing {name, description?, ref?}, set_start {passage}. Entities are named by ID, exact name, or the `ref` an earlier change of the same call gave a new one. A change is {set: value, to}, {change: value, by}, {give: thing, qty} or {take: thing, qty}; formulas use the values’ formula names (read_entities kind values). Before the first change of a connection Talebench keeps a snapshot, so the creator can restore everything at once.","tags":["Tools"],"security":[{"apiKey":[]}],"x-effect":"changes","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"project":{"type":"string","description":"The project’s ID (from list_projects)"},"changes":{"minItems":1,"maxItems":100,"type":"array","items":{"oneOf":[{"type":"object","properties":{"do":{"type":"string","const":"create_passage"},"title":{"type":"string","minLength":1,"maxLength":200},"ref":{"description":"A name for the new entity that later changes of this call can use instead of its ID","type":"string","pattern":"^[A-Za-z0-9_-]{1,40}$"},"chapter":{"type":"string","minLength":1,"maxLength":200,"description":"An ID, the exact name or title, or the ref of an entity made earlier in this call"},"text":{"description":"Paragraphs separated by blank lines","type":"string","maxLength":20000}},"required":["do","title"]},{"type":"object","properties":{"do":{"type":"string","const":"set_title"},"passage":{"type":"string","minLength":1,"maxLength":200,"description":"An ID, the exact name or title, or the ref of an entity made earlier in this call"},"title":{"type":"string","minLength":1,"maxLength":200}},"required":["do","passage","title"]},{"type":"object","properties":{"do":{"type":"string","const":"set_text"},"passage":{"type":"string","minLength":1,"maxLength":200,"description":"An ID, the exact name or title, or the ref of an entity made earlier in this call"},"text":{"type":"string","maxLength":20000,"description":"Replaces the passage’s text; paragraphs separated by blank lines"}},"required":["do","passage","text"]},{"type":"object","properties":{"do":{"type":"string","const":"add_text"},"passage":{"type":"string","minLength":1,"maxLength":200,"description":"An ID, the exact name or title, or the ref of an entity made earlier in this call"},"text":{"type":"string","minLength":1,"maxLength":20000},"speaker":{"description":"A character who says it","type":"string","minLength":1,"maxLength":200}},"required":["do","passage","text"]},{"type":"object","properties":{"do":{"type":"string","const":"add_option"},"passage":{"type":"string","minLength":1,"maxLength":200,"description":"An ID, the exact name or title, or the ref of an entity made earlier in this call"},"label":{"type":"string","minLength":1,"maxLength":200},"to":{"type":"object","properties":{"passage":{"type":"string","minLength":1,"maxLength":200,"description":"An ID, the exact name or title, or the ref of an entity made earlier in this call"},"ending":{"type":"string","minLength":1,"maxLength":200,"description":"An ID, the exact name or title, or the ref of an entity made earlier in this call"}},"description":"Where the option leads: {passage} or {ending}"},"onlyIf":{"type":"string","maxLength":2000,"description":"A formula, e.g. `gold >= 3 and has(\"Key\")`; empty removes the condition"},"changes":{"maxItems":20,"type":"array","items":{"anyOf":[{"type":"object","properties":{"set":{"type":"string","minLength":1,"maxLength":200,"description":"The value"},"to":{"type":"string","maxLength":500}},"required":["set","to"]},{"type":"object","properties":{"change":{"type":"string","minLength":1,"maxLength":200,"description":"The value"},"by":{"type":"string","maxLength":500}},"required":["change","by"]},{"type":"object","properties":{"give":{"type":"string","minLength":1,"maxLength":200,"description":"The thing"},"qty":{"default":"1","type":"string","maxLength":100}},"required":["give"]},{"type":"object","properties":{"take":{"type":"string","minLength":1,"maxLength":200,"description":"The thing"},"qty":{"default":"1","type":"string","maxLength":100}},"required":["take"]}],"description":"A change: {set: value, to: formula} | {change: value, by: formula (negative to lower)} | {give: thing, qty} | {take: thing, qty}"}},"ref":{"description":"A name for the new entity that later changes of this call can use instead of its ID","type":"string","pattern":"^[A-Za-z0-9_-]{1,40}$"}},"required":["do","passage","label","to"]},{"type":"object","properties":{"do":{"type":"string","const":"set_option"},"passage":{"type":"string","minLength":1,"maxLength":200,"description":"An ID, the exact name or title, or the ref of an entity made earlier in this call"},"option":{"type":"string","minLength":1,"maxLength":200,"description":"The option’s ID or exact label"},"label":{"type":"string","minLength":1,"maxLength":200},"to":{"type":"object","properties":{"passage":{"type":"string","minLength":1,"maxLength":200,"description":"An ID, the exact name or title, or the ref of an entity made earlier in this call"},"ending":{"type":"string","minLength":1,"maxLength":200,"description":"An ID, the exact name or title, or the ref of an entity made earlier in this call"}},"description":"Where the option leads: {passage} or {ending}"},"onlyIf":{"type":"string","maxLength":2000,"description":"A formula, e.g. `gold >= 3 and has(\"Key\")`; empty removes the condition"}},"required":["do","passage","option"]},{"type":"object","properties":{"do":{"type":"string","const":"remove_option"},"passage":{"type":"string","minLength":1,"maxLength":200,"description":"An ID, the exact name or title, or the ref of an entity made earlier in this call"},"option":{"type":"string","minLength":1,"maxLength":200,"description":"An ID, the exact name or title, or the ref of an entity made earlier in this call"}},"required":["do","passage","option"]},{"type":"object","properties":{"do":{"type":"string","const":"add_change"},"passage":{"type":"string","minLength":1,"maxLength":200,"description":"An ID, the exact name or title, or the ref of an entity made earlier in this call"},"option":{"description":"Without an option the change happens in the passage itself","type":"string","minLength":1,"maxLength":200},"change":{"anyOf":[{"type":"object","properties":{"set":{"type":"string","minLength":1,"maxLength":200,"description":"The value"},"to":{"type":"string","maxLength":500}},"required":["set","to"]},{"type":"object","properties":{"change":{"type":"string","minLength":1,"maxLength":200,"description":"The value"},"by":{"type":"string","maxLength":500}},"required":["change","by"]},{"type":"object","properties":{"give":{"type":"string","minLength":1,"maxLength":200,"description":"The thing"},"qty":{"default":"1","type":"string","maxLength":100}},"required":["give"]},{"type":"object","properties":{"take":{"type":"string","minLength":1,"maxLength":200,"description":"The thing"},"qty":{"default":"1","type":"string","maxLength":100}},"required":["take"]}],"description":"A change: {set: value, to: formula} | {change: value, by: formula (negative to lower)} | {give: thing, qty} | {take: thing, qty}"}},"required":["do","passage","change"]},{"type":"object","properties":{"do":{"type":"string","const":"create_value"},"name":{"type":"string","minLength":1,"maxLength":200},"type":{"type":"string","enum":["yesno","number","text"]},"start":{"type":["boolean","number","string"]},"shown":{"description":"Shown to the player (default: no)","type":"boolean"},"ref":{"description":"A name for the new entity that later changes of this call can use instead of its ID","type":"string","pattern":"^[A-Za-z0-9_-]{1,40}$"}},"required":["do","name","type"]},{"type":"object","properties":{"do":{"type":"string","const":"create_ending"},"name":{"type":"string","minLength":1,"maxLength":200},"kind":{"default":"neutral","type":"string","enum":["good","neutral","bad","defeat"]},"text":{"type":"string","maxLength":20000},"ref":{"description":"A name for the new entity that later changes of this call can use instead of its ID","type":"string","pattern":"^[A-Za-z0-9_-]{1,40}$"}},"required":["do","name"]},{"type":"object","properties":{"do":{"type":"string","const":"create_chapter"},"title":{"type":"string","minLength":1,"maxLength":200},"color":{"type":"string","pattern":"^#[0-9a-fA-F]{6}$"},"ref":{"description":"A name for the new entity that later changes of this call can use instead of its ID","type":"string","pattern":"^[A-Za-z0-9_-]{1,40}$"}},"required":["do","title"]},{"type":"object","properties":{"do":{"type":"string","const":"create_character"},"name":{"type":"string","minLength":1,"maxLength":200},"description":{"type":"string","maxLength":20000},"ref":{"description":"A name for the new entity that later changes of this call can use instead of its ID","type":"string","pattern":"^[A-Za-z0-9_-]{1,40}$"}},"required":["do","name"]},{"type":"object","properties":{"do":{"type":"string","const":"create_thing"},"name":{"type":"string","minLength":1,"maxLength":200},"description":{"type":"string","maxLength":20000},"ref":{"description":"A name for the new entity that later changes of this call can use instead of its ID","type":"string","pattern":"^[A-Za-z0-9_-]{1,40}$"}},"required":["do","name"]},{"type":"object","properties":{"do":{"type":"string","const":"set_start"},"passage":{"type":"string","minLength":1,"maxLength":200,"description":"An ID, the exact name or title, or the ref of an entity made earlier in this call"}},"required":["do","passage"]}]}},"summary":{"description":"What these changes do, in one line","type":"string","maxLength":300}},"required":["project","changes"]}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1ToolResult"}}}},"401":{"description":"Missing, unknown, revoked or expired key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The key may not use this tool (a viewer key changes nothing; AI tools only when allowed)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such tool, or a project this key cannot use","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"The project cannot be changed now (archived, or changed at the same moment)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Invalid input (field errors in details.fields)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests for this key: try again after the seconds in Retry-After","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/tools/read_entities":{"post":{"operationId":"tool_read_entities","summary":"Read values, characters, things …","description":"The project’s values, characters, things, endings, chapters, collections, enemies, encounters, skills, storages, shops, shared formulas, maps, decks or test states, by kind, optionally only some IDs.","tags":["Tools"],"security":[{"apiKey":[]}],"x-effect":"reads","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"project":{"type":"string","description":"The project’s ID (from list_projects)"},"kind":{"type":"string","enum":["values","characters","things","endings","chapters","collections","enemies","encounters","skills","storages","shops","formulas","maps","decks","test_states"]},"ids":{"maxItems":100,"type":"array","items":{"type":"string"}}},"required":["project","kind"]}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1ToolResult"}}}},"401":{"description":"Missing, unknown, revoked or expired key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The key may not use this tool (a viewer key changes nothing; AI tools only when allowed)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such tool, or a project this key cannot use","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"The project cannot be changed now (archived, or changed at the same moment)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Invalid input (field errors in details.fields)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests for this key: try again after the seconds in Retry-After","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/tools/read_passages":{"post":{"operationId":"tool_read_passages","summary":"Read passages","description":"Passages as readable text: what the player reads, and each option with where it leads, its condition (\"only if\") and its changes, in words and as formulas. Ask by IDs, by titles or by chapter; without any, the first passages of the story.","tags":["Tools"],"security":[{"apiKey":[]}],"x-effect":"reads","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"project":{"type":"string","description":"The project’s ID (from list_projects)"},"ids":{"maxItems":50,"type":"array","items":{"type":"string"}},"titles":{"maxItems":50,"type":"array","items":{"type":"string"}},"chapter":{"description":"A chapter by title or ID","type":"string"},"limit":{"default":20,"type":"integer","minimum":1,"maximum":50}},"required":["project"]}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1ToolResult"}}}},"401":{"description":"Missing, unknown, revoked or expired key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The key may not use this tool (a viewer key changes nothing; AI tools only when allowed)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such tool, or a project this key cannot use","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"The project cannot be changed now (archived, or changed at the same moment)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Invalid input (field errors in details.fields)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests for this key: try again after the seconds in Retry-After","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/tools/render_text":{"post":{"operationId":"tool_render_text","summary":"Text as the player sees it","description":"A story text (with its {tokens}) as the player would read it at the start of the game, or with a test state; optionally on a given visit of its passage (first/then, cycle texts) and with another draw of its random texts (seed).","tags":["Tools"],"security":[{"apiKey":[]}],"x-effect":"reads","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"project":{"type":"string","description":"The project’s ID (from list_projects)"},"text":{"type":"string","minLength":1,"maxLength":20000},"passage":{"description":"The passage the text is in (its ID)","type":"string"},"testState":{"description":"A test state of the project, by name or ID, to start from","type":"string","maxLength":200},"visit":{"description":"The visit of the passage to show: 1 the first, 2 the second, and on","type":"integer","minimum":1,"maximum":1000},"seed":{"description":"Draws the random texts another way: any number, the same number the same draw","type":"integer","minimum":0,"maximum":4294967295},"laterVisit":{"default":false,"description":"Older form of visit 2; visit wins when both are given","type":"boolean"}},"required":["project","text"]}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1ToolResult"}}}},"401":{"description":"Missing, unknown, revoked or expired key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The key may not use this tool (a viewer key changes nothing; AI tools only when allowed)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such tool, or a project this key cannot use","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"The project cannot be changed now (archived, or changed at the same moment)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Invalid input (field errors in details.fields)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests for this key: try again after the seconds in Retry-After","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/tools/search":{"post":{"operationId":"tool_search","summary":"Search the project","description":"Finds words in passage titles and text, option labels and the names and descriptions of values, characters, things and endings.","tags":["Tools"],"security":[{"apiKey":[]}],"x-effect":"reads","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"project":{"type":"string","description":"The project’s ID (from list_projects)"},"text":{"type":"string","minLength":1,"maxLength":200},"limit":{"default":50,"type":"integer","minimum":1,"maximum":200}},"required":["project","text"]}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1ToolResult"}}}},"401":{"description":"Missing, unknown, revoked or expired key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The key may not use this tool (a viewer key changes nothing; AI tools only when allowed)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such tool, or a project this key cannot use","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"The project cannot be changed now (archived, or changed at the same moment)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Invalid input (field errors in details.fields)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests for this key: try again after the seconds in Retry-After","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/tools/simulate_encounter":{"post":{"operationId":"tool_simulate_encounter","summary":"Simulate a battle","description":"Fights a battle (an encounter) many times with the party at the start of the game or of a test state: how often it is won, how long it takes and what is left of each bar.","tags":["Tools"],"security":[{"apiKey":[]}],"x-effect":"reads","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"project":{"type":"string","description":"The project’s ID (from list_projects)"},"encounter":{"type":"string","description":"The encounter’s ID"},"runs":{"default":200,"type":"integer","minimum":10,"maximum":1000},"testState":{"description":"A test state of the project, by name or ID, to start from","type":"string","maxLength":200}},"required":["project","encounter"]}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1ToolResult"}}}},"401":{"description":"Missing, unknown, revoked or expired key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The key may not use this tool (a viewer key changes nothing; AI tools only when allowed)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such tool, or a project this key cannot use","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"The project cannot be changed now (archived, or changed at the same moment)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Invalid input (field errors in details.fields)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests for this key: try again after the seconds in Retry-After","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/tools/story_map":{"post":{"operationId":"tool_story_map","summary":"Story map","description":"The story as a graph: passages in reading order, the ways between them (with their labels, conditions and loops), unreachable passages and groups of passages with no way out.","tags":["Tools"],"security":[{"apiKey":[]}],"x-effect":"reads","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"project":{"type":"string","description":"The project’s ID (from list_projects)"}},"required":["project"]}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1ToolResult"}}}},"401":{"description":"Missing, unknown, revoked or expired key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The key may not use this tool (a viewer key changes nothing; AI tools only when allowed)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such tool, or a project this key cannot use","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"The project cannot be changed now (archived, or changed at the same moment)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Invalid input (field errors in details.fields)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests for this key: try again after the seconds in Retry-After","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/tools/style_guide":{"post":{"operationId":"tool_style_guide","summary":"Style guide","description":"How the project’s writing and pictures should be (the style guide the creator set), with its language and game type. Follow it in everything you write or ask pictures for.","tags":["Tools"],"security":[{"apiKey":[]}],"x-effect":"reads","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"project":{"type":"string","description":"The project’s ID (from list_projects)"}},"required":["project"]}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1ToolResult"}}}},"401":{"description":"Missing, unknown, revoked or expired key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The key may not use this tool (a viewer key changes nothing; AI tools only when allowed)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such tool, or a project this key cannot use","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"The project cannot be changed now (archived, or changed at the same moment)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Invalid input (field errors in details.fields)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests for this key: try again after the seconds in Retry-After","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/tools/test_run":{"post":{"operationId":"tool_test_run","summary":"Test run","description":"Plays the game by itself: \"every_choice\" tries every way, \"random_plays\" plays many times at random. Reports endings reached, passages and options never reached, plays that got stuck and the range of each number value.","tags":["Tools"],"security":[{"apiKey":[]}],"x-effect":"reads","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"project":{"type":"string","description":"The project’s ID (from list_projects)"},"kind":{"default":"every_choice","type":"string","enum":["every_choice","random_plays"]},"runs":{"default":100,"description":"Random plays: how many","type":"integer","minimum":1,"maximum":500},"testState":{"description":"A test state of the project, by name or ID, to start from","type":"string","maxLength":200}},"required":["project"]}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1ToolResult"}}}},"401":{"description":"Missing, unknown, revoked or expired key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The key may not use this tool (a viewer key changes nothing; AI tools only when allowed)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such tool, or a project this key cannot use","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"The project cannot be changed now (archived, or changed at the same moment)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Invalid input (field errors in details.fields)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests for this key: try again after the seconds in Retry-After","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/tools/used_by":{"post":{"operationId":"tool_used_by","summary":"Used by","description":"Every place that uses an entity (a value, character, thing, passage, ending …), by its ID.","tags":["Tools"],"security":[{"apiKey":[]}],"x-effect":"reads","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"project":{"type":"string","description":"The project’s ID (from list_projects)"},"id":{"type":"string","minLength":1,"maxLength":100}},"required":["project","id"]}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1ToolResult"}}}},"401":{"description":"Missing, unknown, revoked or expired key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The key may not use this tool (a viewer key changes nothing; AI tools only when allowed)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such tool, or a project this key cannot use","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"The project cannot be changed now (archived, or changed at the same moment)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Invalid input (field errors in details.fields)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests for this key: try again after the seconds in Retry-After","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"components":{"schemas":{"Error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}},"error":{"type":"string"},"retryAfterSeconds":{"type":"integer"}},"required":["code","message"],"additionalProperties":false},"V1File":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"kind":{"type":"string","enum":["image","spritesheet","audio","video","subtitle","font"]},"status":{"type":"string","enum":["pending","validating","ready","rejected"]},"name":{"type":"string"},"alt":{"anyOf":[{"type":"string"},{"type":"null"}]},"originalFilename":{"type":"string"},"contentType":{"type":"string"},"byteSize":{"anyOf":[{"type":"integer"},{"type":"null"}]},"sha256":{"anyOf":[{"type":"string"},{"type":"null"}]},"metadata":{"type":"object","additionalProperties":{}},"rejectionReason":{"anyOf":[{"type":"string"},{"type":"null"}]},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"url":{"type":"string","format":"uri"},"urlExpiresAt":{"type":"string","format":"date-time"}},"required":["id","kind","status","name","alt","originalFilename","contentType","byteSize","sha256","metadata","rejectionReason","createdAt","updatedAt"],"additionalProperties":false},"V1FileUpload":{"type":"object","properties":{"file":{"$ref":"#/components/schemas/V1File"},"upload":{"type":"object","properties":{"url":{"type":"string","format":"uri"},"fields":{"type":"object","additionalProperties":{"type":"string"}}},"required":["url","fields"],"additionalProperties":false}},"required":["file","upload"],"additionalProperties":false},"V1Key":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"workspace":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"}},"required":["id","name"],"additionalProperties":false},"role":{"type":"string","enum":["viewer","editor"]},"projectIds":{"anyOf":[{"type":"array","items":{"type":"string","format":"uuid"}},{"type":"null"}]},"allowAi":{"type":"boolean"},"expiresAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]}},"required":["id","name","workspace","role","projectIds","allowAi","expiresAt"],"additionalProperties":false},"V1Language":{"type":"object","properties":{"main":{"type":"string"},"language":{"type":"string"},"offered":{"type":"boolean"},"rows":{"type":"array","items":{"type":"object","properties":{"address":{"type":"string"},"field":{"type":"string"},"owner":{"anyOf":[{"type":"string"},{"type":"null"}]},"main":{"type":"string"},"translation":{"anyOf":[{"type":"string"},{"type":"null"}]},"status":{"anyOf":[{"type":"string","enum":["draft","review","done"]},{"type":"null"}]},"state":{"type":"string","enum":["missing","changed","draft","review","done"]}},"required":["address","field","owner","main","translation","status","state"],"additionalProperties":false}},"gone":{"type":"array","items":{"type":"string"}}},"required":["main","language","offered","rows","gone"],"additionalProperties":false},"V1Languages":{"type":"object","properties":{"main":{"type":"string"},"languages":{"type":"array","items":{"type":"object","properties":{"language":{"type":"string"},"offered":{"type":"boolean"},"total":{"type":"integer"},"translated":{"type":"integer"},"changed":{"type":"integer"},"gone":{"type":"integer"}},"required":["language","offered","total","translated","changed","gone"],"additionalProperties":false}}},"required":["main","languages"],"additionalProperties":false},"V1Project":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"title":{"type":"string"},"description":{"type":"string"},"archived":{"type":"boolean"}},"required":["id","title","description","archived"],"additionalProperties":false},"V1Tool":{"type":"object","properties":{"name":{"type":"string"},"title":{"type":"string"},"description":{"type":"string"},"effect":{"type":"string","enum":["reads","adds","changes"]},"ai":{"type":"boolean"},"input":{"type":"object","additionalProperties":{}}},"required":["name","title","description","effect","ai","input"],"additionalProperties":false},"V1ToolArguments":{"type":"object","additionalProperties":{}},"V1ToolResult":{"type":"object","properties":{"tool":{"type":"string"},"projectId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"result":{"type":"string"}},"required":["tool","projectId","result"],"additionalProperties":false},"V1TranslationsWrite":{"type":"object","properties":{"rows":{"type":"array","items":{"type":"object","properties":{"address":{"type":"string","minLength":1,"maxLength":300},"text":{"type":"string","maxLength":20000},"status":{"type":"string","enum":["draft","review","done"]},"main":{"type":"string","maxLength":20000}},"required":["address","text"],"additionalProperties":false}},"csv":{"type":"string","maxLength":1000000},"hidden":{"type":"boolean"}},"additionalProperties":false},"V1TranslationsWritten":{"type":"object","properties":{"revision":{"type":"integer"},"read":{"type":"integer"},"skipped":{"type":"integer"},"changed":{"type":"integer"},"hidden":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"problems":{"type":"array","items":{"type":"object","properties":{"severity":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"},"pointer":{"type":"string"}},"required":["severity","code","message","pointer"],"additionalProperties":false}}},"required":["revision","read","skipped","changed","hidden","problems"],"additionalProperties":false}},"securitySchemes":{"apiKey":{"type":"http","scheme":"bearer","description":"A key of the workspace (tb_…), made in Workspace settings → API keys; sent as Authorization: Bearer tb_…"}}},"servers":[{"url":"https://app.talebench.com"}]}