{ "openapi": "3.1.0", "info": { "title": "presentation-services API", "description": "Create, review, and render presentations through a typed REST API.\n\n## Outline review to rendered deck\n\n1. `POST /outlines` with a prompt or uploaded-file sources.\n2. Edit the returned `outline` JSON. The `PresentationOutline` contract permits\n reordering, adding, removing, or rewriting slides before a deck is created.\n3. `POST /decks` with the edited object in `outline` and a unique `Request-Id`.\n An authored outline skips outline generation and proceeds through slides and export.\n4. Poll the returned `status_url` until `status` is `COMPLETED` or `FAILED`. On success,\n `export.download_url` points to the finished artifact.\n\n`POST /decks` is asynchronous by default (`202 Accepted`). Reusing the same `Request-Id`\nwith the same body is a safe retry. Changing the body under that ID returns\n`REQUEST_ID_CONFLICT`.\n\n## Errors\n\nHTTP failures use one JSON envelope: `{\"error\":{\"code\",\"message\",\"details\",\"trace_id\"}}`.\n`details` and `trace_id` are optional. Validation failures use `VALIDATION_FAILED` and put\nfield issues in `error.details.errors`. Rate limits return `RATE_LIMITED` with\n`Retry-After` and `X-RateLimit-*` headers. Include `trace_id` in support requests.\n\nGeneration can also fail after a successful `202`. That terminal failure appears on the\nrequest resource as `status: \"FAILED\"` with a sanitized `error` string.\n", "version": "0.0.0" }, "servers": [ { "url": "/api/v1" } ], "paths": { "/me": { "get": { "tags": [ "me" ], "summary": "Me", "description": "Resolve the API key's user, workspace/project scope, and effective permissions.", "operationId": "me_me_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/APIPrincipal" } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "security": [ { "HTTPBearer": [] } ] } }, "/api-keys/current": { "delete": { "tags": [ "api-keys" ], "summary": "Revoke Current Key", "description": "Permanently revoke the Bearer API key authenticating this request.", "operationId": "revoke_current_key_api_keys_current_delete", "responses": { "204": { "description": "Successful Response" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "security": [ { "HTTPBearer": [] } ] } }, "/workspace": { "get": { "tags": [ "workspace" ], "summary": "Get Workspace", "description": "Return the workspace bound to the current API key.", "operationId": "get_workspace_workspace_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Workspace" } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "security": [ { "HTTPBearer": [] } ] } }, "/members": { "get": { "tags": [ "members" ], "summary": "List Members", "description": "List workspace members with contact details and current roles.", "operationId": "list_members_members_get", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "default": 1, "title": "Page" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 200, "minimum": 1, "default": 200, "title": "Limit" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Page_Member_" } } } }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/members/{user_id}": { "patch": { "tags": [ "members" ], "summary": "Patch Member", "description": "Change a workspace member's role; an admin-capable key is required.", "operationId": "patch_member_members__user_id__patch", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "user_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "User Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateMemberRoleRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Member" } } } }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "delete": { "tags": [ "members" ], "summary": "Remove Member", "description": "Remove a member and revoke every API key issued for that membership.", "operationId": "remove_member_members__user_id__delete", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "user_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "User Id" } } ], "responses": { "204": { "description": "Successful Response" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/projects": { "get": { "tags": [ "projects" ], "summary": "List Projects", "description": "List accessible projects; a project-bound key sees only its bound project.", "operationId": "list_projects_projects_get", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "default": 1, "title": "Page" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 200, "minimum": 1, "default": 200, "title": "Limit" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Page_Project_" } } } }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" } } }, "post": { "tags": [ "projects" ], "summary": "Create Project", "description": "Create a workspace project when the caller's plan and key allow it.", "operationId": "create_project_projects_post", "security": [ { "HTTPBearer": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateProjectRequest" } } } }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Project" } } } }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/projects/{project_id}": { "get": { "tags": [ "projects" ], "summary": "Get Project", "description": "Fetch one project after enforcing workspace, key-scope, and read access.", "operationId": "get_project_projects__project_id__get", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Project Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Project" } } } }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "patch": { "tags": [ "projects" ], "summary": "Patch Project", "description": "Update a project's name, slug, or default member role.", "operationId": "patch_project_projects__project_id__patch", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Project Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateProjectRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Project" } } } }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/brand-kits": { "get": { "tags": [ "brand-kits" ], "summary": "Search Brand Kits", "description": "Search the brand kits you can style a deck with; pass a result's `id` to `POST /decks`.\n\nIncludes published brands, your workspace's kits and your own unshared kits. A brand limited to\napproved email domains appears only when your verified email domain is one of them.", "operationId": "search_brand_kits_brand_kits_get", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "q", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 100 }, { "type": "null" } ], "description": "Brand name or domain to search for.", "title": "Q" }, "description": "Brand name or domain to search for." }, { "name": "domain", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 255 }, { "type": "null" } ], "description": "Exact brand domain, e.g. `acme.com`.", "title": "Domain" }, "description": "Exact brand domain, e.g. `acme.com`." }, { "name": "type", "in": "query", "required": false, "schema": { "anyOf": [ { "$ref": "#/components/schemas/KitType" }, { "type": "null" } ], "description": "Only catalog brands, or only your workspace's kits.", "title": "Type" }, "description": "Only catalog brands, or only your workspace's kits." }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "default": 1, "title": "Page" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 100, "minimum": 1, "default": 20, "title": "Limit" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Page_BrandKitMatch_" } } } }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/brand-kits/{brand_kit_id}": { "get": { "tags": [ "brand-kits" ], "summary": "Get Brand Kit", "description": "Get one brand kit you can style a deck with.", "operationId": "get_brand_kit_brand_kits__brand_kit_id__get", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "brand_kit_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Brand Kit Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BrandKitDetail" } } } }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/decks": { "get": { "tags": [ "decks" ], "summary": "List Decks", "description": "List accessible decks with project, flag, sort, search, and pagination filters.\n\nDecks that have no slides yet (generation still running, or never completed)\nare omitted; fetch those by id.", "operationId": "list_decks_decks_get", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "project_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "title": "Project Id" } }, { "name": "flag", "in": "query", "required": false, "schema": { "anyOf": [ { "$ref": "#/components/schemas/DeckFlagType" }, { "type": "null" } ], "title": "Flag" } }, { "name": "sort", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/DeckSort", "default": "RECENT" } }, { "name": "search", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Search" } }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "default": 1, "title": "Page" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 200, "minimum": 1, "default": 50, "title": "Limit" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Page_Deck_" } } } }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" } } }, "post": { "tags": [ "decks" ], "summary": "Create a deck and generate it through final export", "description": "Create a deck and run supplied content through final export.\n\nA request with generation inputs requires `Request-Id`, returns 202 +\nLocation by default, and accepts `Prefer: wait=N` up to 180 seconds. Supply\neither a prompt and/or typed document sources, or a complete authored\noutline. Authored outlines skip outline generation but still run slides and\nexport. Same-ID/different-body returns a rich 409 suggesting a\nversion-suffixed request ID.", "operationId": "create_deck_decks_post", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "Request-Id", "in": "header", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 255, "pattern": "^[A-Za-z0-9][A-Za-z0-9._:~-]{0,254}$", "description": "Required caller request ID; reuse it to safely retry this create.", "title": "Request-Id" }, "description": "Required caller request ID; reuse it to safely retry this create." }, { "name": "Prefer", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 32, "pattern": "^\\s*wait=\\d+\\s*$" }, { "type": "null" } ], "description": "Optional bounded generation wait: `wait=N`, where N is 0-180.", "title": "Prefer" }, "description": "Optional bounded generation wait: `wait=N`, where N is 0-180." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateDeckRequest" }, "examples": { "prompt": { "summary": "Generate a deck directly from a prompt", "value": { "name": "Launch plan", "prompt": "Explain our launch plan to sales leadership.", "slide_count": "10", "export_format": "PPTX" } }, "reviewedOutline": { "summary": "Render a caller-edited outline", "description": "Pass the edited `outline` returned by POST /outlines. This skips outline generation and runs slides plus export.", "value": { "name": "Q3 customer review", "outline": { "documentTitle": "Q3 customer review", "hook": "Retention improved while expansion revenue became the next constraint.", "slides": [ { "heading": "Q3 in one minute", "description": "Revenue, retention, and the two decisions needed from the board.", "visualComposition": [ "metric", "metric", "metric" ] }, { "heading": "Expansion is the next growth lever", "description": "Segment expansion by customer cohort and identify the largest gap.", "speakerNotes": "Call out the enterprise cohort before discussing actions.", "visualComposition": [ "bar-chart", "text" ] } ] }, "export_format": "PPTX" } } } } } }, "responses": { "201": { "description": "Generation became terminal during the requested bounded wait.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeneratedDeckResponse" }, "examples": { "generationCompleted": { "summary": "Generation completed during the requested bounded wait", "value": { "request_id": "q3-customer-review-v1", "deck_id": "dc2d4f8d-a52a-4c58-aeb8-02b4d1dc9001", "status": "COMPLETED", "stage": "COMPLETED", "status_url": "https://api.presentations.ai/api/v1/requests/q3-customer-review-v1", "error": null, "created_at": "2026-08-14T09:30:00Z", "updated_at": "2026-08-14T09:31:42Z", "warnings": [], "export": { "id": "7ec2d749-85dc-4e02-8bf2-76b663d5c002", "deck_id": "dc2d4f8d-a52a-4c58-aeb8-02b4d1dc9001", "format": "PPTX", "content_type": "application/vnd.openxmlformats-officedocument.presentationml.presentation", "size_bytes": 1843200, "download_url": "https://api.presentations.ai/api/v1/exports/7ec2d749-85dc-4e02-8bf2-76b663d5c002/download?token=example", "created_at": "2026-08-14T09:31:42Z" } } } } } }, "headers": { "Location": { "description": "Stable root-relative URL of the generation request.", "schema": { "type": "string", "format": "uri-reference" } }, "Preference-Applied": { "description": "Present only when a bounded wait was requested.", "schema": { "type": "string", "pattern": "^wait=(?:0|[1-9]\\d?|1[0-7]\\d|180)$" } } } }, "202": { "description": "Deck generation accepted; poll the returned request URL.", "headers": { "Location": { "description": "Stable root-relative URL of the generation request.", "schema": { "type": "string", "format": "uri-reference" } }, "Preference-Applied": { "description": "Present only when a bounded wait was requested.", "schema": { "type": "string", "pattern": "^wait=(?:0|[1-9]\\d?|1[0-7]\\d|180)$" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeneratedDeckResponse" }, "examples": { "generationAccepted": { "summary": "Generation accepted and safe to poll", "value": { "request_id": "q3-customer-review-v1", "deck_id": "dc2d4f8d-a52a-4c58-aeb8-02b4d1dc9001", "status": "RUNNING", "stage": "SLIDES", "status_url": "https://api.presentations.ai/api/v1/requests/q3-customer-review-v1", "error": null, "created_at": "2026-08-14T09:30:00Z", "updated_at": "2026-08-14T09:30:04Z", "warnings": [], "export": null } } } } } }, "400": { "description": "Invalid bounded-wait duration.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/APIErrorResponse" } } } }, "401": { "description": "Authentication failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/APIErrorResponse" } } } }, "402": { "description": "The workspace has insufficient generation credits.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/APIErrorResponse" } } } }, "403": { "description": "The caller or workspace plan cannot create the deck.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/APIErrorResponse" } } } }, "404": { "description": "A referenced source file does not exist in the caller's workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/APIErrorResponse" } } } }, "409": { "description": "Request-ID conflict or source files are not ready.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/RequestIdConflictResponse" }, { "$ref": "#/components/schemas/APIErrorResponse" } ], "title": "Response 409 Create Deck Decks Post" } } } }, "422": { "description": "A header or request-body field failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestValidationErrorResponse" } } } }, "500": { "$ref": "#/components/responses/InternalError" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/decks/stream": { "post": { "tags": [ "decks" ], "summary": "Create a deck and stream bounded generation status", "description": "Create or replay a durable deck generation and stream bounded status.\n\nThis is the streaming transport for the same idempotent operation as\n`POST /decks`. Disconnecting or reaching the wait bound never cancels the\ngeneration; callers resume through the emitted `request.status_url`.", "operationId": "stream_deck_generation_decks_stream_post", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "wait", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 180, "minimum": 0, "description": "Seconds to stream request status before detaching (0-180).", "default": 180, "title": "Wait" }, "description": "Seconds to stream request status before detaching (0-180)." }, { "name": "Request-Id", "in": "header", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 255, "pattern": "^[A-Za-z0-9][A-Za-z0-9._:~-]{0,254}$", "description": "Caller request ID shared with POST /decks retries.", "title": "Request-Id" }, "description": "Caller request ID shared with POST /decks retries." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateDeckRequest" } } } }, "responses": { "200": { "description": "Strict accepted and request-status events. A detached event means durable generation is still running and should be polled at its status URL.", "content": { "text/event-stream": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/DeckStreamAccepted" }, { "$ref": "#/components/schemas/DeckStreamStatus" }, { "$ref": "#/components/schemas/DeckStreamDetached" } ], "discriminator": { "propertyName": "type", "mapping": { "accepted": "#/components/schemas/DeckStreamAccepted", "status": "#/components/schemas/DeckStreamStatus", "detached": "#/components/schemas/DeckStreamDetached" } }, "title": "Response Stream Deck Generation Decks Stream Post" } } } }, "401": { "description": "Authentication failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/APIErrorResponse" } } } }, "402": { "description": "The workspace has insufficient generation credits.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/APIErrorResponse" } } } }, "403": { "description": "The caller or workspace plan cannot create the deck.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/APIErrorResponse" } } } }, "404": { "description": "A referenced source file does not exist in the caller's workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/APIErrorResponse" } } } }, "409": { "description": "Request-ID conflict or source files are not ready.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/RequestIdConflictResponse" }, { "$ref": "#/components/schemas/APIErrorResponse" } ] } } } }, "422": { "description": "A header, query, or request-body field failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestValidationErrorResponse" } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/decks/{deck_id}": { "get": { "tags": [ "decks" ], "summary": "Get Deck", "description": "Fetch deck metadata, latest generation status, and existing export artifacts.", "operationId": "get_deck_decks__deck_id__get", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "deck_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Deck Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeckDetailResponse" } } } }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "patch": { "tags": [ "decks" ], "summary": "Patch Deck", "description": "Update deck metadata without starting generation or creating an export.", "operationId": "patch_deck_decks__deck_id__patch", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "deck_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Deck Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateDeckRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Deck" } } } }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "delete": { "tags": [ "decks" ], "summary": "Delete Deck", "description": "Soft-delete a deck; the operation is idempotent for an already deleted deck.", "operationId": "delete_deck_decks__deck_id__delete", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "deck_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Deck Id" } } ], "responses": { "204": { "description": "Successful Response" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/decks/{deck_id}/flags/{flag}": { "put": { "tags": [ "decks" ], "summary": "Set Deck Flag", "description": "Set a user-private organizational flag such as starred or archived.", "operationId": "set_deck_flag_decks__deck_id__flags__flag__put", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "deck_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Deck Id" } }, { "name": "flag", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/DeckFlagType" } } ], "responses": { "204": { "description": "Successful Response" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "delete": { "tags": [ "decks" ], "summary": "Unset Deck Flag", "description": "Remove one user-private organizational flag from a deck.", "operationId": "unset_deck_flag_decks__deck_id__flags__flag__delete", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "deck_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Deck Id" } }, { "name": "flag", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/DeckFlagType" } } ], "responses": { "204": { "description": "Successful Response" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/decks/{deck_id}/thumbnail": { "get": { "tags": [ "decks" ], "summary": "Get Deck Thumbnail", "description": "Stream the current JPEG thumbnail; return 404 until one is available.", "operationId": "get_deck_thumbnail_decks__deck_id__thumbnail_get", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "deck_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Deck Id" } }, { "name": "width", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Stored size to serve (see `thumbnails`); the largest by default.", "title": "Width" }, "description": "Stored size to serve (see `thumbnails`); the largest by default." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/decks/{deck_id}/exports": { "get": { "tags": [ "decks" ], "summary": "List Deck Exports External", "description": "Most-recent-first export artifacts for a deck.", "operationId": "list_deck_exports_external_decks__deck_id__exports_get", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "deck_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Deck Id" } }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "default": 1, "title": "Page" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 200, "minimum": 1, "default": 200, "title": "Limit" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Page_ExternalDeckExportResponse_" } } } }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/decks/{deck_id}/exports/{export_id}/content": { "get": { "tags": [ "decks" ], "summary": "Get Deck Export Content External", "description": "Stream a produced export artifact.", "operationId": "get_deck_export_content_external_decks__deck_id__exports__export_id__content_get", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "deck_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Deck Id" } }, { "name": "export_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Export Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/decks/outline/stream": { "post": { "tags": [ "decks" ], "summary": "Legacy stateless outline stream", "description": "Compatibility stream; use `POST /outlines` for JSON or SSE output.", "operationId": "stream_outline_external_decks_outline_stream_post", "deprecated": true, "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "accept-language", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Accept-Language" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OutlineStreamRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "text/event-stream": { "itemSchema": { "type": "object", "properties": { "data": { "type": "string", "contentMediaType": "application/json", "contentSchema": { "type": "object", "additionalProperties": true, "title": "Streamitem Stream Outline External Decks Outline Stream Post" } }, "event": { "type": "string" }, "id": { "type": "string" }, "retry": { "type": "integer", "minimum": 0 } }, "required": [ "data" ] } } } }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/decks/{deck_id}/outline": { "get": { "tags": [ "decks" ], "summary": "Get Deck Outline External", "description": "Durable outline state for a generated deck.", "operationId": "get_deck_outline_external_decks__deck_id__outline_get", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "deck_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Deck Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeckOutline" } } } }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/decks/slides": { "post": { "tags": [ "decks" ], "summary": "Generate Slide External", "description": "Stateless single-slide fill from a caller-picked variation \u2014 the v8 fill.\n\n`graphics_xml` (the v8 writer's structured graphics) is the content when given \u2014 the\nsame fill the app runs for v8 decks; otherwise `heading` + `description` are the content\nfor the v8 add-slide fill, which fills the picked variation's elements from plain text.\n\nCosts one generated slide's credits, refunded if the fill fails. Send an\n`Idempotency-Key` to retry safely: a key that already paid is a 409.", "operationId": "generate_slide_external_decks_slides_post", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Idempotency-Key" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SlideFillRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeneratedSlide" } } } }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/decks/slides/change": { "post": { "tags": [ "decks" ], "summary": "Change Slide External", "description": "Stateless transform of slide content onto a different graphic type \u2014 the v8 change fill.", "operationId": "change_slide_external_decks_slides_change_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SlideChangeV8Request" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeneratedSlide" } } } }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "security": [ { "HTTPBearer": [] } ] } }, "/decks/{deck_id}/grants": { "post": { "tags": [ "decks" ], "summary": "Create Grant External", "description": "Create or update a grant on a deck.", "operationId": "create_grant_external_decks__deck_id__grants_post", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "deck_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Deck Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeckGrantCreate" } } } }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeckGrantResponse" } } } }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "get": { "tags": [ "decks" ], "summary": "List Grants External", "description": "List all active grants on a deck.", "operationId": "list_grants_external_decks__deck_id__grants_get", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "deck_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Deck Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/DeckGrantResponse" }, "title": "Response List Grants External Decks Deck Id Grants Get" } } } }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/decks/{deck_id}/grants/{grant_id}": { "patch": { "tags": [ "decks" ], "summary": "Update Grant External", "description": "Update the role on a deck grant.", "operationId": "update_grant_external_decks__deck_id__grants__grant_id__patch", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "grant_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Grant Id" } }, { "name": "deck_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Deck Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeckGrantUpdate" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeckGrantResponse" } } } }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "delete": { "tags": [ "decks" ], "summary": "Delete Grant External", "description": "Delete a deck grant.", "operationId": "delete_grant_external_decks__deck_id__grants__grant_id__delete", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "grant_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Grant Id" } }, { "name": "deck_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Deck Id" } } ], "responses": { "204": { "description": "Successful Response" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/decks/{deck_id}/share-link": { "get": { "tags": [ "decks" ], "summary": "Get Share Link External", "description": "Fetch the deck's active share link URL; 404 if link sharing is off.", "operationId": "get_share_link_external_decks__deck_id__share_link_get", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "deck_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Deck Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShareLink" } } } }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "post": { "tags": [ "decks" ], "summary": "Create Share Link External", "description": "Enable the deck's share link and return its URL.\n\nReuses the existing link so the URL is stable; pass `rotate=true` to mint a\nfresh token (the previous URL stops working).", "operationId": "create_share_link_external_decks__deck_id__share_link_post", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "deck_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Deck Id" } }, { "name": "rotate", "in": "query", "required": false, "schema": { "type": "boolean", "default": false, "title": "Rotate" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShareLink" } } } }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "delete": { "tags": [ "decks" ], "summary": "Delete Share Link External", "description": "Disable link-sharing for the deck.", "operationId": "delete_share_link_external_decks__deck_id__share_link_delete", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "deck_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Deck Id" } } ], "responses": { "204": { "description": "Successful Response" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/outlines": { "post": { "tags": [ "outlines" ], "summary": "Generate an outline without creating a deck", "description": "Generate a stateless outline from a prompt and/or extracted files.\n\nNo deck, session, or generation request is persisted. Referenced files must belong to the\ncaller's workspace and have completed extraction before this request.", "operationId": "create_outline_outlines_post", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "accept-language", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Accept-Language" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateOutlineRequest" }, "examples": { "prompt": { "summary": "Generate a reviewable outline from a prompt", "value": { "prompt": "Turn the Q3 results into a concise board update.", "slide_count": "8", "level_of_detail": "standard" } }, "uploadedFile": { "summary": "Generate from an uploaded source file", "value": { "prompt": "Focus on retention changes and decisions required.", "sources": [ { "type": "file", "file_id": "f1f11b7e-5e9a-4a3e-8e66-08b49a8ea001" } ] } } } } } }, "responses": { "200": { "description": "A completed, strictly typed JSON outline.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateOutlineResponse" }, "examples": { "reviewableOutline": { "summary": "Typed outline ready for caller edits", "value": { "outline": { "documentTitle": "Q3 customer review", "hook": "Retention improved while expansion revenue became the next constraint.", "slides": [ { "heading": "Q3 in one minute", "description": "Revenue, retention, and the two decisions needed from the board.", "visualComposition": [ "metric", "metric", "metric" ] }, { "heading": "Expansion is the next growth lever", "description": "Segment expansion by customer cohort and identify the largest gap.", "speakerNotes": "Call out the enterprise cohort before discussing actions.", "visualComposition": [ "bar-chart", "text" ] } ] } } } } } } }, "400": { "description": "The referenced files contain no extracted text.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/APIErrorResponse" } } } }, "404": { "description": "A referenced file does not exist in the caller's workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/APIErrorResponse" } } } }, "409": { "description": "One or more referenced files are still being extracted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/APIErrorResponse" } } } }, "422": { "description": "A request field failed validation, or the prompt, source text and files together exceed the plan's content limit (CONTENT_TOO_LONG).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/APIErrorResponse" } } } }, "502": { "description": "Outline generation failed before producing a valid outline.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/APIErrorResponse" } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/outlines/stream": { "post": { "tags": [ "outlines" ], "summary": "Stream an outline without creating a deck", "description": "Stream the same stateless operation exposed by `POST /outlines`.", "operationId": "stream_outline_response_outlines_stream_post", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "accept-language", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Accept-Language" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateOutlineRequest" } } } }, "responses": { "200": { "description": "Strict discriminated outline events encoded as SSE data frames.", "content": { "text/event-stream": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/OutlineStreamStarted" }, { "$ref": "#/components/schemas/OutlineStreamDelta" }, { "$ref": "#/components/schemas/OutlineStreamCompleted" }, { "$ref": "#/components/schemas/OutlineStreamFailed" } ], "discriminator": { "propertyName": "type", "mapping": { "started": "#/components/schemas/OutlineStreamStarted", "delta": "#/components/schemas/OutlineStreamDelta", "completed": "#/components/schemas/OutlineStreamCompleted", "failed": "#/components/schemas/OutlineStreamFailed" } }, "title": "Response Stream Outline Response Outlines Stream Post" } } } }, "400": { "description": "The referenced files contain no extracted text.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/APIErrorResponse" } } } }, "404": { "description": "A referenced file does not exist in the caller's workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/APIErrorResponse" } } } }, "409": { "description": "One or more referenced files are still being extracted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/APIErrorResponse" } } } }, "422": { "description": "A header or request-body field failed validation, or the prompt, source text and files together exceed the plan's content limit (CONTENT_TOO_LONG).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/APIErrorResponse" } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/files": { "post": { "tags": [ "files" ], "summary": "Upload File", "description": "Upload a file and enqueue extraction.", "operationId": "upload_file_files_post", "requestBody": { "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/Body_upload_file_files_post" } } }, "required": true }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExternalFileResponse" } } } }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "security": [ { "HTTPBearer": [] } ] } }, "/files/{file_id}": { "get": { "tags": [ "files" ], "summary": "Get File", "description": "Get file metadata and extraction status.", "operationId": "get_file_files__file_id__get", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "file_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "File Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExternalFileStatusResponse" } } } }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "delete": { "tags": [ "files" ], "summary": "Delete File", "description": "Delete an uploaded file and any extraction state, including a hung extraction.", "operationId": "delete_file_files__file_id__delete", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "file_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "File Id" } } ], "responses": { "204": { "description": "Successful Response" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/requests/{request_id}": { "get": { "tags": [ "requests" ], "summary": "Get Generation Request", "description": "Get deck-generation status by the caller's request ID.", "operationId": "get_generation_request_requests__request_id__get", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "request_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 255, "pattern": "^[A-Za-z0-9][A-Za-z0-9._:~-]{0,254}$", "title": "Request Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeckGenerationRequestResponse" }, "examples": { "completed": { "summary": "Rendered deck and export are ready", "value": { "request_id": "q3-customer-review-v1", "deck_id": "dc2d4f8d-a52a-4c58-aeb8-02b4d1dc9001", "status": "COMPLETED", "stage": "COMPLETED", "status_url": "https://api.presentations.ai/api/v1/requests/q3-customer-review-v1", "error": null, "created_at": "2026-08-14T09:30:00Z", "updated_at": "2026-08-14T09:31:42Z", "warnings": [], "export": { "id": "7ec2d749-85dc-4e02-8bf2-76b663d5c002", "deck_id": "dc2d4f8d-a52a-4c58-aeb8-02b4d1dc9001", "format": "PPTX", "content_type": "application/vnd.openxmlformats-officedocument.presentationml.presentation", "size_bytes": 1843200, "download_url": "https://api.presentations.ai/api/v1/exports/7ec2d749-85dc-4e02-8bf2-76b663d5c002/download?token=example", "created_at": "2026-08-14T09:31:42Z" } } }, "failed": { "summary": "Terminal asynchronous failure", "value": { "request_id": "q3-customer-review-v1", "deck_id": "dc2d4f8d-a52a-4c58-aeb8-02b4d1dc9001", "status": "FAILED", "stage": "FAILED", "status_url": "https://api.presentations.ai/api/v1/requests/q3-customer-review-v1", "error": "Slide generation failed after retries.", "created_at": "2026-08-14T09:30:00Z", "updated_at": "2026-08-14T09:31:10Z", "warnings": [], "export": null } } } } } }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/credits": { "get": { "tags": [ "credits" ], "summary": "Get Credit Balance", "description": "Return the workspace's total, reserved, consumed, and available credits.", "operationId": "get_credit_balance_credits_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreditBalance" } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "security": [ { "HTTPBearer": [] } ] } }, "/usage": { "get": { "tags": [ "usage" ], "summary": "Get Usage", "description": "Return requests, success rate, durations and credits for this key.", "operationId": "get_usage_usage_get", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "since", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Since" } }, { "name": "until", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Until" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/APIUsageSummary" } } } }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/usage/requests": { "get": { "tags": [ "usage" ], "summary": "List Usage Requests", "description": "List the deck-generation requests this key made, newest first.", "operationId": "list_usage_requests_usage_requests_get", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "since", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Since" } }, { "name": "until", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Until" } }, { "name": "status", "in": "query", "required": false, "schema": { "anyOf": [ { "$ref": "#/components/schemas/AsyncTaskStatus" }, { "type": "null" } ], "title": "Status" } }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "default": 1, "title": "Page" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 200, "minimum": 1, "default": 50, "title": "Limit" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Page_APIUsageRequest_" } } } }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/objects/{object_path}": { "get": { "tags": [ "objects" ], "summary": "Get Public Object", "description": "Stream an allowlisted public object.", "operationId": "get_public_object_objects__object_path__get", "parameters": [ { "name": "object_path", "in": "path", "required": true, "schema": { "type": "string", "title": "Object Path" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/exports/{export_id}/download": { "get": { "tags": [ "exports" ], "summary": "Download Export", "description": "Stream an export artifact for a valid, unexpired signed token.\n\n`variant=animated` serves the animated PPTX build.", "operationId": "download_export_exports__export_id__download_get", "parameters": [ { "name": "export_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Export Id" } }, { "name": "token", "in": "query", "required": true, "schema": { "type": "string", "title": "Token" } }, { "name": "variant", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Variant" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "404": { "$ref": "#/components/responses/NotFound" } } } } }, "components": { "schemas": { "APIError": { "properties": { "code": { "type": "string", "enum": [ "BAD_REQUEST", "CONFLICT", "FEATURE_NOT_IN_PLAN", "FEATURE_UNAVAILABLE", "FORBIDDEN", "HTTP_ERROR", "IDEMPOTENCY_CONFLICT", "INSUFFICIENT_CREDITS", "INTERNAL_ERROR", "INVALID_TOKEN", "NOT_FOUND", "PLAN_LIMIT_EXCEEDED", "RATE_LIMITED", "REQUEST_ID_CONFLICT", "SOURCES_NOT_READY", "UNAUTHENTICATED", "UPSTREAM_ERROR", "VALIDATION_FAILED" ], "title": "Code", "description": "Stable machine-readable error code; branch client behavior on this value." }, "message": { "type": "string", "minLength": 1, "title": "Message", "description": "Sanitized human-readable explanation; wording may evolve." }, "details": { "anyOf": [ { "additionalProperties": { "$ref": "#/components/schemas/JsonValue" }, "type": "object" }, { "type": "null" } ], "title": "Details", "description": "Optional code-specific structured context, never required for display." }, "trace_id": { "anyOf": [ { "type": "string", "maxLength": 32, "minLength": 32 }, { "type": "null" } ], "title": "Trace Id", "description": "Trace identifier to include when reporting an unexpected failure." } }, "additionalProperties": false, "type": "object", "required": [ "code", "message" ], "title": "APIError", "description": "Standard external API error payload." }, "APIErrorResponse": { "properties": { "error": { "$ref": "#/components/schemas/APIError" } }, "additionalProperties": false, "type": "object", "required": [ "error" ], "title": "APIErrorResponse", "description": "Standard external API error envelope.", "examples": [ { "error": { "code": "NOT_FOUND", "message": "Deck not found.", "trace_id": "4bf92f3577b34da6a3ce929d0e0e4736" } }, { "error": { "code": "RATE_LIMITED", "message": "Too many requests." } } ] }, "APIPrincipal": { "properties": { "user_id": { "type": "string", "format": "uuid", "title": "User Id" }, "email": { "type": "string", "format": "email", "title": "Email" }, "workspace_id": { "type": "string", "format": "uuid", "title": "Workspace Id" }, "project_id": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "title": "Project Id" }, "api_key_id": { "type": "string", "format": "uuid", "title": "Api Key Id" }, "role_at_issuance": { "$ref": "#/components/schemas/WorkspaceRole" }, "scopes": { "items": { "type": "string" }, "type": "array", "title": "Scopes" }, "permissions": { "items": { "$ref": "#/components/schemas/Capability" }, "type": "array", "title": "Permissions" } }, "additionalProperties": false, "type": "object", "required": [ "user_id", "email", "workspace_id", "project_id", "api_key_id", "role_at_issuance", "scopes", "permissions" ], "title": "APIPrincipal", "description": "Caller identity returned by the API `/me` endpoint." }, "APIUsageFeature": { "properties": { "feature": { "type": "string", "title": "Feature" }, "credits": { "type": "integer", "title": "Credits" }, "uses": { "type": "integer", "title": "Uses" } }, "additionalProperties": false, "type": "object", "required": [ "feature", "credits", "uses" ], "title": "APIUsageFeature", "description": "Credits one feature consumed." }, "APIUsageKey": { "properties": { "api_key_id": { "type": "string", "format": "uuid", "title": "Api Key Id" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Name" }, "prefix": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Prefix" }, "requests": { "type": "integer", "title": "Requests" }, "credits_consumed": { "type": "integer", "title": "Credits Consumed" } }, "additionalProperties": false, "type": "object", "required": [ "api_key_id", "name", "prefix", "requests", "credits_consumed" ], "title": "APIUsageKey", "description": "One key's share of the usage." }, "APIUsageRequest": { "properties": { "task_id": { "type": "string", "format": "uuid", "title": "Task Id" }, "request_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Request Id" }, "api_key_id": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "title": "Api Key Id" }, "deck_id": { "type": "string", "format": "uuid", "title": "Deck Id" }, "status": { "$ref": "#/components/schemas/AsyncTaskStatus" }, "stage": { "anyOf": [ { "$ref": "#/components/schemas/GenerationStage" }, { "type": "null" } ] }, "created_at": { "type": "string", "format": "date-time", "title": "Created At" }, "finished_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Finished At" }, "duration_seconds": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Duration Seconds" }, "credits_consumed": { "type": "integer", "title": "Credits Consumed" }, "error": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Error" } }, "additionalProperties": false, "type": "object", "required": [ "task_id", "request_id", "api_key_id", "deck_id", "status", "stage", "created_at", "finished_at", "duration_seconds", "credits_consumed", "error" ], "title": "APIUsageRequest", "description": "One deck-generation request made with an API key." }, "APIUsageRequestCounts": { "properties": { "total": { "type": "integer", "title": "Total" }, "completed": { "type": "integer", "title": "Completed" }, "failed": { "type": "integer", "title": "Failed" }, "in_progress": { "type": "integer", "title": "In Progress" } }, "additionalProperties": false, "type": "object", "required": [ "total", "completed", "failed", "in_progress" ], "title": "APIUsageRequestCounts", "description": "Deck-generation requests by lifecycle outcome." }, "APIUsageSummary": { "properties": { "workspace_id": { "type": "string", "format": "uuid", "title": "Workspace Id" }, "api_key_id": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "title": "Api Key Id" }, "since": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Since" }, "until": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Until" }, "requests": { "$ref": "#/components/schemas/APIUsageRequestCounts" }, "success_rate": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Success Rate" }, "avg_duration_seconds": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Avg Duration Seconds" }, "credits_consumed": { "type": "integer", "title": "Credits Consumed" }, "by_feature": { "items": { "$ref": "#/components/schemas/APIUsageFeature" }, "type": "array", "title": "By Feature" }, "by_key": { "items": { "$ref": "#/components/schemas/APIUsageKey" }, "type": "array", "title": "By Key" } }, "additionalProperties": false, "type": "object", "required": [ "workspace_id", "api_key_id", "since", "until", "requests", "success_rate", "avg_duration_seconds", "credits_consumed", "by_feature", "by_key" ], "title": "APIUsageSummary", "description": "Usage over a window, for one key or for every key in scope." }, "AsyncTaskStatus": { "type": "string", "enum": [ "CREATED", "RUNNING", "COMPLETED", "FAILED" ], "title": "AsyncTaskStatus", "description": "Lifecycle state of an async task." }, "Body_upload_file_files_post": { "properties": { "file": { "type": "string", "contentMediaType": "application/octet-stream", "title": "File" } }, "type": "object", "required": [ "file" ], "title": "Body_upload_file_files_post" }, "BrandKitDetail": { "properties": { "id": { "type": "string", "format": "uuid", "title": "Id", "description": "Pass as `brand_kit_id` to `POST /decks`." }, "name": { "type": "string", "title": "Name", "description": "The brand." }, "domain": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Domain", "description": "The brand's domain; null for generic style kits." }, "type": { "$ref": "#/components/schemas/KitType", "description": "CATALOG: a published brand. WORKSPACE: one of your workspace's kits. PERSONAL: your own kit, shared with no workspace." }, "access": { "$ref": "#/components/schemas/KitAccess", "description": "Why you can see it. PUBLIC: open to everyone. DOMAIN: limited to approved email domains, and yours is one. WORKSPACE: your workspace's kit. OWNER: your own kit." }, "logo_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Logo Url", "description": "The brand mark, when the kit has one." }, "colors": { "items": { "type": "string" }, "type": "array", "title": "Colors", "description": "Brand colours as hex." }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description" }, "fonts": { "anyOf": [ { "$ref": "#/components/schemas/BrandKitFonts" }, { "type": "null" } ], "description": "Default heading/body font families, when set." }, "default_mood": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Default Mood", "description": "The kit's default mood, when it has one you may use." } }, "additionalProperties": false, "type": "object", "required": [ "id", "name", "type", "access" ], "title": "BrandKitDetail", "description": "One brand kit, with what it styles a deck with." }, "BrandKitFonts": { "properties": { "heading": { "type": "string", "title": "Heading" }, "body": { "type": "string", "title": "Body" } }, "additionalProperties": false, "type": "object", "required": [ "heading", "body" ], "title": "BrandKitFonts", "description": "The kit's default heading and body font families." }, "BrandKitMatch": { "properties": { "id": { "type": "string", "format": "uuid", "title": "Id", "description": "Pass as `brand_kit_id` to `POST /decks`." }, "name": { "type": "string", "title": "Name", "description": "The brand." }, "domain": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Domain", "description": "The brand's domain; null for generic style kits." }, "type": { "$ref": "#/components/schemas/KitType", "description": "CATALOG: a published brand. WORKSPACE: one of your workspace's kits. PERSONAL: your own kit, shared with no workspace." }, "access": { "$ref": "#/components/schemas/KitAccess", "description": "Why you can see it. PUBLIC: open to everyone. DOMAIN: limited to approved email domains, and yours is one. WORKSPACE: your workspace's kit. OWNER: your own kit." }, "logo_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Logo Url", "description": "The brand mark, when the kit has one." }, "colors": { "items": { "type": "string" }, "type": "array", "title": "Colors", "description": "Brand colours as hex." } }, "additionalProperties": false, "type": "object", "required": [ "id", "name", "type", "access" ], "title": "BrandKitMatch", "description": "One brand kit the caller may style a deck with." }, "Capability": { "type": "string", "enum": [ "workspace.read", "workspace.write", "workspace.delete", "ownership.transfer", "billing.manage", "billing.read", "payment_method.manage", "purchases.create", "sso.manage", "audit.read", "activity.read", "activity.update", "members.read", "members.write", "invites.manage", "apikeys.manage", "brand_kit.read", "brand_kit.manage", "brand_assets.read", "brand_assets.manage", "company.read", "company.manage", "credits.view", "credits.manage", "projects.read", "projects.create", "project.write", "project.delete", "project.members.read", "project.members.write", "project.knowledge.read", "project.knowledge.write", "project.knowledge.manage", "deck.create", "deck.read", "deck.write", "deck.delete", "deck.comment", "deck.share.manage", "deck.analytics.read", "joinrequests.manage", "mcp.tools.list", "mcp.tools.invoke", "mcp.resources.list", "mcp.resources.read", "mcp.prompts.list", "mcp.prompts.get" ], "title": "Capability", "description": "Fine-grained permission checked on every authorized action." }, "CreateDeckRequest": { "oneOf": [ { "anyOf": [ { "required": [ "deck_title" ] }, { "required": [ "prompt" ] }, { "required": [ "sources" ] }, { "required": [ "source_text" ] }, { "required": [ "file_ids" ] } ], "not": { "required": [ "outline" ] }, "title": "Prompt or document input" }, { "not": { "anyOf": [ { "required": [ "prompt" ] }, { "required": [ "sources" ] }, { "required": [ "source_text" ] }, { "required": [ "file_ids" ] } ] }, "properties": { "outline": { "not": { "type": "null" } } }, "required": [ "outline" ], "title": "Authored outline input" } ], "properties": { "prompt": { "anyOf": [ { "type": "string", "maxLength": 200000, "minLength": 1 }, { "type": "null" } ], "title": "Prompt" }, "sources": { "anyOf": [ { "items": { "oneOf": [ { "$ref": "#/components/schemas/TextSource" }, { "$ref": "#/components/schemas/FileSource" } ], "discriminator": { "propertyName": "type", "mapping": { "file": "#/components/schemas/FileSource", "text": "#/components/schemas/TextSource" } } }, "type": "array", "maxItems": 100, "minItems": 1 }, { "type": "null" } ], "title": "Sources", "description": "Inline text and/or references to files uploaded through POST /files." }, "source_text": { "anyOf": [ { "type": "string", "maxLength": 200000, "minLength": 1 }, { "type": "null" } ], "title": "Source Text", "description": "Deprecated inline-source field; use a text entry in sources.", "deprecated": true }, "file_ids": { "anyOf": [ { "items": { "type": "string", "format": "uuid" }, "type": "array", "maxItems": 100 }, { "type": "null" } ], "title": "File Ids", "description": "Deprecated uploaded-file field; use file entries in sources.", "deprecated": true }, "name": { "type": "string", "maxLength": 255, "minLength": 1, "title": "Name", "default": "Untitled Presentation" }, "visibility": { "$ref": "#/components/schemas/DeckVisibility", "default": "WORKSPACE" }, "project_id": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "title": "Project Id" }, "deck_title": { "anyOf": [ { "type": "string", "maxLength": 255, "minLength": 1 }, { "type": "null" } ], "title": "Deck Title" }, "outline": { "anyOf": [ { "$ref": "#/components/schemas/PresentationOutline" }, { "type": "null" } ] }, "company": { "anyOf": [ { "type": "string", "maxLength": 200 }, { "type": "null" } ], "title": "Company" }, "creator_role": { "anyOf": [ { "type": "string", "maxLength": 1000 }, { "type": "null" } ], "title": "Creator Role" }, "model": { "$ref": "#/components/schemas/DeckGenerationModel", "default": "STANDARD" }, "language": { "type": "string", "maxLength": 100, "minLength": 1, "title": "Language", "default": "English" }, "slide_count": { "anyOf": [ { "type": "string", "pattern": "^(auto|\\d{1,3}(-\\d{1,3})?|\\d{1,3}\\+)$" }, { "type": "null" } ], "title": "Slide Count" }, "level_of_detail": { "anyOf": [ { "$ref": "#/components/schemas/DeckLevelOfDetail" }, { "type": "null" } ] }, "insider_content": { "anyOf": [ { "type": "string", "maxLength": 200000 }, { "type": "null" } ], "title": "Insider Content" }, "export_format": { "$ref": "#/components/schemas/DeckExportFormat", "default": "PPTX" }, "audience": { "anyOf": [ { "type": "string", "maxLength": 200 }, { "type": "null" } ], "title": "Audience", "description": "Who the deck is for. Omitted: inferred from the prompt and sources, never asked back (the API run has no questions)." }, "deck_purpose": { "anyOf": [ { "type": "string", "maxLength": 64 }, { "type": "null" } ], "title": "Deck Purpose", "description": "Purpose id from the deck purpose taxonomy: pitch, sales, marketing, strategy, report, training, teaching, coursework, product, research, security, general." }, "brand_kit_id": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "title": "Brand Kit Id", "description": "Style the deck as a brand: an `id` from `GET /brand-kits`. Omitted: no brand kit." }, "deep_search": { "type": "boolean", "title": "Deep Search", "description": "Consultant-grade research and exhibit slides (paid plans; DEEP_SEARCH_OUTLINE credits per slide). Not applicable to an authored outline.", "default": false } }, "additionalProperties": false, "type": "object", "title": "CreateDeckRequest", "description": "Create a deck and optionally run generation through final export.\n\nThe run covers outline -> slides -> export. `source_text` is raw text used\nas source material, equivalent to an attached document but with no upload\nor extraction step. Files-only generates from the attached documents;\nextraction must have completed (409 otherwise).\n\nA caller-authored `outline` skips outline generation and runs the supplied\nstructure directly through slides and export. It cannot be combined with a\nprompt or document sources. Use `POST /outlines` for stateless preview and\nreview before creating a deck.\n\nAt least one generation input is required. Omitted name defaults to a\nplaceholder, replaced by the requested or authored title when available." }, "CreateOutlineRequest": { "anyOf": [ { "properties": { "prompt": { "not": { "type": "null" } } }, "required": [ "prompt" ] }, { "properties": { "sources": { "not": { "type": "null" } } }, "required": [ "sources" ] }, { "properties": { "source_text": { "not": { "type": "null" } } }, "required": [ "source_text" ] }, { "properties": { "file_ids": { "not": { "type": "null" } } }, "required": [ "file_ids" ] } ], "properties": { "prompt": { "anyOf": [ { "type": "string", "maxLength": 200000, "minLength": 1 }, { "type": "null" } ], "title": "Prompt" }, "sources": { "anyOf": [ { "items": { "oneOf": [ { "$ref": "#/components/schemas/TextSource" }, { "$ref": "#/components/schemas/FileSource" } ], "discriminator": { "propertyName": "type", "mapping": { "file": "#/components/schemas/FileSource", "text": "#/components/schemas/TextSource" } } }, "type": "array", "maxItems": 100, "minItems": 1 }, { "type": "null" } ], "title": "Sources", "description": "Inline text and/or references to files uploaded through POST /files." }, "source_text": { "anyOf": [ { "type": "string", "maxLength": 200000, "minLength": 1 }, { "type": "null" } ], "title": "Source Text", "description": "Deprecated inline-source field; use a text entry in sources.", "deprecated": true }, "file_ids": { "anyOf": [ { "items": { "type": "string", "format": "uuid" }, "type": "array", "maxItems": 100 }, { "type": "null" } ], "title": "File Ids", "description": "Deprecated uploaded-file field; use file entries in sources.", "deprecated": true }, "language": { "type": "string", "maxLength": 100, "minLength": 1, "title": "Language", "default": "English" }, "slide_count": { "anyOf": [ { "type": "string", "maxLength": 32 }, { "type": "null" } ], "title": "Slide Count" }, "level_of_detail": { "anyOf": [ { "type": "string", "enum": [ "brief", "standard", "detailed", "very_detailed" ] }, { "type": "null" } ], "title": "Level Of Detail" } }, "additionalProperties": false, "type": "object", "title": "CreateOutlineRequest", "description": "Generate an outline without creating or mutating a deck." }, "CreateOutlineResponse": { "properties": { "outline": { "$ref": "#/components/schemas/PresentationOutline" } }, "additionalProperties": false, "type": "object", "required": [ "outline" ], "title": "CreateOutlineResponse", "description": "Completed stateless outline generation." }, "CreateProjectRequest": { "properties": { "name": { "type": "string", "maxLength": 120, "minLength": 1, "title": "Name" }, "default_member_role": { "$ref": "#/components/schemas/ProjectRole", "default": "EDITOR" } }, "additionalProperties": false, "type": "object", "required": [ "name" ], "title": "CreateProjectRequest", "description": "Create a new project in a workspace." }, "CreditBalance": { "properties": { "workspace_id": { "type": "string", "format": "uuid", "title": "Workspace Id" }, "available": { "type": "integer", "title": "Available" }, "active_granted": { "type": "integer", "title": "Active Granted" }, "total_consumed": { "type": "integer", "title": "Total Consumed" }, "active_holds": { "type": "integer", "title": "Active Holds" } }, "additionalProperties": false, "type": "object", "required": [ "workspace_id", "available", "active_granted", "total_consumed", "active_holds" ], "title": "CreditBalance", "description": "Workspace credit balance summary." }, "Deck": { "properties": { "id": { "type": "string", "format": "uuid", "title": "Id" }, "workspace_id": { "type": "string", "format": "uuid", "title": "Workspace Id" }, "project_id": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "title": "Project Id" }, "source_deck_id": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "title": "Source Deck Id" }, "legacy_deck_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Legacy Deck Id" }, "created_by": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "title": "Created By" }, "name": { "type": "string", "title": "Name" }, "visibility": { "$ref": "#/components/schemas/DeckVisibility" }, "thumbnail_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Thumbnail Url" }, "thumbnails": { "items": { "$ref": "#/components/schemas/Thumbnail" }, "type": "array", "title": "Thumbnails", "description": "Every stored size of the same render, largest first (`thumbnails[0]` is `thumbnail_url`). Empty until the first render." }, "has_share_link": { "type": "boolean", "title": "Has Share Link", "default": false }, "archived_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Archived At" }, "deleted_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Deleted At" }, "created_at": { "type": "string", "format": "date-time", "title": "Created At" }, "updated_at": { "type": "string", "format": "date-time", "title": "Updated At" }, "flags": { "items": { "$ref": "#/components/schemas/DeckFlagType" }, "type": "array", "title": "Flags" }, "version": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Version", "description": "Active content version: v1 | v2 | null (authored in-app)", "examples": [ "v1" ] }, "origin_version": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Origin Version", "description": "Version this deck was migrated from; null if authored in-app.", "examples": [ "v1" ] }, "permissions": { "anyOf": [ { "$ref": "#/components/schemas/DeckPermissions" }, { "type": "null" } ] }, "shared_with_me": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Shared With Me" } }, "additionalProperties": false, "type": "object", "required": [ "id", "workspace_id", "project_id", "created_by", "name", "visibility", "archived_at", "created_at", "updated_at" ], "title": "Deck", "description": "Deck response shape." }, "DeckDetailResponse": { "properties": { "id": { "type": "string", "format": "uuid", "title": "Id" }, "workspace_id": { "type": "string", "format": "uuid", "title": "Workspace Id" }, "project_id": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "title": "Project Id" }, "source_deck_id": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "title": "Source Deck Id" }, "legacy_deck_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Legacy Deck Id" }, "created_by": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "title": "Created By" }, "name": { "type": "string", "title": "Name" }, "visibility": { "$ref": "#/components/schemas/DeckVisibility" }, "thumbnail_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Thumbnail Url" }, "thumbnails": { "items": { "$ref": "#/components/schemas/Thumbnail" }, "type": "array", "title": "Thumbnails", "description": "Every stored size of the same render, largest first (`thumbnails[0]` is `thumbnail_url`). Empty until the first render." }, "has_share_link": { "type": "boolean", "title": "Has Share Link", "default": false }, "archived_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Archived At" }, "deleted_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Deleted At" }, "created_at": { "type": "string", "format": "date-time", "title": "Created At" }, "updated_at": { "type": "string", "format": "date-time", "title": "Updated At" }, "flags": { "items": { "$ref": "#/components/schemas/DeckFlagType" }, "type": "array", "title": "Flags" }, "version": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Version", "description": "Active content version: v1 | v2 | null (authored in-app)", "examples": [ "v1" ] }, "origin_version": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Origin Version", "description": "Version this deck was migrated from; null if authored in-app.", "examples": [ "v1" ] }, "permissions": { "anyOf": [ { "$ref": "#/components/schemas/DeckPermissions" }, { "type": "null" } ] }, "shared_with_me": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Shared With Me" }, "status": { "anyOf": [ { "$ref": "#/components/schemas/AsyncTaskStatus" }, { "type": "null" } ] }, "exports": { "items": { "$ref": "#/components/schemas/ExternalDeckExportResponse" }, "type": "array", "title": "Exports", "description": "Previously produced artifacts with download URLs. This read never queues or creates an export." } }, "additionalProperties": false, "type": "object", "required": [ "id", "workspace_id", "project_id", "created_by", "name", "visibility", "thumbnail_url", "thumbnails", "archived_at", "created_at", "updated_at", "status", "exports" ], "title": "DeckDetailResponse", "description": "Deck metadata plus its latest generation state and previously produced artifacts." }, "DeckExportFormat": { "type": "string", "enum": [ "PPTX", "PDF", "IMAGE" ], "title": "DeckExportFormat", "description": "Artifact format produced by the converter (PPTX) or the renderer (PDF/IMAGE)." }, "DeckFlagType": { "type": "string", "enum": [ "STARRED" ], "title": "DeckFlagType", "description": "Kinds of per-user deck flag." }, "DeckGenerationModel": { "type": "string", "enum": [ "STANDARD", "PRO", "ULTRA" ], "title": "DeckGenerationModel", "description": "User-selected generation model tier." }, "DeckGenerationRequestResponse": { "properties": { "request_id": { "type": "string", "maxLength": 255, "minLength": 1, "title": "Request Id", "description": "Caller request ID used to safely replay this deck creation." }, "deck_id": { "type": "string", "format": "uuid", "title": "Deck Id" }, "status": { "$ref": "#/components/schemas/AsyncTaskStatus", "description": "Durable lifecycle state for this request." }, "stage": { "$ref": "#/components/schemas/GenerationStage", "description": "Current generation stage for progress display." }, "status_url": { "type": "string", "minLength": 1, "format": "uri", "title": "Status Url", "description": "Canonical URL to poll for this request." }, "error": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Error", "description": "Sanitized terminal failure message; non-null only when status is FAILED." }, "created_at": { "type": "string", "format": "date-time", "title": "Created At" }, "updated_at": { "type": "string", "format": "date-time", "title": "Updated At" }, "warnings": { "items": { "$ref": "#/components/schemas/TaskWarning" }, "type": "array", "title": "Warnings", "description": "Nonterminal degradations encountered while generation continued." }, "export": { "anyOf": [ { "$ref": "#/components/schemas/ExternalDeckExportResponse" }, { "type": "null" } ], "description": "Finished artifact; non-null after successful export persistence." } }, "additionalProperties": false, "type": "object", "required": [ "request_id", "deck_id", "status", "stage", "status_url", "error", "created_at", "updated_at" ], "title": "DeckGenerationRequestResponse", "description": "Public generation lifecycle keyed only by request ID and deck ID." }, "DeckGrantCreate": { "properties": { "subject": { "type": "string", "maxLength": 255, "minLength": 1, "title": "Subject" }, "role": { "$ref": "#/components/schemas/DeckGrantRole" }, "workspace_role": { "anyOf": [ { "$ref": "#/components/schemas/WorkspaceRole" }, { "type": "null" } ] } }, "additionalProperties": false, "type": "object", "required": [ "subject", "role" ], "title": "DeckGrantCreate", "description": "Create or update a per-deck grant." }, "DeckGrantResponse": { "properties": { "id": { "type": "string", "format": "uuid", "title": "Id" }, "deck_id": { "type": "string", "format": "uuid", "title": "Deck Id" }, "subject_type": { "$ref": "#/components/schemas/DeckGrantSubjectType" }, "subject_user_id": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "title": "Subject User Id" }, "subject_email": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Subject Email" }, "subject": { "anyOf": [ { "$ref": "#/components/schemas/UserInfo" }, { "type": "null" } ] }, "role": { "$ref": "#/components/schemas/DeckGrantRole" }, "granted_by": { "type": "string", "format": "uuid", "title": "Granted By" }, "created_at": { "type": "string", "format": "date-time", "title": "Created At" }, "membership_status": { "anyOf": [ { "type": "string", "enum": [ "member", "non_member", "pending_request", "invited" ] }, { "type": "null" } ], "title": "Membership Status" }, "workspace_role": { "anyOf": [ { "$ref": "#/components/schemas/WorkspaceRole" }, { "type": "null" } ] } }, "additionalProperties": false, "type": "object", "required": [ "id", "deck_id", "subject_type", "role", "granted_by", "created_at" ], "title": "DeckGrantResponse", "description": "Wire representation of a DeckGrant." }, "DeckGrantRole": { "type": "string", "enum": [ "VIEW", "COMMENT", "EDIT" ], "title": "DeckGrantRole", "description": "Per-deck grant role for sharing decks independently of project membership." }, "DeckGrantSubjectType": { "type": "string", "enum": [ "USER", "EMAIL" ], "title": "DeckGrantSubjectType", "description": "What kind of subject a deck grant targets." }, "DeckGrantUpdate": { "properties": { "role": { "anyOf": [ { "$ref": "#/components/schemas/DeckGrantRole" }, { "type": "null" } ] } }, "additionalProperties": false, "type": "object", "title": "DeckGrantUpdate", "description": "Partial update of a deck grant." }, "DeckLevelOfDetail": { "type": "string", "enum": [ "BRIEF", "STANDARD", "DETAILED", "VERY_DETAILED" ], "title": "DeckLevelOfDetail", "description": "Requested outline density." }, "DeckOutline": { "properties": { "deck_id": { "type": "string", "format": "uuid", "title": "Deck Id" }, "deck_session_id": { "type": "string", "format": "uuid", "title": "Deck Session Id" }, "status": { "$ref": "#/components/schemas/DeckSessionStatus" }, "outline": { "anyOf": [ { "$ref": "#/components/schemas/PresentationOutline" }, { "type": "null" } ] }, "final_outline": { "anyOf": [ { "$ref": "#/components/schemas/PresentationOutline" }, { "type": "null" } ] } }, "additionalProperties": false, "type": "object", "required": [ "deck_id", "deck_session_id", "status" ], "title": "DeckOutline", "description": "Durable outline state for a generated deck." }, "DeckPermissions": { "properties": { "workspace_role": { "anyOf": [ { "$ref": "#/components/schemas/WorkspaceRole" }, { "type": "null" } ] }, "project_role": { "anyOf": [ { "$ref": "#/components/schemas/ProjectRole" }, { "type": "null" } ] }, "deck_grant_role": { "anyOf": [ { "$ref": "#/components/schemas/DeckGrantRole" }, { "type": "null" } ] }, "is_creator": { "type": "boolean", "title": "Is Creator" }, "capabilities": { "items": { "$ref": "#/components/schemas/Capability" }, "type": "array", "title": "Capabilities" } }, "additionalProperties": false, "type": "object", "required": [ "workspace_role", "project_role", "deck_grant_role", "is_creator", "capabilities" ], "title": "DeckPermissions", "description": "Caller's resolved access to one deck." }, "DeckSessionStatus": { "type": "string", "enum": [ "DRAFT", "OUTLINE_FINALIZED" ], "title": "DeckSessionStatus", "description": "Deck-generation lifecycle state." }, "DeckSort": { "type": "string", "enum": [ "RECENT", "NAME", "UPDATED", "CREATED" ], "title": "DeckSort", "description": "Ordering for the deck list query." }, "DeckStreamAccepted": { "properties": { "type": { "type": "string", "const": "accepted", "title": "Type", "default": "accepted" }, "deck": { "$ref": "#/components/schemas/GeneratedDeckResponse" } }, "additionalProperties": false, "type": "object", "required": [ "deck" ], "title": "DeckStreamAccepted", "description": "Deck generation was durably accepted." }, "DeckStreamDetached": { "properties": { "type": { "type": "string", "const": "detached", "title": "Type", "default": "detached" }, "request": { "$ref": "#/components/schemas/DeckGenerationRequestResponse" }, "message": { "type": "string", "title": "Message", "default": "stream wait elapsed; continue polling request.status_url" } }, "additionalProperties": false, "type": "object", "required": [ "request" ], "title": "DeckStreamDetached", "description": "The bounded stream ended while durable generation continues." }, "DeckStreamStatus": { "properties": { "type": { "type": "string", "const": "status", "title": "Type", "default": "status" }, "request": { "$ref": "#/components/schemas/DeckGenerationRequestResponse" } }, "additionalProperties": false, "type": "object", "required": [ "request" ], "title": "DeckStreamStatus", "description": "Current durable generation request status." }, "DeckVisibility": { "type": "string", "enum": [ "PROJECT", "PRIVATE", "WORKSPACE", "PUBLIC" ], "title": "DeckVisibility", "description": "Default access mode for a deck." }, "ExternalDeckExportResponse": { "properties": { "id": { "type": "string", "format": "uuid", "title": "Id" }, "deck_id": { "type": "string", "format": "uuid", "title": "Deck Id" }, "format": { "$ref": "#/components/schemas/DeckExportFormat" }, "content_type": { "type": "string", "title": "Content Type" }, "size_bytes": { "type": "integer", "title": "Size Bytes" }, "download_url": { "type": "string", "title": "Download Url" }, "created_at": { "type": "string", "format": "date-time", "title": "Created At" } }, "additionalProperties": false, "type": "object", "required": [ "id", "deck_id", "format", "content_type", "size_bytes", "download_url", "created_at" ], "title": "ExternalDeckExportResponse", "description": "External export artifact projection." }, "ExternalFileResponse": { "properties": { "file_id": { "type": "string", "format": "uuid", "title": "File Id" }, "filename": { "type": "string", "title": "Filename" }, "status": { "$ref": "#/components/schemas/AsyncTaskStatus" }, "created_at": { "type": "string", "format": "date-time", "title": "Created At" } }, "additionalProperties": false, "type": "object", "required": [ "file_id", "filename", "status", "created_at" ], "title": "ExternalFileResponse", "description": "External upload response keyed only by file ID." }, "ExternalFileStatusResponse": { "properties": { "file_id": { "type": "string", "format": "uuid", "title": "File Id" }, "filename": { "type": "string", "title": "Filename" }, "status": { "anyOf": [ { "$ref": "#/components/schemas/AsyncTaskStatus" }, { "type": "null" } ] }, "error": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Error" }, "size_bytes": { "type": "integer", "title": "Size Bytes" }, "content_type": { "type": "string", "title": "Content Type" }, "char_count": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Char Count" }, "content_sha256": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Content Sha256" }, "extracted_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Extracted At" }, "created_at": { "type": "string", "format": "date-time", "title": "Created At" } }, "additionalProperties": false, "type": "object", "required": [ "file_id", "filename", "status", "error", "size_bytes", "content_type", "char_count", "content_sha256", "extracted_at", "created_at" ], "title": "ExternalFileStatusResponse", "description": "External file metadata and extraction status keyed only by file ID." }, "FileSource": { "properties": { "type": { "type": "string", "const": "file", "title": "Type" }, "file_id": { "type": "string", "format": "uuid", "title": "File Id" } }, "additionalProperties": false, "type": "object", "required": [ "type", "file_id" ], "title": "FileSource", "description": "Reference to a source document previously uploaded through `/files`." }, "GeneratedDeckResponse": { "properties": { "request_id": { "type": "string", "maxLength": 255, "minLength": 1, "title": "Request Id", "description": "Caller request ID used to safely replay this deck creation." }, "deck_id": { "type": "string", "format": "uuid", "title": "Deck Id" }, "status": { "$ref": "#/components/schemas/AsyncTaskStatus", "description": "Durable lifecycle state for this request." }, "stage": { "$ref": "#/components/schemas/GenerationStage", "description": "Current generation stage for progress display." }, "status_url": { "type": "string", "minLength": 1, "format": "uri", "title": "Status Url", "description": "Canonical URL to poll for this request." }, "error": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Error", "description": "Sanitized terminal failure message; non-null only when status is FAILED." }, "created_at": { "type": "string", "format": "date-time", "title": "Created At" }, "updated_at": { "type": "string", "format": "date-time", "title": "Updated At" }, "warnings": { "items": { "$ref": "#/components/schemas/TaskWarning" }, "type": "array", "title": "Warnings", "description": "Nonterminal degradations encountered while generation continued." }, "export": { "anyOf": [ { "$ref": "#/components/schemas/ExternalDeckExportResponse" }, { "type": "null" } ], "description": "Finished artifact; non-null after successful export persistence." } }, "additionalProperties": false, "type": "object", "required": [ "request_id", "deck_id", "status", "stage", "status_url", "error", "created_at", "updated_at" ], "title": "GeneratedDeckResponse", "description": "Accepted deck generation.\n\nCarries no viewer URL: creating a deck never shares it. A public link is\nopt-in through `POST /decks/{deck_id}/share-link`." }, "GeneratedSlide": { "properties": { "variation_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Variation Name" }, "data": { "additionalProperties": true, "type": "object", "title": "Data" } }, "additionalProperties": false, "type": "object", "required": [ "data" ], "title": "GeneratedSlide", "description": "Stateless slide-generation result (external API \u2014 not persisted)." }, "GenerationStage": { "type": "string", "enum": [ "QUEUED", "OUTLINE", "SLIDES", "EXPORT", "COMPLETED", "FAILED", "ENRICHING", "SCRAPING", "ANALYZING", "GENERATING_VISUALS", "SAVING" ], "title": "GenerationStage", "description": "Durable, caller-visible deck-generation stage." }, "JsonValue": {}, "KitAccess": { "type": "string", "enum": [ "PUBLIC", "DOMAIN", "WORKSPACE", "OWNER" ], "title": "KitAccess", "description": "Why the caller can see a kit." }, "KitType": { "type": "string", "enum": [ "CATALOG", "WORKSPACE", "PERSONAL" ], "title": "KitType", "description": "Where a visible kit comes from." }, "Member": { "properties": { "workspace_id": { "type": "string", "format": "uuid", "title": "Workspace Id" }, "user_id": { "type": "string", "format": "uuid", "title": "User Id" }, "display_name": { "type": "string", "title": "Display Name" }, "email": { "type": "string", "format": "email", "title": "Email" }, "user": { "$ref": "#/components/schemas/UserContact" }, "role": { "$ref": "#/components/schemas/WorkspaceRole" }, "joined_at": { "type": "string", "format": "date-time", "title": "Joined At" } }, "additionalProperties": false, "type": "object", "required": [ "workspace_id", "user_id", "display_name", "email", "user", "role", "joined_at" ], "title": "Member", "description": "Workspace member response.\n\n`user_id`/`display_name`/`email` duplicate `user` for wire compatibility." }, "OutlineGraphic": { "properties": { "type": { "type": "string", "maxLength": 100, "minLength": 1, "title": "Type" }, "heading": { "anyOf": [ { "type": "string", "maxLength": 300 }, { "type": "null" } ], "title": "Heading" }, "items": { "anyOf": [ { "items": { "$ref": "#/components/schemas/OutlineGraphicItem" }, "type": "array", "maxItems": 30 }, { "type": "null" } ], "title": "Items" }, "rows": { "anyOf": [ { "items": { "type": "string", "maxLength": 2000, "minLength": 1 }, "type": "array", "maxItems": 50 }, { "type": "null" } ], "title": "Rows" }, "extra": { "anyOf": [ { "items": { "$ref": "#/components/schemas/OutlineGraphicItem" }, "type": "array", "maxItems": 4 }, { "type": "null" } ], "title": "Extra" }, "callout": { "anyOf": [ { "type": "string", "maxLength": 300 }, { "type": "null" } ], "title": "Callout" }, "stamp": { "anyOf": [ { "type": "string", "maxLength": 40 }, { "type": "null" } ], "title": "Stamp" }, "footnote": { "anyOf": [ { "type": "string", "maxLength": 600 }, { "type": "null" } ], "title": "Footnote" }, "ref": { "anyOf": [ { "$ref": "#/components/schemas/OutlineRef" }, { "type": "null" } ] }, "highlight": { "anyOf": [ { "$ref": "#/components/schemas/OutlineHighlight" }, { "type": "null" } ] } }, "additionalProperties": false, "type": "object", "required": [ "type" ], "title": "OutlineGraphic", "description": "One typed body graphic on a v8 outline slide.\n\n`type` may carry a subtype suffix (e.g. ``diagram:process``). Tables use\n`rows` (pipe-separated cells, first row = headers) instead of `items`." }, "OutlineGraphicItem": { "properties": { "h": { "anyOf": [ { "type": "string", "maxLength": 2000 }, { "type": "null" } ], "title": "H" }, "b": { "anyOf": [ { "type": "string", "maxLength": 5000 }, { "type": "null" } ], "title": "B" }, "v": { "anyOf": [ { "type": "string", "maxLength": 200 }, { "type": "null" } ], "title": "V" }, "s": { "anyOf": [ { "type": "string", "maxLength": 500 }, { "type": "null" } ], "title": "S" }, "i": { "anyOf": [ { "type": "string", "maxLength": 100 }, { "type": "null" } ], "title": "I" }, "sub": { "anyOf": [ { "items": { "type": "string", "maxLength": 2000, "minLength": 1 }, "type": "array", "maxItems": 20 }, { "type": "null" } ], "title": "Sub" }, "tags": { "anyOf": [ { "items": { "type": "string", "maxLength": 80, "minLength": 1 }, "type": "array", "maxItems": 6 }, { "type": "null" } ], "title": "Tags" }, "metric": { "anyOf": [ { "type": "string", "maxLength": 200 }, { "type": "null" } ], "title": "Metric" }, "entity": { "anyOf": [ { "type": "string", "maxLength": 200 }, { "type": "null" } ], "title": "Entity" }, "entityDomain": { "anyOf": [ { "type": "string", "maxLength": 200 }, { "type": "null" } ], "title": "Entitydomain" }, "trend": { "anyOf": [ { "type": "string", "maxLength": 40 }, { "type": "null" } ], "title": "Trend" }, "status": { "anyOf": [ { "type": "string", "maxLength": 60 }, { "type": "null" } ], "title": "Status" }, "delta": { "anyOf": [ { "type": "string", "maxLength": 160 }, { "type": "null" } ], "title": "Delta" }, "period": { "anyOf": [ { "type": "string", "maxLength": 160 }, { "type": "null" } ], "title": "Period" } }, "additionalProperties": false, "type": "object", "title": "OutlineGraphicItem", "description": "One content item inside a v8 structured graphic.\n\nMirrors the v8 writer's item contract: `h` head/label, `b` body/explanation,\n`v` value (kpi/chart datum), `s` source/role (quotes), `i` icon hint\n(direct-build), `sub` sub-bullets." }, "OutlineHighlight": { "properties": { "kind": { "anyOf": [ { "type": "string", "maxLength": 20 }, { "type": "null" } ], "title": "Kind" }, "at": { "anyOf": [ { "type": "string", "maxLength": 200 }, { "type": "null" } ], "title": "At" }, "text": { "anyOf": [ { "type": "string", "maxLength": 300 }, { "type": "null" } ], "title": "Text" } }, "additionalProperties": false, "type": "object", "title": "OutlineHighlight", "description": "The one element of a graphic the heading rests on (`why`)." }, "OutlineRef": { "properties": { "label": { "anyOf": [ { "type": "string", "maxLength": 120 }, { "type": "null" } ], "title": "Label" }, "v": { "anyOf": [ { "type": "string", "maxLength": 80 }, { "type": "null" } ], "title": "V" } }, "additionalProperties": false, "type": "object", "title": "OutlineRef", "description": "A benchmark/target line a chart should show (``)." }, "OutlineSource": { "properties": { "domain": { "anyOf": [ { "type": "string", "maxLength": 200 }, { "type": "null" } ], "title": "Domain" }, "text": { "anyOf": [ { "type": "string", "maxLength": 300 }, { "type": "null" } ], "title": "Text" }, "url": { "anyOf": [ { "type": "string", "maxLength": 2000 }, { "type": "null" } ], "title": "Url" } }, "additionalProperties": false, "type": "object", "title": "OutlineSource", "description": "One slide-level source chip (`Publisher, period`)." }, "OutlineStreamCompleted": { "properties": { "type": { "type": "string", "const": "completed", "title": "Type", "default": "completed" }, "outline": { "$ref": "#/components/schemas/PresentationOutline" } }, "additionalProperties": false, "type": "object", "required": [ "outline" ], "title": "OutlineStreamCompleted", "description": "Terminal successful outline event." }, "OutlineStreamDelta": { "properties": { "type": { "type": "string", "const": "delta", "title": "Type", "default": "delta" }, "delta": { "type": "string", "minLength": 1, "title": "Delta" } }, "additionalProperties": false, "type": "object", "required": [ "delta" ], "title": "OutlineStreamDelta", "description": "Incremental generated outline text." }, "OutlineStreamFailed": { "properties": { "type": { "type": "string", "const": "failed", "title": "Type", "default": "failed" }, "message": { "type": "string", "minLength": 1, "title": "Message" } }, "additionalProperties": false, "type": "object", "required": [ "message" ], "title": "OutlineStreamFailed", "description": "Terminal failed outline event." }, "OutlineStreamRequest": { "properties": { "deck_title": { "type": "string", "maxLength": 255, "minLength": 1, "title": "Deck Title" }, "language": { "type": "string", "maxLength": 100, "minLength": 1, "title": "Language", "default": "English" }, "slide_count": { "anyOf": [ { "type": "string", "maxLength": 32 }, { "type": "null" } ], "title": "Slide Count" }, "level_of_detail": { "anyOf": [ { "type": "string", "enum": [ "brief", "standard", "detailed", "very_detailed" ] }, { "type": "null" } ], "title": "Level Of Detail" }, "outline_prompt_variant": { "anyOf": [ { "type": "string", "maxLength": 64 }, { "type": "null" } ], "title": "Outline Prompt Variant" } }, "additionalProperties": false, "type": "object", "required": [ "deck_title" ], "title": "OutlineStreamRequest", "description": "Single-shot outline generation from a deck title. Stateless \u2014 persists nothing." }, "OutlineStreamStarted": { "properties": { "type": { "type": "string", "const": "started", "title": "Type", "default": "started" } }, "additionalProperties": false, "type": "object", "title": "OutlineStreamStarted", "description": "Outline generation started." }, "Page_APIUsageRequest_": { "properties": { "data": { "items": { "$ref": "#/components/schemas/APIUsageRequest" }, "type": "array", "title": "Data" }, "page": { "type": "integer", "title": "Page" }, "limit": { "type": "integer", "title": "Limit" }, "total": { "type": "integer", "title": "Total" } }, "additionalProperties": false, "type": "object", "required": [ "data", "page", "limit", "total" ], "title": "Page[APIUsageRequest]" }, "Page_BrandKitMatch_": { "properties": { "data": { "items": { "$ref": "#/components/schemas/BrandKitMatch" }, "type": "array", "title": "Data" }, "page": { "type": "integer", "title": "Page" }, "limit": { "type": "integer", "title": "Limit" }, "total": { "type": "integer", "title": "Total" } }, "additionalProperties": false, "type": "object", "required": [ "data", "page", "limit", "total" ], "title": "Page[BrandKitMatch]" }, "Page_Deck_": { "properties": { "data": { "items": { "$ref": "#/components/schemas/Deck" }, "type": "array", "title": "Data" }, "page": { "type": "integer", "title": "Page" }, "limit": { "type": "integer", "title": "Limit" }, "total": { "type": "integer", "title": "Total" } }, "additionalProperties": false, "type": "object", "required": [ "data", "page", "limit", "total" ], "title": "Page[Deck]" }, "Page_ExternalDeckExportResponse_": { "properties": { "data": { "items": { "$ref": "#/components/schemas/ExternalDeckExportResponse" }, "type": "array", "title": "Data" }, "page": { "type": "integer", "title": "Page" }, "limit": { "type": "integer", "title": "Limit" }, "total": { "type": "integer", "title": "Total" } }, "additionalProperties": false, "type": "object", "required": [ "data", "page", "limit", "total" ], "title": "Page[ExternalDeckExportResponse]" }, "Page_Member_": { "properties": { "data": { "items": { "$ref": "#/components/schemas/Member" }, "type": "array", "title": "Data" }, "page": { "type": "integer", "title": "Page" }, "limit": { "type": "integer", "title": "Limit" }, "total": { "type": "integer", "title": "Total" } }, "additionalProperties": false, "type": "object", "required": [ "data", "page", "limit", "total" ], "title": "Page[Member]" }, "Page_Project_": { "properties": { "data": { "items": { "$ref": "#/components/schemas/Project" }, "type": "array", "title": "Data" }, "page": { "type": "integer", "title": "Page" }, "limit": { "type": "integer", "title": "Limit" }, "total": { "type": "integer", "title": "Total" } }, "additionalProperties": false, "type": "object", "required": [ "data", "page", "limit", "total" ], "title": "Page[Project]" }, "PresentationOutline": { "properties": { "documentTitle": { "anyOf": [ { "type": "string", "maxLength": 255 }, { "type": "null" } ], "title": "Documenttitle" }, "hook": { "anyOf": [ { "type": "string", "maxLength": 5000 }, { "type": "null" } ], "title": "Hook" }, "researchSummary": { "anyOf": [ { "type": "string", "maxLength": 20000 }, { "type": "null" } ], "title": "Researchsummary" }, "contentLanguage": { "anyOf": [ { "type": "string", "maxLength": 100 }, { "type": "null" } ], "title": "Contentlanguage" }, "footerText": { "anyOf": [ { "type": "string", "maxLength": 500 }, { "type": "null" } ], "title": "Footertext" }, "imagePrompt": { "anyOf": [ { "type": "string", "maxLength": 5000 }, { "type": "null" } ], "title": "Imageprompt" }, "contentMode": { "anyOf": [ { "type": "string", "maxLength": 20 }, { "type": "null" } ], "title": "Contentmode" }, "companyName": { "anyOf": [ { "type": "string", "maxLength": 300 }, { "type": "null" } ], "title": "Companyname" }, "companyDomain": { "anyOf": [ { "type": "string", "maxLength": 255 }, { "type": "null" } ], "title": "Companydomain" }, "slides": { "items": { "$ref": "#/components/schemas/PresentationOutlineSlide" }, "type": "array", "maxItems": 200, "minItems": 1, "title": "Slides" } }, "additionalProperties": false, "type": "object", "required": [ "slides" ], "title": "PresentationOutline", "description": "Complete validated presentation outline." }, "PresentationOutlineSlide": { "properties": { "heading": { "type": "string", "maxLength": 2000, "minLength": 1, "title": "Heading" }, "subheading": { "anyOf": [ { "type": "string", "maxLength": 2000 }, { "type": "null" } ], "title": "Subheading" }, "description": { "anyOf": [ { "type": "string", "maxLength": 20000 }, { "type": "null" } ], "title": "Description" }, "category": { "anyOf": [ { "type": "string", "maxLength": 200 }, { "type": "null" } ], "title": "Category" }, "useCase": { "anyOf": [ { "type": "string", "maxLength": 200 }, { "type": "null" } ], "title": "Usecase" }, "speakerNotes": { "anyOf": [ { "type": "string", "maxLength": 5000 }, { "type": "null" } ], "title": "Speakernotes" }, "visualComposition": { "anyOf": [ { "items": { "type": "string", "maxLength": 100, "minLength": 1 }, "type": "array", "maxItems": 20 }, { "type": "null" } ], "title": "Visualcomposition" }, "graphicSubtypes": { "anyOf": [ { "additionalProperties": { "type": "string" }, "type": "object", "maxProperties": 20 }, { "type": "null" } ], "title": "Graphicsubtypes" }, "graphics": { "anyOf": [ { "items": { "$ref": "#/components/schemas/OutlineGraphic" }, "type": "array", "maxItems": 10 }, { "type": "null" } ], "title": "Graphics" }, "imageQuery": { "anyOf": [ { "type": "string", "maxLength": 1000 }, { "type": "null" } ], "title": "Imagequery" }, "sources": { "anyOf": [ { "items": { "$ref": "#/components/schemas/OutlineSource" }, "type": "array", "maxItems": 8 }, { "type": "null" } ], "title": "Sources" }, "confidence": { "anyOf": [ { "type": "string", "maxLength": 20 }, { "type": "null" } ], "title": "Confidence" } }, "additionalProperties": false, "type": "object", "required": [ "heading" ], "title": "PresentationOutlineSlide", "description": "One validated slide in a generated or caller-authored outline." }, "Project": { "properties": { "id": { "type": "string", "format": "uuid", "title": "Id" }, "workspace_id": { "type": "string", "format": "uuid", "title": "Workspace Id" }, "name": { "type": "string", "title": "Name" }, "slug": { "type": "string", "title": "Slug" }, "default_member_role": { "$ref": "#/components/schemas/ProjectRole" }, "workspace_visible": { "type": "boolean", "title": "Workspace Visible" }, "created_by": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "title": "Created By" }, "archived_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Archived At" }, "created_at": { "type": "string", "format": "date-time", "title": "Created At" }, "knowledge_id": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "title": "Knowledge Id" }, "has_share_link": { "type": "boolean", "title": "Has Share Link", "default": false } }, "additionalProperties": false, "type": "object", "required": [ "id", "workspace_id", "name", "slug", "default_member_role", "workspace_visible", "created_by", "archived_at", "created_at" ], "title": "Project", "description": "Project response shape." }, "ProjectRole": { "type": "string", "enum": [ "LEAD", "EDITOR", "VIEWER" ], "title": "ProjectRole", "description": "Project membership role." }, "RequestIdConflict": { "properties": { "code": { "type": "string", "const": "REQUEST_ID_CONFLICT", "title": "Code" }, "message": { "type": "string", "minLength": 1, "title": "Message" }, "details": { "$ref": "#/components/schemas/RequestIdConflictDetails" }, "trace_id": { "anyOf": [ { "type": "string", "maxLength": 32, "minLength": 32 }, { "type": "null" } ], "title": "Trace Id" } }, "additionalProperties": false, "type": "object", "required": [ "code", "message", "details" ], "title": "RequestIdConflict", "description": "A request ID was replayed with content different from the original." }, "RequestIdConflictDetails": { "properties": { "deck_id": { "type": "string", "format": "uuid", "title": "Deck Id" }, "resolution": { "type": "string", "const": "reuse_original_payload_or_increment_request_id_version", "title": "Resolution" } }, "additionalProperties": false, "type": "object", "required": [ "deck_id", "resolution" ], "title": "RequestIdConflictDetails", "description": "Reconciliation information returned for a changed idempotent request." }, "RequestIdConflictResponse": { "properties": { "error": { "$ref": "#/components/schemas/RequestIdConflict" } }, "additionalProperties": false, "type": "object", "required": [ "error" ], "title": "RequestIdConflictResponse", "description": "Typed 409 response for a request-ID content conflict." }, "RequestValidationDetails": { "properties": { "errors": { "items": { "$ref": "#/components/schemas/RequestValidationIssue" }, "type": "array", "minItems": 1, "title": "Errors" } }, "additionalProperties": false, "type": "object", "required": [ "errors" ], "title": "RequestValidationDetails", "description": "Field-level issues for a rejected create request." }, "RequestValidationError": { "properties": { "code": { "type": "string", "const": "VALIDATION_FAILED", "title": "Code" }, "message": { "type": "string", "minLength": 1, "title": "Message" }, "details": { "$ref": "#/components/schemas/RequestValidationDetails" }, "trace_id": { "anyOf": [ { "type": "string", "maxLength": 32, "minLength": 32 }, { "type": "null" } ], "title": "Trace Id" } }, "additionalProperties": false, "type": "object", "required": [ "code", "message", "details" ], "title": "RequestValidationError", "description": "Typed validation failure from the standard API error handler." }, "RequestValidationErrorResponse": { "properties": { "error": { "$ref": "#/components/schemas/RequestValidationError" } }, "additionalProperties": false, "type": "object", "required": [ "error" ], "title": "RequestValidationErrorResponse", "description": "Typed 422 response envelope.", "examples": [ { "error": { "code": "VALIDATION_FAILED", "details": { "errors": [ { "loc": [ "header", "Request-Id" ], "msg": "Field required", "type": "missing" } ] }, "message": "Request failed validation.", "trace_id": "4bf92f3577b34da6a3ce929d0e0e4736" } } ] }, "RequestValidationIssue": { "properties": { "type": { "type": "string", "minLength": 1, "title": "Type", "description": "Pydantic validation error type." }, "loc": { "items": { "anyOf": [ { "type": "string" }, { "type": "integer" } ] }, "type": "array", "minItems": 1, "title": "Loc", "description": "Location from request section through the rejected field." }, "msg": { "type": "string", "minLength": 1, "title": "Msg", "description": "Human-readable validation message." }, "input": { "anyOf": [ { "$ref": "#/components/schemas/JsonValue" }, { "type": "null" } ], "description": "Rejected input, truncated when it originated from binary request data." }, "ctx": { "anyOf": [ { "additionalProperties": { "$ref": "#/components/schemas/JsonValue" }, "type": "object" }, { "type": "null" } ], "title": "Ctx", "description": "Optional constraint values used by the validator." } }, "additionalProperties": false, "type": "object", "required": [ "type", "loc", "msg" ], "title": "RequestValidationIssue", "description": "One typed Pydantic/FastAPI request-validation issue." }, "ShareLink": { "properties": { "url": { "type": "string", "minLength": 1, "format": "uri", "title": "Url" }, "password_set": { "type": "boolean", "title": "Password Set", "default": false }, "expires_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Expires At" } }, "additionalProperties": false, "type": "object", "required": [ "url" ], "title": "ShareLink", "description": "Response carrying the full share URL (includes raw token).\n\nGrows the access-control state additively so the share dialog can render its\ncurrent settings from the same call that gives it the URL. The password's\nvalue is on `ShareLinkSettings`." }, "SlideChangeV8Request": { "properties": { "content": { "type": "string", "maxLength": 20000, "minLength": 1, "title": "Content" }, "target_template": { "type": "string", "maxLength": 200, "minLength": 1, "title": "Target Template" }, "subtype": { "anyOf": [ { "type": "string", "maxLength": 100 }, { "type": "null" } ], "title": "Subtype" }, "nodecount": { "anyOf": [ { "type": "integer", "minimum": 1.0 }, { "type": "null" } ], "title": "Nodecount" }, "char_range": { "anyOf": [ { "type": "string", "maxLength": 100 }, { "type": "null" } ], "title": "Char Range" }, "elements": { "anyOf": [ { "items": { "additionalProperties": true, "type": "object" }, "type": "array" }, { "type": "null" } ], "title": "Elements" }, "language": { "type": "string", "maxLength": 100, "title": "Language", "default": "auto" } }, "additionalProperties": false, "type": "object", "required": [ "content", "target_template" ], "title": "SlideChangeV8Request", "description": "V8 change: convert existing slide CONTENT into a TARGET graphic type (+ subtype).\n\nRuns the v8 filler (JSON). An optional Exa answer fills in data the content lacks\n(target-aware)." }, "SlideFillRequest": { "properties": { "selected_template": { "type": "string", "maxLength": 200, "minLength": 1, "title": "Selected Template" }, "elements": { "items": { "additionalProperties": true, "type": "object" }, "type": "array", "title": "Elements" }, "shape": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Shape" }, "heading": { "type": "string", "maxLength": 2000, "title": "Heading", "default": "" }, "description": { "type": "string", "maxLength": 20000, "title": "Description", "default": "" }, "subheading": { "type": "string", "maxLength": 2000, "title": "Subheading", "default": "" }, "speaker_notes": { "type": "string", "maxLength": 5000, "title": "Speaker Notes", "default": "" }, "language": { "type": "string", "maxLength": 100, "minLength": 1, "title": "Language", "default": "English" }, "graphics_xml": { "type": "string", "maxLength": 40000, "title": "Graphics Xml", "default": "" }, "adapt_content": { "type": "boolean", "title": "Adapt Content", "default": false }, "total_slides": { "type": "integer", "minimum": 0.0, "title": "Total Slides", "default": 0 } }, "additionalProperties": false, "type": "object", "required": [ "selected_template", "elements" ], "title": "SlideFillRequest", "description": "Stateless slide generation (external API) \u2014 deck size comes from the caller.\n\nAlways the v8 fill. Content comes from `graphics_xml` (the v8 writer's structured\ngraphics for the slide) when given, else from `heading` + `description` as plain content\n(the v8 add-slide fill); one of the two is required." }, "TaskWarning": { "properties": { "message": { "type": "string", "maxLength": 500, "minLength": 1, "title": "Message" }, "stage": { "type": "string", "maxLength": 100, "minLength": 1, "title": "Stage" }, "source": { "type": "string", "maxLength": 100, "minLength": 1, "title": "Source" }, "retryable": { "type": "boolean", "title": "Retryable", "default": false }, "occurred_at": { "type": "string", "format": "date-time", "title": "Occurred At" } }, "additionalProperties": false, "type": "object", "required": [ "message", "stage", "source", "occurred_at" ], "title": "TaskWarning", "description": "A generation warning persisted on an async task." }, "TextSource": { "properties": { "type": { "type": "string", "const": "text", "title": "Type" }, "content": { "type": "string", "maxLength": 200000, "minLength": 1, "title": "Content" } }, "additionalProperties": false, "type": "object", "required": [ "type", "content" ], "title": "TextSource", "description": "Inline factual source material supplied directly in the request." }, "Thumbnail": { "properties": { "url": { "type": "string", "title": "Url" }, "width": { "type": "integer", "title": "Width" }, "height": { "type": "integer", "title": "Height" } }, "additionalProperties": false, "type": "object", "required": [ "url", "width", "height" ], "title": "Thumbnail", "description": "One stored size of a rendered thumbnail; `width`/`height` feed `srcset`." }, "UpdateDeckRequest": { "properties": { "name": { "anyOf": [ { "type": "string", "maxLength": 255, "minLength": 1 }, { "type": "null" } ], "title": "Name" }, "visibility": { "anyOf": [ { "$ref": "#/components/schemas/DeckVisibility" }, { "type": "null" } ] }, "project_id": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "title": "Project Id" }, "version": { "anyOf": [ { "type": "string", "enum": [ "v1", "v2" ] }, { "type": "null" } ], "title": "Version" } }, "additionalProperties": false, "type": "object", "title": "UpdateDeckRequest", "description": "Partial update of a deck. project_id=None keeps the current value.\n\n`version` flips which content the app renders (`Deck.active_version`) \u2014\nnever `origin_version`, which is immutable provenance. Only \"v1\"/\"v2\" are\naccepted; the service layer rejects a flip to a version the deck has no\nreal materialized content for (see `deck_service.update`)." }, "UpdateMemberRoleRequest": { "properties": { "role": { "$ref": "#/components/schemas/WorkspaceRole" } }, "additionalProperties": false, "type": "object", "required": [ "role" ], "title": "UpdateMemberRoleRequest", "description": "Change a member's role." }, "UpdateProjectRequest": { "properties": { "name": { "anyOf": [ { "type": "string", "maxLength": 120, "minLength": 1 }, { "type": "null" } ], "title": "Name" }, "slug": { "anyOf": [ { "type": "string", "maxLength": 40, "minLength": 1 }, { "type": "null" } ], "title": "Slug" }, "default_member_role": { "anyOf": [ { "$ref": "#/components/schemas/ProjectRole" }, { "type": "null" } ] } }, "additionalProperties": false, "type": "object", "title": "UpdateProjectRequest", "description": "Partial update of a project. Archive is handled by DELETE." }, "UserContact": { "properties": { "id": { "type": "string", "format": "uuid", "title": "Id" }, "display_name": { "type": "string", "title": "Display Name" }, "avatar_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Avatar Url" }, "email": { "type": "string", "format": "email", "title": "Email" } }, "additionalProperties": false, "type": "object", "required": [ "id", "display_name", "avatar_url", "email" ], "title": "UserContact", "description": "UserInfo plus email \u2014 for member-management surfaces only." }, "UserInfo": { "properties": { "id": { "type": "string", "format": "uuid", "title": "Id" }, "display_name": { "type": "string", "title": "Display Name" }, "avatar_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Avatar Url" } }, "additionalProperties": false, "type": "object", "required": [ "id", "display_name", "avatar_url" ], "title": "UserInfo", "description": "Public profile of a referenced user." }, "Workspace": { "properties": { "id": { "type": "string", "format": "uuid", "title": "Id" }, "name": { "type": "string", "title": "Name" }, "slug": { "type": "string", "title": "Slug" }, "default_brand_kit_id": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "title": "Default Brand Kit Id" }, "workspace_image_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Workspace Image Url" }, "created_at": { "type": "string", "format": "date-time", "title": "Created At" } }, "additionalProperties": false, "type": "object", "required": [ "id", "name", "slug", "created_at" ], "title": "Workspace", "description": "Shared workspace response shape." }, "WorkspaceRole": { "type": "string", "enum": [ "OWNER", "ADMIN", "MEMBER", "GUEST" ], "title": "WorkspaceRole", "description": "Workspace membership role; higher roles subsume lower ones for hierarchy checks." } }, "securitySchemes": { "HTTPBearer": { "type": "http", "scheme": "bearer" } }, "responses": { "Unauthenticated": { "description": "Missing, malformed, expired, or revoked Bearer API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/APIErrorResponse" } } }, "headers": { "WWW-Authenticate": { "description": "Bearer authentication challenge.", "schema": { "type": "string", "example": "Bearer" } } } }, "Forbidden": { "description": "The API key, workspace role, project scope, or plan lacks permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/APIErrorResponse" } } } }, "NotFound": { "description": "The resource does not exist or is outside the caller's scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/APIErrorResponse" } } } }, "ValidationFailed": { "description": "A path, query, header, or request-body field failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestValidationErrorResponse" } } } }, "RateLimited": { "description": "The caller exceeded the API rate limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/APIErrorResponse" } } }, "headers": { "Retry-After": { "description": "HTTP date after which the request may be retried.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Requests allowed in the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix timestamp when the current window resets.", "schema": { "type": "integer" } } } }, "InternalError": { "description": "Unexpected server failure. Retry only idempotent operations and retain trace_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/APIErrorResponse" } } } } } }, "tags": [ { "name": "me", "description": "The authenticated principal: who the current API key acts as." }, { "name": "api-keys", "description": "Manage the workspace's API keys." }, { "name": "workspace", "description": "Workspace details and settings." }, { "name": "members", "description": "Workspace membership." }, { "name": "projects", "description": "Projects that group decks." }, { "name": "decks", "description": "Create decks asynchronously from prompts, typed sources, or a caller-edited outline, then poll, inspect, and download the rendered result." }, { "name": "outlines", "description": "Generate stateless, strictly typed outlines as JSON or SSE. Edit the returned outline and pass it to `POST /decks` to render the reviewed structure." }, { "name": "brand-kits", "description": "Find a brand kit and pass its `id` as `brand_kit_id` to `POST /decks`. Brands limited to approved email domains appear only for callers on those domains." }, { "name": "files", "description": "Upload source files for deck generation." }, { "name": "requests", "description": "Poll deck generation by caller request ID, including its stage, warnings, terminal error, and completed export." }, { "name": "credits", "description": "Credit balance and usage." }, { "name": "objects", "description": "Fetch stored objects referenced by other resources." }, { "name": "exports", "description": "Token-authorized downloads of deck export artifacts." } ], "x-tagGroups": [ { "name": "Account", "tags": [ "me", "api-keys", "workspace", "members", "credits" ] }, { "name": "Build presentations", "tags": [ "projects", "brand-kits", "files", "outlines", "decks" ] }, { "name": "Track and download", "tags": [ "requests", "objects", "exports" ] } ] }