{ "openapi": "3.0.3", "info": { "title": "OODA AI REST API", "version": "2026-10-01", "description": "Build with the OODA AI REST API and a project API key. This reference covers the public model, media, voice and avatar endpoints. Examples use illustrative IDs and outputs; select actual enabled model IDs from `GET /v1/models`.\n\n## Quickstart\n\n1. Sign in to [OODA AI Platform](https://platform.ooda.ai/api-keys), select your project, and create a key under **Manage → API Keys**. Copy the secret when it is shown; later views show only a preview.\n2. Set the API base URL and key in your server environment using the values below.\n3. List your models, then send a request.\n\n```bash\nexport OODA_BASE_URL=\"https://platform.ooda.ai\"\nexport OODA_API_KEY=\"YOUR_API_KEY\"\n\ncurl \"$OODA_BASE_URL/v1/models\" \\\n -H \"Authorization: Bearer $OODA_API_KEY\"\n\ncurl \"$OODA_BASE_URL/v1/chat/completions\" \\\n -H \"Authorization: Bearer $OODA_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"model\":\"platform/auto\",\"messages\":[{\"role\":\"user\",\"content\":\"Hello!\"}]}'\n```\n\n## Authentication and scope\n\nSend `Authorization: Bearer YOUR_API_KEY` on every documented request, including downloads and video polling. Keep keys on your server; do not embed them in browser bundles or URLs. These requests do not require browser cookies.\n\nPrefer project-scoped keys. A project's enabled models and resources determine what its key can use. Organization-wide keys can discover published resources across the organization; endpoints requiring a project use the key's resolved default project. A request header cannot turn a project key into an organization-wide key. API keys do not inherit the creator's administrator role. Role-restricted actions can return **403**; inaccessible project resources return **404**. Specialized support keys and managed Agent callback credentials are separate credentials with different scopes.\n\n## OpenAI SDK compatibility\n\nThe model list and Chat Completions API support the OpenAI client shape. Set `base_url` to the API origin plus `/v1`; always select a model returned by your catalog. Compatibility applies to the documented operations, not the entire OpenAI API. The OODA AI REST API does not expose a public `/v1/responses`, `/v1/files`, or `/v1/embeddings` endpoint in this release.\n\n```python\nimport os\nfrom openai import OpenAI\n\nclient = OpenAI(\n api_key=os.environ[\"OODA_API_KEY\"],\n base_url=os.environ[\"OODA_BASE_URL\"] + \"/v1\",\n)\nresult = client.chat.completions.create(\n model=\"platform/auto\",\n messages=[{\"role\": \"user\", \"content\": \"Hello!\"}],\n)\nprint(result.choices[0].message.content)\n```\n\n## Streaming\n\nSet `stream: true` for Chat Completions and use `curl -N` to disable client buffering. Responses use `text/event-stream`: each `data:` event contains a JSON chunk, and `[DONE]` ends a successful stream. Accumulate `choices[].delta.content` and tool-call fragments. Token usage may arrive in a final chunk with empty choices. A disconnect before completion is not proof of success; avoid automatically replaying a request after output has started.\n\n## Published resources\n\n`GET /v1/models` also discovers project resources such as `expert/...`, `idp/...`, `workflow/...`, `agent/...`, and `avatar/...`. Use the returned ID without reconstructing it. Text resources use Chat Completions; image, video and audio resources use their matching modality endpoint. IDP accepts text or `pdf_url`/`image_url` content parts, including base64 data URLs, through Chat Completions. It returns extracted JSON in the assistant message's `content` string. Published IDP versions can use `:vN`; API keys cannot access `:draft`. Workflows use the last user message as their input; file parts are not their trigger payload. Ready Agents use the same chat endpoint; generated file links require the same key.\n\n## Errors, limits and retries\n\n| HTTP status | Meaning | What to do |\n| --- | --- | --- |\n| 400 | Invalid JSON, missing fields or unsupported model options | Correct the request. |\n| 401 | Missing, invalid or disabled credentials | Check the key and environment. |\n| 402 | Insufficient credits or a spending limit | Check organization billing and project budgets. |\n| 403 | Access or organization policy denied | Check scope, permissions and IP allowlists. |\n| 404 | Unknown or inaccessible model/resource | Use an ID returned for this key. |\n| 409 | Resource is not ready or conflicts with current state | Poll the job or resolve the conflict. |\n| 413 | Request is too large | Reduce the input size. |\n| 429 | Request/token rate limit or capacity restriction | Respect `Retry-After` when supplied and use bounded exponential backoff. |\n| 500 / 502 / 503 / 504 | Server or upstream service failure | Retry with backoff only when safe. |\n\nLimits depend on your organization, project and chosen model; there is no single published request-per-minute allowance. Model metadata lists supported options and context limits. Unsupported media sizes, durations or controls can return 400. Generation and mutation requests do not promise idempotency: a retry can create a duplicate or incur another charge.\n\nMost platform errors use `{\"data\":null,\"error\":\"message\"}`. Authentication middleware can return `{\"error\":\"message\"}` without a data envelope, and inference errors may use an OpenAI-style error object. Parse the status first and accept either error shape. The `X-Inference-Trace-Id` response header, when present, helps support locate a request. A successful avatar/face response uses `{data,error}`; model/chat/media responses follow the schemas below.\n\n## Data handling\n\nThe documentation page is a read-only reference: it does not collect API keys or send model requests. OODA AI Platform stores account and application data; request metadata and generated product resources can be retained. This API reference does not promise zero retention. See the [privacy policy](https://ooda.ai/privacy) and your service agreement for the applicable terms.\n" }, "servers": [ { "url": "https://platform.ooda.ai" } ], "security": [ { "apiKey": [] } ], "tags": [ { "name": "Models", "description": "Discover the models and published resources your key can access." }, { "name": "Chat", "description": "Text, tools, structured output and published text resources." }, { "name": "Classification", "description": "Typed choices, probabilities and scores." }, { "name": "Images", "description": "Generate images with supported model options." }, { "name": "Videos", "description": "Create, poll and download video jobs." }, { "name": "Audio", "description": "Speech synthesis and transcription." }, { "name": "Voices", "description": "Voice library, cloning and settings." }, { "name": "Faces", "description": "Stock faces and project-specific trained faces." }, { "name": "Avatars", "description": "Create avatars and manage live conversations." }, { "name": "Agent files", "description": "Download files returned by a ready Agent." } ], "paths": { "/v1/models": { "get": { "tags": [ "Models" ], "summary": "List available models", "description": "Returns the enabled model catalog for this key, including published resources. Check type, available and metadata before choosing options. A successful list does not guarantee current generation capacity.", "operationId": "get_v1_models", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "list" ] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Model" } } }, "required": [ "object", "data" ] }, "example": { "object": "list", "data": [ { "id": "platform/auto", "object": "model", "created": 0, "owned_by": "platform", "name": "Auto", "type": "text" } ] } } } }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "402": { "$ref": "#/components/responses/Error402" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "429": { "$ref": "#/components/responses/Error429" }, "502": { "$ref": "#/components/responses/Error502" }, "503": { "$ref": "#/components/responses/Error503" } }, "x-codeSamples": [ { "lang": "Shell", "label": "cURL", "source": "curl \"$OODA_BASE_URL/v1/models\" \\\n -H \"Authorization: Bearer $OODA_API_KEY\"" } ] } }, "/v1/chat/completions": { "post": { "tags": [ "Chat" ], "summary": "Create a chat completion", "description": "Send a message history to an enabled text model or published text resource. Model-specific controls are subject to the catalog metadata. Set stream=true for SSE; tool-capable models accept tools and tool_choice. Send tool results back with role=tool and the matching tool_call_id. For IDP use a returned idp/... ID; PDF/image content parts are supported, while input_file and file_id are not.", "operationId": "post_v1_chat_completions", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatCompletion" }, "example": { "id": "chatcmpl-example", "object": "chat.completion", "created": 1790812800, "model": "platform/auto", "choices": [ { "index": 0, "message": { "role": "assistant", "content": "Hello! How can I help?" }, "finish_reason": "stop" } ], "usage": { "prompt_tokens": 9, "completion_tokens": 8, "total_tokens": 17 } } }, "text/event-stream": { "schema": { "type": "string" }, "example": "data: {\"id\":\"chatcmpl-example\",\"object\":\"chat.completion.chunk\",\"choices\":[{\"index\":0,\"delta\":{\"content\":\"Hello!\"}}]}\n\ndata: {\"id\":\"chatcmpl-example\",\"object\":\"chat.completion.chunk\",\"choices\":[{\"index\":0,\"delta\":{},\"finish_reason\":\"stop\"}]}\n\ndata: [DONE]\n\n" } } }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "402": { "$ref": "#/components/responses/Error402" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "429": { "$ref": "#/components/responses/Error429" }, "502": { "$ref": "#/components/responses/Error502" }, "503": { "$ref": "#/components/responses/Error503" } }, "x-codeSamples": [ { "lang": "Shell", "label": "cURL", "source": "curl -X POST \"$OODA_BASE_URL/v1/chat/completions\" \\\n -H \"Authorization: Bearer $OODA_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"model\":\"platform/auto\",\"messages\":[{\"role\":\"user\",\"content\":\"Hello!\"}]}'" }, { "lang": "JavaScript", "label": "JavaScript (fetch)", "source": "const response = await fetch(`${process.env.OODA_BASE_URL}/v1/chat/completions`, {\n method: \"POST\",\n headers: {\n Authorization: `Bearer ${process.env.OODA_API_KEY}`,\n \"Content-Type\": \"application/json\"\n },\n body: JSON.stringify({ model: \"platform/auto\", messages: [{ role: \"user\", content: \"Hello!\" }] })\n});\nif (!response.ok) throw new Error(`OODA AI HTTP ${response.status}`);\nconsole.log((await response.json()).choices[0].message.content);" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "model": { "type": "string", "description": "Catalog model ID, or platform/auto." }, "messages": { "type": "array", "items": { "$ref": "#/components/schemas/Message" } }, "stream": { "type": "boolean", "default": false }, "stream_options": { "type": "object", "properties": { "include_usage": { "type": "boolean" } } }, "max_tokens": { "type": "integer", "minimum": 1, "description": "Output limit; support and maximum depend on the model." }, "temperature": { "type": "number", "description": "Only for models that support sampling controls." }, "tools": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "function" ] }, "function": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "parameters": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "name" ] } }, "required": [ "type", "function" ] } }, "tool_choice": { "oneOf": [ { "type": "string", "enum": [ "auto", "none", "required" ] }, { "type": "object", "properties": {}, "additionalProperties": true } ] }, "response_format": { "type": "object", "properties": {}, "description": "For models advertising structured output, e.g. {\"type\":\"json_object\"}.", "additionalProperties": true } }, "required": [ "model", "messages" ] }, "examples": { "text": { "value": { "model": "platform/auto", "messages": [ { "role": "user", "content": "Hello!" } ] } }, "idp": { "summary": "Published IDP input (replace the ID and base64 data)", "value": { "model": "idp/your-project/Invoice", "messages": [ { "role": "user", "content": [ { "type": "text", "text": "Extract this invoice." }, { "type": "pdf_url", "pdf_url": { "url": "data:application/pdf;base64,REPLACE_WITH_BASE64_PDF" } } ] } ] } }, "tools": { "summary": "Tool declaration (execute returned calls in your application)", "value": { "model": "platform/auto", "messages": [ { "role": "user", "content": "What is the weather in Berlin?" } ], "tools": [ { "type": "function", "function": { "name": "get_weather", "description": "Get current weather for a city.", "parameters": { "type": "object", "properties": { "city": { "type": "string" } }, "required": [ "city" ] } } } ], "tool_choice": "auto" } } } } } } } }, "/v1/systemone": { "post": { "tags": [ "Classification" ], "summary": "Classify structured input", "description": "Return named choices, probabilities (noul, between 0 and 1), or fractional ordered scores. No actions are executed. model=platform/auto inherits the organization classifier. Maximum request: 256 KiB and 128 questions. Invalid answers fail with 502.", "operationId": "post_v1_systemone", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "answers": { "type": "object", "additionalProperties": { "type": "object", "properties": { "type": { "type": "string" }, "choice": { "type": "string" }, "noul": { "type": "number", "minimum": 0, "maximum": 1 }, "score": { "type": "number" }, "confidence": { "type": "number", "minimum": 0, "maximum": 1 } } } }, "usage": { "type": "object", "properties": { "input_tokens": { "type": "integer" }, "output_tokens": { "type": "integer" } } } }, "required": [ "answers", "usage" ] }, "example": { "answers": { "route": { "type": "choice", "choice": "billing", "confidence": 0.96 } }, "usage": { "input_tokens": 40, "output_tokens": 12 } } } } }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "402": { "$ref": "#/components/responses/Error402" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "429": { "$ref": "#/components/responses/Error429" }, "502": { "$ref": "#/components/responses/Error502" }, "503": { "$ref": "#/components/responses/Error503" } }, "x-codeSamples": [ { "lang": "Shell", "label": "cURL", "source": "curl -X POST \"$OODA_BASE_URL/v1/systemone\" \\\n -H \"Authorization: Bearer $OODA_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"model\":\"platform/auto\",\"state\":\"Please send a copy of my invoice.\",\"questions\":{\"route\":{\"type\":\"choice\",\"instructions\":\"Select the appropriate team.\",\"criteria\":{\"billing\":\"Invoices and payments\",\"support\":\"Product help\"}}}}'" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "model": { "type": "string" }, "state": { "oneOf": [ { "type": "string" }, { "type": "object", "properties": {}, "additionalProperties": true }, { "type": "array", "items": {} } ] }, "questions": { "type": "object", "minProperties": 1, "maxProperties": 128, "additionalProperties": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "choice", "noul", "score" ] }, "instructions": { "oneOf": [ { "type": "string" }, { "type": "object", "properties": {}, "additionalProperties": true }, { "type": "array", "items": {} } ] }, "criteria": { "description": "choice: map of option IDs to descriptions; score: ordered array of 2–128 descriptions; noul: optional true/false descriptions.", "oneOf": [ { "type": "object", "properties": {}, "additionalProperties": { "type": "string", "nullable": true } }, { "type": "array", "items": { "type": "string" } } ] } }, "required": [ "type", "instructions" ] } } }, "required": [ "model", "state", "questions" ] }, "example": { "model": "platform/auto", "state": "Please send a copy of my invoice.", "questions": { "route": { "type": "choice", "instructions": "Select the appropriate team.", "criteria": { "billing": "Invoices and payments", "support": "Product help" } } } } } } } } }, "/v1/images/generations": { "post": { "tags": [ "Images" ], "summary": "Generate images", "description": "Choose an image model from the catalog. Size, count and response formats vary by model. Ordinary API-key callers receive the inline image response; they do not use the dashboard gallery placeholder/polling flow. Returned URLs may expire; download results promptly.", "operationId": "post_v1_images_generations", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "created": { "type": "integer" }, "data": { "type": "array", "items": { "type": "object", "properties": { "url": { "type": "string" }, "b64_json": { "type": "string", "description": "Base64 image bytes." }, "revised_prompt": { "type": "string" } } } } } }, "example": { "created": 1790812800, "data": [ { "b64_json": "BASE64_IMAGE_BYTES" } ] } } } }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "402": { "$ref": "#/components/responses/Error402" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "429": { "$ref": "#/components/responses/Error429" }, "502": { "$ref": "#/components/responses/Error502" }, "503": { "$ref": "#/components/responses/Error503" } }, "x-codeSamples": [ { "lang": "Shell", "label": "cURL", "source": "curl -X POST \"$OODA_BASE_URL/v1/images/generations\" \\\n -H \"Authorization: Bearer $OODA_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"model\":\"platform/auto-image\",\"prompt\":\"A watercolor illustration of a lighthouse.\"}'" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "model": { "type": "string", "description": "An enabled image model ID." }, "prompt": { "type": "string" }, "n": { "type": "integer", "minimum": 1, "description": "Number of images, where supported." }, "size": { "type": "string", "description": "Use a supported size from model metadata." }, "response_format": { "type": "string", "description": "url or b64_json where supported." } }, "required": [ "model", "prompt" ] }, "example": { "model": "platform/auto-image", "prompt": "A watercolor illustration of a lighthouse." } } } } } }, "/v1/videos/generations": { "post": { "tags": [ "Videos" ], "summary": "Start video generation", "description": "For API-key callers, returns a job with an opaque id and polling_url. Follow that URL with the same key until completed/ready or failed; then download the returned content URL. Shapes can include additional model-specific fields. Jobs are scoped to the organization and effective project; the opaque handle expires after 24 hours. Use string seconds. No dashboard gallery access is required.", "operationId": "post_v1_videos_generations", "responses": { "202": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VideoJob" }, "example": { "id": "OPAQUE_JOB_ID", "status": "queued", "polling_url": "https://platform.ooda.ai/v1/videos/OPAQUE_JOB_ID" } } } }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "402": { "$ref": "#/components/responses/Error402" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "429": { "$ref": "#/components/responses/Error429" }, "502": { "$ref": "#/components/responses/Error502" }, "503": { "$ref": "#/components/responses/Error503" }, "200": { "description": "Some models return the job or completed result immediately.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VideoJob" }, "example": { "id": "OPAQUE_JOB_ID", "status": "queued", "polling_url": "https://platform.ooda.ai/v1/videos/OPAQUE_JOB_ID" } } } } }, "x-codeSamples": [ { "lang": "Shell", "label": "cURL", "source": "curl -X POST \"$OODA_BASE_URL/v1/videos/generations\" \\\n -H \"Authorization: Bearer $OODA_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"model\":\"platform/auto-video\",\"prompt\":\"A slow aerial shot of a coastal lighthouse.\",\"seconds\":\"8\"}'" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "model": { "type": "string", "description": "An enabled video model, including a returned avatar/... ID." }, "prompt": { "type": "string" }, "seconds": { "type": "string", "description": "Duration in seconds, subject to model metadata." }, "size": { "type": "string", "description": "Supported size from model metadata." }, "image_b64": { "type": "string", "description": "Base64 reference image, only for supported models." } }, "required": [ "model", "prompt" ] }, "example": { "model": "platform/auto-video", "prompt": "A slow aerial shot of a coastal lighthouse.", "seconds": "8" } } } } } }, "/v1/videos/{id}": { "get": { "tags": [ "Videos" ], "summary": "Get video job status", "description": "Use the polling_url returned by generation, preserving its opaque ID and API origin. Poll with backoff. Stop on terminal failure; do not create a second generation request to check progress.", "operationId": "get_v1_videos_id", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VideoJob" }, "example": { "id": "OPAQUE_JOB_ID", "status": "completed", "polling_url": "https://platform.ooda.ai/v1/videos/OPAQUE_JOB_ID", "url": "https://platform.ooda.ai/v1/videos/OPAQUE_JOB_ID/content" } } } }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "402": { "$ref": "#/components/responses/Error402" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "429": { "$ref": "#/components/responses/Error429" }, "502": { "$ref": "#/components/responses/Error502" }, "503": { "$ref": "#/components/responses/Error503" } }, "x-codeSamples": [ { "lang": "Shell", "label": "cURL", "source": "curl \"$OODA_BASE_URL/v1/videos/00000000-0000-4000-8000-000000000001\" \\\n -H \"Authorization: Bearer $OODA_API_KEY\"" } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Use the value returned by the API. This example is a placeholder.", "schema": { "type": "string" }, "example": "00000000-0000-4000-8000-000000000001" } ] } }, "/v1/videos/{id}/content": { "get": { "tags": [ "Videos" ], "summary": "Download a completed video", "description": "Download with the same key and project scope. Content is binary; do not parse it as JSON. The response Content-Type reflects the media. A job that is not ready can return 409.", "operationId": "get_v1_videos_id_content", "responses": { "200": { "description": "Successful response", "content": { "video/mp4": { "schema": { "type": "string", "format": "binary" }, "example": "(binary video bytes)" } } }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "402": { "$ref": "#/components/responses/Error402" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "429": { "$ref": "#/components/responses/Error429" }, "502": { "$ref": "#/components/responses/Error502" }, "503": { "$ref": "#/components/responses/Error503" }, "409": { "$ref": "#/components/responses/Error409" } }, "x-codeSamples": [ { "lang": "Shell", "label": "cURL", "source": "curl \"$OODA_BASE_URL/v1/videos/00000000-0000-4000-8000-000000000001/content\" \\\n -H \"Authorization: Bearer $OODA_API_KEY\" \\\n --output output.bin" } ], "parameters": [ { "name": "index", "in": "query", "schema": { "type": "integer", "minimum": 0, "maximum": 99 }, "description": "Optional output index for multi-output models." }, { "name": "id", "in": "path", "required": true, "description": "Use the value returned by the API. This example is a placeholder.", "schema": { "type": "string" }, "example": "00000000-0000-4000-8000-000000000001" } ] }, "head": { "tags": [ "Videos" ], "summary": "Inspect video content headers", "description": "Same authentication and job scope as GET. Returns headers without the video body; a pending job can return 409.", "operationId": "head_v1_videos_id_content", "responses": { "200": { "description": "Successful response" }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "402": { "$ref": "#/components/responses/Error402" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "429": { "$ref": "#/components/responses/Error429" }, "502": { "$ref": "#/components/responses/Error502" }, "503": { "$ref": "#/components/responses/Error503" } }, "x-codeSamples": [ { "lang": "Shell", "label": "cURL", "source": "curl -X HEAD \"$OODA_BASE_URL/v1/videos/00000000-0000-4000-8000-000000000001/content\" \\\n -H \"Authorization: Bearer $OODA_API_KEY\" \\\n --output output.bin" } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Use the value returned by the API. This example is a placeholder.", "schema": { "type": "string" }, "example": "00000000-0000-4000-8000-000000000001" } ] } }, "/v1/audio/transcriptions": { "post": { "tags": [ "Audio" ], "summary": "Transcribe audio", "description": "Upload an audio file as multipart/form-data with a speech-to-text model from your catalog. Let your HTTP library set the multipart boundary. Supported formats, limits and language options depend on the model.", "operationId": "post_v1_audio_transcriptions", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "text": { "type": "string" } }, "required": [ "text" ] }, "example": { "text": "Hello, and welcome to OODA AI." } } } }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "402": { "$ref": "#/components/responses/Error402" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "429": { "$ref": "#/components/responses/Error429" }, "502": { "$ref": "#/components/responses/Error502" }, "503": { "$ref": "#/components/responses/Error503" } }, "x-codeSamples": [ { "lang": "Shell", "label": "cURL", "source": "curl -X POST \"$OODA_BASE_URL/v1/audio/transcriptions\" \\\n -H \"Authorization: Bearer $OODA_API_KEY\" \\\n -F 'model=openai/whisper-large-v3' \\\n -F 'file=@recording.wav' \\\n -F 'response_format=json'" } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "model": { "type": "string" }, "file": { "type": "string", "format": "binary" }, "language": { "type": "string", "description": "Optional language hint, when supported." }, "prompt": { "type": "string", "description": "Optional transcription context, when supported." }, "response_format": { "type": "string", "description": "Use json for the example response. Other formats depend on the model." } }, "required": [ "model", "file" ] }, "example": { "model": "openai/whisper-large-v3", "file": "@recording.wav", "response_format": "json" } } } } } }, "/v1/audio/speech": { "post": { "tags": [ "Audio" ], "summary": "Generate speech", "description": "Choose an audio synthesis model and a voice compatible with it. The response contains audio bytes, not a JSON envelope. Save the body to a file and inspect Content-Type. Voices and output formats differ by model; the voice library below is not universal across all speech models.", "operationId": "post_v1_audio_speech", "responses": { "200": { "description": "Successful response", "content": { "audio/mpeg": { "schema": { "type": "string", "format": "binary" }, "example": "(binary MP3 bytes)" } } }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "402": { "$ref": "#/components/responses/Error402" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "429": { "$ref": "#/components/responses/Error429" }, "502": { "$ref": "#/components/responses/Error502" }, "503": { "$ref": "#/components/responses/Error503" } }, "x-codeSamples": [ { "lang": "Shell", "label": "cURL", "source": "curl -X POST \"$OODA_BASE_URL/v1/audio/speech\" \\\n -H \"Authorization: Bearer $OODA_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"model\":\"elevenlabs/eleven_multilingual_v2\",\"input\":\"Welcome to OODA AI.\",\"voice\":\"VOICE_ID_FROM_LIBRARY\",\"response_format\":\"mp3\"}' \\\n --output speech.mp3" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "model": { "type": "string" }, "input": { "type": "string", "description": "Text to speak." }, "voice": { "type": "string", "description": "A voice ID accepted by the selected model." }, "response_format": { "type": "string", "description": "Output format, where supported." }, "speed": { "type": "number" }, "language": { "type": "string", "description": "Optional language hint." } }, "required": [ "model", "input" ] }, "example": { "model": "elevenlabs/eleven_multilingual_v2", "input": "Welcome to OODA AI.", "voice": "VOICE_ID_FROM_LIBRARY", "response_format": "mp3" } } } } } }, "/v1/voices": { "get": { "tags": [ "Voices" ], "summary": "List voices", "description": "Returns the current voice library. Use voice_id in compatible speech or avatar requests. This API-key voice interface differs from the dashboard project voice-management API.", "operationId": "get_v1_voices", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "voices": { "type": "array", "items": { "$ref": "#/components/schemas/Voice" } } } }, "example": { "voices": [ { "voice_id": "VOICE_ID_FROM_LIBRARY", "name": "Example voice", "category": "premade" } ] } } } }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "402": { "$ref": "#/components/responses/Error402" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "429": { "$ref": "#/components/responses/Error429" }, "502": { "$ref": "#/components/responses/Error502" }, "503": { "$ref": "#/components/responses/Error503" } }, "x-codeSamples": [ { "lang": "Shell", "label": "cURL", "source": "curl \"$OODA_BASE_URL/v1/voices\" \\\n -H \"Authorization: Bearer $OODA_API_KEY\"" } ] } }, "/v1/voices/{id}": { "get": { "tags": [ "Voices" ], "summary": "Get a voice", "description": "Get details for a voice ID returned by the library.", "operationId": "get_v1_voices_id", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Voice" }, "example": { "voice_id": "VOICE_ID_FROM_LIBRARY", "name": "Example voice", "category": "premade" } } } }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "402": { "$ref": "#/components/responses/Error402" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "429": { "$ref": "#/components/responses/Error429" }, "502": { "$ref": "#/components/responses/Error502" }, "503": { "$ref": "#/components/responses/Error503" } }, "x-codeSamples": [ { "lang": "Shell", "label": "cURL", "source": "curl \"$OODA_BASE_URL/v1/voices/00000000-0000-4000-8000-000000000001\" \\\n -H \"Authorization: Bearer $OODA_API_KEY\"" } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Use the value returned by the API. This example is a placeholder.", "schema": { "type": "string" }, "example": "00000000-0000-4000-8000-000000000001" } ] }, "delete": { "tags": [ "Voices" ], "summary": "Delete a voice", "description": "Permanently deletes a deletable custom voice. Stock voices may reject deletion. Confirm the selected voice in your application before sending this request.", "operationId": "delete_v1_voices_id", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" } } }, "example": { "status": "ok" } } } }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "402": { "$ref": "#/components/responses/Error402" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "429": { "$ref": "#/components/responses/Error429" }, "502": { "$ref": "#/components/responses/Error502" }, "503": { "$ref": "#/components/responses/Error503" } }, "x-codeSamples": [ { "lang": "Shell", "label": "cURL", "source": "curl -X DELETE \"$OODA_BASE_URL/v1/voices/00000000-0000-4000-8000-000000000001\" \\\n -H \"Authorization: Bearer $OODA_API_KEY\"" } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Use the value returned by the API. This example is a placeholder.", "schema": { "type": "string" }, "example": "00000000-0000-4000-8000-000000000001" } ] } }, "/v1/voices/add": { "post": { "tags": [ "Voices" ], "summary": "Clone a voice", "description": "Upload one or more voice samples using repeated files multipart fields. Only submit recordings you are authorized to use. Return fields and verification requirements depend on voice-service configuration.", "operationId": "post_v1_voices_add", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "voice_id": { "type": "string" }, "requires_verification": { "type": "boolean" } }, "additionalProperties": true }, "example": { "voice_id": "NEW_VOICE_ID", "requires_verification": false } } } }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "402": { "$ref": "#/components/responses/Error402" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "429": { "$ref": "#/components/responses/Error429" }, "502": { "$ref": "#/components/responses/Error502" }, "503": { "$ref": "#/components/responses/Error503" } }, "x-codeSamples": [ { "lang": "Shell", "label": "cURL", "source": "curl -X POST \"$OODA_BASE_URL/v1/voices/add\" \\\n -H \"Authorization: Bearer $OODA_API_KEY\" \\\n -F 'name=My voice' \\\n -F 'files=@sample.mp3'" } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "files": { "type": "array", "items": { "type": "string", "format": "binary" } }, "description": { "type": "string" }, "labels": { "type": "string", "description": "JSON-encoded object of descriptive labels." } }, "required": [ "name", "files" ] }, "example": { "name": "My voice", "files": [ "@sample.mp3" ] } } } } } }, "/v1/voices/{id}/edit": { "post": { "tags": [ "Voices" ], "summary": "Edit a custom voice", "description": "Update the name, description or samples of an editable voice using multipart form fields.", "operationId": "post_v1_voices_id_edit", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" } } }, "example": { "status": "ok" } } } }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "402": { "$ref": "#/components/responses/Error402" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "429": { "$ref": "#/components/responses/Error429" }, "502": { "$ref": "#/components/responses/Error502" }, "503": { "$ref": "#/components/responses/Error503" } }, "x-codeSamples": [ { "lang": "Shell", "label": "cURL", "source": "curl -X POST \"$OODA_BASE_URL/v1/voices/00000000-0000-4000-8000-000000000001/edit\" \\\n -H \"Authorization: Bearer $OODA_API_KEY\" \\\n -F 'name=Updated voice'" } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "files": { "type": "array", "items": { "type": "string", "format": "binary" } }, "description": { "type": "string" }, "labels": { "type": "string", "description": "JSON-encoded object of descriptive labels." } }, "required": [ "name" ] }, "example": { "name": "Updated voice" } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Use the value returned by the API. This example is a placeholder.", "schema": { "type": "string" }, "example": "00000000-0000-4000-8000-000000000001" } ] } }, "/v1/voices/settings/default": { "get": { "tags": [ "Voices" ], "summary": "Get default voice settings", "description": "Returns the voice service default synthesis settings. Supported overrides depend on the speech model.", "operationId": "get_v1_voices_settings_default", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "stability": { "type": "number" }, "similarity_boost": { "type": "number" }, "style": { "type": "number" }, "use_speaker_boost": { "type": "boolean" } }, "additionalProperties": true }, "example": { "stability": 0.5, "similarity_boost": 0.75, "style": 0, "use_speaker_boost": true } } } }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "402": { "$ref": "#/components/responses/Error402" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "429": { "$ref": "#/components/responses/Error429" }, "502": { "$ref": "#/components/responses/Error502" }, "503": { "$ref": "#/components/responses/Error503" } }, "x-codeSamples": [ { "lang": "Shell", "label": "cURL", "source": "curl \"$OODA_BASE_URL/v1/voices/settings/default\" \\\n -H \"Authorization: Bearer $OODA_API_KEY\"" } ] } }, "/v1/voices/shared": { "get": { "tags": [ "Voices" ], "summary": "Browse shared voices", "description": "Returns the shared voice library using the configured voice service defaults. Query parameters are not currently forwarded by this endpoint.", "operationId": "get_v1_voices_shared", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "voices": { "type": "array", "items": { "$ref": "#/components/schemas/Voice" } }, "has_more": { "type": "boolean" } }, "additionalProperties": true }, "example": { "voices": [ { "voice_id": "VOICE_ID_FROM_LIBRARY", "name": "Example voice", "category": "premade" } ], "has_more": false } } } }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "402": { "$ref": "#/components/responses/Error402" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "429": { "$ref": "#/components/responses/Error429" }, "502": { "$ref": "#/components/responses/Error502" }, "503": { "$ref": "#/components/responses/Error503" } }, "x-codeSamples": [ { "lang": "Shell", "label": "cURL", "source": "curl \"$OODA_BASE_URL/v1/voices/shared\" \\\n -H \"Authorization: Bearer $OODA_API_KEY\"" } ] } }, "/v1/faces": { "get": { "tags": [ "Faces" ], "summary": "List faces", "description": "Lists stock faces and custom faces accessible in the key’s project. Custom faces use local UUIDs; stock faces retain catalog IDs.", "operationId": "get_v1_faces", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Face" } }, "error": { "type": "string", "nullable": true } }, "required": [ "data", "error" ] }, "example": { "data": [ { "id": "00000000-0000-4000-8000-000000000001", "displayName": "Presenter", "status": "ready", "createdByOrganizationId": null } ], "error": null } } } }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "402": { "$ref": "#/components/responses/Error402" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "429": { "$ref": "#/components/responses/Error429" }, "502": { "$ref": "#/components/responses/Error502" }, "503": { "$ref": "#/components/responses/Error503" } }, "x-codeSamples": [ { "lang": "Shell", "label": "cURL", "source": "curl \"$OODA_BASE_URL/v1/faces\" \\\n -H \"Authorization: Bearer $OODA_API_KEY\"" } ], "parameters": [ { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1 } }, { "name": "perPage", "in": "query", "schema": { "type": "integer", "minimum": 1 } } ] }, "post": { "tags": [ "Faces" ], "summary": "Train a face", "description": "Submit exactly one imageFile (JPEG/PNG, up to 20 MB) or videoFile (MP4/WebM). Video training requires the consent statement shown in OODA AI Platform; supply consentVideoFile when it is not at the beginning of the training video. Training is asynchronous: poll GET /v1/faces/{id} until ready or error.", "operationId": "post_v1_faces", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Face" }, "error": { "type": "string", "nullable": true } }, "required": [ "data", "error" ] }, "example": { "data": { "id": "00000000-0000-4000-8000-000000000001", "displayName": "Presenter", "status": "training", "createdByOrganizationId": null }, "error": null } } } }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "402": { "$ref": "#/components/responses/Error402" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "429": { "$ref": "#/components/responses/Error429" }, "502": { "$ref": "#/components/responses/Error502" }, "503": { "$ref": "#/components/responses/Error503" } }, "x-codeSamples": [ { "lang": "Shell", "label": "cURL", "source": "curl -X POST \"$OODA_BASE_URL/v1/faces\" \\\n -H \"Authorization: Bearer $OODA_API_KEY\" \\\n -F 'displayName=Presenter' \\\n -F 'imageFile=@portrait.png'" } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "displayName": { "type": "string" }, "imageFile": { "type": "string", "format": "binary" }, "voiceName": { "type": "string", "enum": [ "anna", "benjamin", "james", "liam", "julia", "ivy" ] }, "videoFile": { "type": "string", "format": "binary" }, "consentVideoFile": { "type": "string", "format": "binary" } }, "required": [ "displayName" ] }, "example": { "displayName": "Presenter", "imageFile": "@portrait.png" } } } } } }, "/v1/faces/{id}": { "get": { "tags": [ "Faces" ], "summary": "Get a face", "description": "Retrieve a stock face or a project-local custom face, including its training status. Unknown or out-of-scope IDs return 404.", "operationId": "get_v1_faces_id", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Face" }, "error": { "type": "string", "nullable": true } }, "required": [ "data", "error" ] }, "example": { "data": { "id": "00000000-0000-4000-8000-000000000001", "displayName": "Presenter", "status": "ready", "createdByOrganizationId": null }, "error": null } } } }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "402": { "$ref": "#/components/responses/Error402" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "429": { "$ref": "#/components/responses/Error429" }, "502": { "$ref": "#/components/responses/Error502" }, "503": { "$ref": "#/components/responses/Error503" } }, "x-codeSamples": [ { "lang": "Shell", "label": "cURL", "source": "curl \"$OODA_BASE_URL/v1/faces/00000000-0000-4000-8000-000000000001\" \\\n -H \"Authorization: Bearer $OODA_API_KEY\"" } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Use the value returned by the API. This example is a placeholder.", "schema": { "type": "string" }, "example": "00000000-0000-4000-8000-000000000001" } ] }, "put": { "tags": [ "Faces" ], "summary": "Rename a face", "description": "Rename a custom face belonging to this project. Stock faces cannot be renamed.", "operationId": "put_v1_faces_id", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "displayName": { "type": "string" } } }, "error": { "type": "string", "nullable": true } }, "required": [ "data", "error" ] }, "example": { "data": { "id": "00000000-0000-4000-8000-000000000001", "displayName": "Updated presenter" }, "error": null } } } }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "402": { "$ref": "#/components/responses/Error402" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "429": { "$ref": "#/components/responses/Error429" }, "502": { "$ref": "#/components/responses/Error502" }, "503": { "$ref": "#/components/responses/Error503" } }, "x-codeSamples": [ { "lang": "Shell", "label": "cURL", "source": "curl -X PUT \"$OODA_BASE_URL/v1/faces/00000000-0000-4000-8000-000000000001\" \\\n -H \"Authorization: Bearer $OODA_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"displayName\":\"Updated presenter\"}'" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "displayName": { "type": "string" } }, "required": [ "displayName" ] }, "example": { "displayName": "Updated presenter" } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Use the value returned by the API. This example is a placeholder.", "schema": { "type": "string" }, "example": "00000000-0000-4000-8000-000000000001" } ] }, "delete": { "tags": [ "Faces" ], "summary": "Delete a face", "description": "Permanently delete a project-created custom face and its stored training media. Confirm the selected face in your application first.", "operationId": "delete_v1_faces_id", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "deleted": { "type": "boolean" } } }, "error": { "type": "string", "nullable": true } }, "required": [ "data", "error" ] }, "example": { "data": { "deleted": true }, "error": null } } } }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "402": { "$ref": "#/components/responses/Error402" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "429": { "$ref": "#/components/responses/Error429" }, "502": { "$ref": "#/components/responses/Error502" }, "503": { "$ref": "#/components/responses/Error503" } }, "x-codeSamples": [ { "lang": "Shell", "label": "cURL", "source": "curl -X DELETE \"$OODA_BASE_URL/v1/faces/00000000-0000-4000-8000-000000000001\" \\\n -H \"Authorization: Bearer $OODA_API_KEY\"" } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Use the value returned by the API. This example is a placeholder.", "schema": { "type": "string" }, "example": "00000000-0000-4000-8000-000000000001" } ] } }, "/v1/avatars": { "get": { "tags": [ "Avatars" ], "summary": "List avatars", "description": "Lists avatars in the resolved project. Use the returned local UUID for subsequent requests.", "operationId": "get_v1_avatars", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Avatar" } }, "error": { "type": "string", "nullable": true } }, "required": [ "data", "error" ] }, "example": { "data": [ { "id": "00000000-0000-4000-8000-000000000001", "name": "Support assistant", "faceId": "STOCK_FACE_ID", "llmId": "llm_example", "greeting": "How can I help?" } ], "error": null } } } }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "402": { "$ref": "#/components/responses/Error402" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "429": { "$ref": "#/components/responses/Error429" }, "502": { "$ref": "#/components/responses/Error502" }, "503": { "$ref": "#/components/responses/Error503" } }, "x-codeSamples": [ { "lang": "Shell", "label": "cURL", "source": "curl \"$OODA_BASE_URL/v1/avatars\" \\\n -H \"Authorization: Bearer $OODA_API_KEY\"" } ], "parameters": [ { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1 } }, { "name": "perPage", "in": "query", "schema": { "type": "integer", "minimum": 1 } } ] }, "post": { "tags": [ "Avatars" ], "summary": "Create an avatar", "description": "Create an avatar with a face from GET /v1/faces and an unused llmId from POST /v1/avatars/custom-llm. Optional knowledge and connector IDs must be accessible in the project. Meeting conferencing is off by default.", "operationId": "post_v1_avatars", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Avatar" }, "error": { "type": "string", "nullable": true } }, "required": [ "data", "error" ] }, "example": { "data": { "id": "00000000-0000-4000-8000-000000000001", "name": "Support assistant", "faceId": "STOCK_FACE_ID", "llmId": "llm_example", "greeting": "How can I help?" }, "error": null } } } }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "402": { "$ref": "#/components/responses/Error402" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "429": { "$ref": "#/components/responses/Error429" }, "502": { "$ref": "#/components/responses/Error502" }, "503": { "$ref": "#/components/responses/Error503" } }, "x-codeSamples": [ { "lang": "Shell", "label": "cURL", "source": "curl -X POST \"$OODA_BASE_URL/v1/avatars\" \\\n -H \"Authorization: Bearer $OODA_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"name\":\"Support assistant\",\"faceId\":\"STOCK_FACE_ID\",\"llmId\":\"llm_example\",\"greeting\":\"How can I help?\"}'" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "faceId": { "type": "string" }, "voiceId": { "type": "string" }, "llmId": { "type": "string" }, "systemPrompt": { "type": "string" }, "greeting": { "type": "string" }, "language": { "type": "string" }, "knowledgeFileIds": { "type": "array", "items": { "type": "string", "description": "Project-local resource ID." } }, "knowledgeFolderIds": { "type": "array", "items": { "type": "string", "description": "Project-local resource ID." } }, "connectorPairIds": { "type": "array", "items": { "type": "string", "description": "Project-local resource ID." } } }, "required": [ "name", "faceId", "llmId" ] }, "example": { "name": "Support assistant", "faceId": "STOCK_FACE_ID", "llmId": "llm_example", "greeting": "How can I help?" } } } } } }, "/v1/avatars/custom-llm": { "post": { "tags": [ "Avatars" ], "summary": "Create an avatar brain", "description": "Register an enabled text model for an avatar. Use the returned llm_ ID once when creating the avatar. Credentials remain server-side; this endpoint does not return an API-key secret.", "operationId": "post_v1_avatars_custom_llm", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "displayName": { "type": "string" }, "modelName": { "type": "string" } } }, "error": { "type": "string", "nullable": true } }, "required": [ "data", "error" ] }, "example": { "data": { "id": "llm_example", "displayName": "Support brain", "modelName": "platform/auto" }, "error": null } } } }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "402": { "$ref": "#/components/responses/Error402" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "429": { "$ref": "#/components/responses/Error429" }, "502": { "$ref": "#/components/responses/Error502" }, "503": { "$ref": "#/components/responses/Error503" } }, "x-codeSamples": [ { "lang": "Shell", "label": "cURL", "source": "curl -X POST \"$OODA_BASE_URL/v1/avatars/custom-llm\" \\\n -H \"Authorization: Bearer $OODA_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"modelId\":\"platform/auto\",\"name\":\"Support brain\"}'" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "modelId": { "type": "string" }, "name": { "type": "string" } }, "required": [ "modelId" ] }, "example": { "modelId": "platform/auto", "name": "Support brain" } } } } } }, "/v1/avatars/{id}": { "get": { "tags": [ "Avatars" ], "summary": "Get an avatar", "description": "Fetch the project-local avatar. Inaccessible or unknown UUIDs return 404.", "operationId": "get_v1_avatars_id", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Avatar" }, "error": { "type": "string", "nullable": true } }, "required": [ "data", "error" ] }, "example": { "data": { "id": "00000000-0000-4000-8000-000000000001", "name": "Support assistant", "faceId": "STOCK_FACE_ID", "llmId": "llm_example", "greeting": "How can I help?" }, "error": null } } } }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "402": { "$ref": "#/components/responses/Error402" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "429": { "$ref": "#/components/responses/Error429" }, "502": { "$ref": "#/components/responses/Error502" }, "503": { "$ref": "#/components/responses/Error503" } }, "x-codeSamples": [ { "lang": "Shell", "label": "cURL", "source": "curl \"$OODA_BASE_URL/v1/avatars/00000000-0000-4000-8000-000000000001\" \\\n -H \"Authorization: Bearer $OODA_API_KEY\"" } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Use the value returned by the API. This example is a placeholder.", "schema": { "type": "string" }, "example": "00000000-0000-4000-8000-000000000001" } ] }, "put": { "tags": [ "Avatars" ], "summary": "Update an avatar", "description": "Update the avatar in place. Omitted fields are preserved. Empty arrays clear linked collections; empty greeting/description clears those values. An empty systemPrompt restores the default prompt. The response contains the avatar identity, not a complete avatar object.", "operationId": "put_v1_avatars_id", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" } }, "required": [ "id" ] }, "error": { "type": "string", "nullable": true } }, "required": [ "data", "error" ] }, "example": { "data": { "id": "00000000-0000-4000-8000-000000000001" }, "error": null } } } }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "402": { "$ref": "#/components/responses/Error402" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "429": { "$ref": "#/components/responses/Error429" }, "502": { "$ref": "#/components/responses/Error502" }, "503": { "$ref": "#/components/responses/Error503" } }, "x-codeSamples": [ { "lang": "Shell", "label": "cURL", "source": "curl -X PUT \"$OODA_BASE_URL/v1/avatars/00000000-0000-4000-8000-000000000001\" \\\n -H \"Authorization: Bearer $OODA_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"name\":\"Customer support\",\"greeting\":\"Welcome!\"}'" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "faceId": { "type": "string" }, "voiceId": { "type": "string" }, "systemPrompt": { "type": "string" }, "greeting": { "type": "string" }, "language": { "type": "string" }, "knowledgeFileIds": { "type": "array", "items": { "type": "string", "description": "Project-local resource ID." } }, "knowledgeFolderIds": { "type": "array", "items": { "type": "string", "description": "Project-local resource ID." } }, "connectorPairIds": { "type": "array", "items": { "type": "string", "description": "Project-local resource ID." } }, "modelId": { "type": "string", "description": "An enabled text model ID." } } }, "example": { "name": "Customer support", "greeting": "Welcome!" } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Use the value returned by the API. This example is a placeholder.", "schema": { "type": "string" }, "example": "00000000-0000-4000-8000-000000000001" } ] }, "delete": { "tags": [ "Avatars" ], "summary": "Delete an avatar", "description": "Permanently delete this project avatar. Confirm the selected avatar before sending the request.", "operationId": "delete_v1_avatars_id", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "deleted": { "type": "boolean" } } }, "error": { "type": "string", "nullable": true } }, "required": [ "data", "error" ] }, "example": { "data": { "deleted": true }, "error": null } } } }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "402": { "$ref": "#/components/responses/Error402" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "429": { "$ref": "#/components/responses/Error429" }, "502": { "$ref": "#/components/responses/Error502" }, "503": { "$ref": "#/components/responses/Error503" } }, "x-codeSamples": [ { "lang": "Shell", "label": "cURL", "source": "curl -X DELETE \"$OODA_BASE_URL/v1/avatars/00000000-0000-4000-8000-000000000001\" \\\n -H \"Authorization: Bearer $OODA_API_KEY\"" } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Use the value returned by the API. This example is a placeholder.", "schema": { "type": "string" }, "example": "00000000-0000-4000-8000-000000000001" } ] } }, "/v1/avatars/sessions": { "post": { "tags": [ "Avatars" ], "summary": "Start a live conversation", "description": "Creates a billable live conversation. personaConfig.personaId is the avatar UUID. The returned conversationId is a separate local session UUID. Join conversationUrl with a compatible browser client and end the session when finished.", "operationId": "post_v1_avatars_sessions", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/AvatarSession" }, "error": { "type": "string", "nullable": true } }, "required": [ "data", "error" ] }, "example": { "data": { "conversationId": "00000000-0000-4000-8000-000000000001", "conversationUrl": "https://example.daily.co/example-room" }, "error": null } } } }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "402": { "$ref": "#/components/responses/Error402" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "429": { "$ref": "#/components/responses/Error429" }, "502": { "$ref": "#/components/responses/Error502" }, "503": { "$ref": "#/components/responses/Error503" } }, "x-codeSamples": [ { "lang": "Shell", "label": "cURL", "source": "curl -X POST \"$OODA_BASE_URL/v1/avatars/sessions\" \\\n -H \"Authorization: Bearer $OODA_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"personaConfig\":{\"personaId\":\"00000000-0000-4000-8000-000000000001\"}}'" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "personaConfig": { "type": "object", "properties": { "personaId": { "type": "string", "format": "uuid" }, "initialMessage": { "type": "string" }, "languageCode": { "type": "string", "description": "Supported two-letter code or English language name." }, "systemPrompt": { "type": "string" } }, "required": [ "personaId" ] }, "history": { "type": "array", "items": { "type": "object", "properties": { "role": { "type": "string", "enum": [ "user", "assistant" ] }, "content": { "type": "string" } } } } }, "required": [ "personaConfig" ] }, "example": { "personaConfig": { "personaId": "00000000-0000-4000-8000-000000000001" } } } } } } }, "/v1/avatars/sessions/{id}/end": { "post": { "tags": [ "Avatars" ], "summary": "End a live conversation", "description": "Use the conversationId returned by session creation, not the avatar ID. The platform attempts to end the remote call and removes its local mapping. A repeated request or an inaccessible session can return 404.", "operationId": "post_v1_avatars_sessions_id_end", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "ended": { "type": "boolean" } } }, "error": { "type": "string", "nullable": true } }, "required": [ "data", "error" ] }, "example": { "data": { "ended": true }, "error": null } } } }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "402": { "$ref": "#/components/responses/Error402" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "429": { "$ref": "#/components/responses/Error429" }, "502": { "$ref": "#/components/responses/Error502" }, "503": { "$ref": "#/components/responses/Error503" } }, "x-codeSamples": [ { "lang": "Shell", "label": "cURL", "source": "curl -X POST \"$OODA_BASE_URL/v1/avatars/sessions/00000000-0000-4000-8000-000000000001/end\" \\\n -H \"Authorization: Bearer $OODA_API_KEY\"" } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Use the value returned by the API. This example is a placeholder.", "schema": { "type": "string" }, "example": "00000000-0000-4000-8000-000000000001" } ] } }, "/v1/avatars/script-helper": { "post": { "tags": [ "Avatars" ], "summary": "Draft an avatar script", "description": "Draft or revise the spoken text for an avatar video. Requires project context and available model capacity; this does not generate a video.", "operationId": "post_v1_avatars_script_helper", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "script": { "type": "string" } } }, "error": { "type": "string", "nullable": true } }, "required": [ "data", "error" ] }, "example": { "data": { "script": "Welcome to our product tour." }, "error": null } } } }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "402": { "$ref": "#/components/responses/Error402" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "429": { "$ref": "#/components/responses/Error429" }, "502": { "$ref": "#/components/responses/Error502" }, "503": { "$ref": "#/components/responses/Error503" } }, "x-codeSamples": [ { "lang": "Shell", "label": "cURL", "source": "curl -X POST \"$OODA_BASE_URL/v1/avatars/script-helper\" \\\n -H \"Authorization: Bearer $OODA_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"instructions\":\"Write a short welcome for a product tour.\",\"avatarName\":\"Alex\"}'" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "instructions": { "type": "string" }, "currentScript": { "type": "string" }, "avatarName": { "type": "string" } }, "required": [ "instructions" ] }, "example": { "instructions": "Write a short welcome for a product tour.", "avatarName": "Alex" } } } } } }, "/v1/avatars/api-config": { "get": { "tags": [ "Avatars" ], "summary": "Get avatar API origins", "description": "Returns configured platform origins for clients integrating avatars. No secrets are returned.", "operationId": "get_v1_avatars_api_config", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "apiBaseUrl": { "type": "string" }, "appBaseUrl": { "type": "string" } } }, "error": { "type": "string", "nullable": true } }, "required": [ "data", "error" ] }, "example": { "data": { "apiBaseUrl": "https://platform.ooda.ai", "appBaseUrl": "https://platform.ooda.ai" }, "error": null } } } }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "402": { "$ref": "#/components/responses/Error402" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "429": { "$ref": "#/components/responses/Error429" }, "502": { "$ref": "#/components/responses/Error502" }, "503": { "$ref": "#/components/responses/Error503" } }, "x-codeSamples": [ { "lang": "Shell", "label": "cURL", "source": "curl \"$OODA_BASE_URL/v1/avatars/api-config\" \\\n -H \"Authorization: Bearer $OODA_API_KEY\"" } ] } }, "/v1/avatars/avatar-config": { "post": { "tags": [ "Avatars" ], "summary": "Save legacy avatar configuration", "description": "Compatibility endpoint. Prefer the create/update avatar operations for new integrations. Request fields use camelCase; stored config response fields use snake_case. personaId must be a project-local avatar UUID.", "operationId": "post_v1_avatars_avatar_config", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": {}, "additionalProperties": true }, "error": { "type": "string", "nullable": true } }, "required": [ "data", "error" ] }, "example": { "data": { "persona_id": "00000000-0000-4000-8000-000000000001", "platform_model_id": "platform/auto", "language": "en", "knowledge_folder_ids": [] }, "error": null } } } }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "402": { "$ref": "#/components/responses/Error402" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "429": { "$ref": "#/components/responses/Error429" }, "502": { "$ref": "#/components/responses/Error502" }, "503": { "$ref": "#/components/responses/Error503" } }, "x-codeSamples": [ { "lang": "Shell", "label": "cURL", "source": "curl -X POST \"$OODA_BASE_URL/v1/avatars/avatar-config\" \\\n -H \"Authorization: Bearer $OODA_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"personaId\":\"00000000-0000-4000-8000-000000000001\",\"platformModelId\":\"platform/auto\",\"language\":\"en\"}'" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "personaId": { "type": "string" }, "platformModelId": { "type": "string" }, "language": { "type": "string" }, "customLlmId": { "type": "string" }, "greeting": { "type": "string" }, "description": { "type": "string" }, "knowledgeFileIds": { "type": "array", "items": { "type": "string" } }, "knowledgeFolderIds": { "type": "array", "items": { "type": "string" } }, "connectorPairIds": { "type": "array", "items": { "type": "string" } } }, "required": [ "personaId", "platformModelId" ] }, "example": { "personaId": "00000000-0000-4000-8000-000000000001", "platformModelId": "platform/auto", "language": "en" } } } }, "deprecated": true } }, "/v1/avatars/avatar-config/{id}": { "get": { "tags": [ "Avatars" ], "summary": "Get legacy avatar configuration", "description": "Returns the project avatar configuration or data=null when no config is stored. Prefer GET /v1/avatars/{id} for the avatar itself.", "operationId": "get_v1_avatars_avatar_config_id", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": {}, "nullable": true, "additionalProperties": true }, "error": { "type": "string", "nullable": true } }, "required": [ "data", "error" ] }, "example": { "data": { "persona_id": "00000000-0000-4000-8000-000000000001", "platform_model_id": "platform/auto", "language": "en", "knowledge_folder_ids": [] }, "error": null } } } }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "402": { "$ref": "#/components/responses/Error402" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "429": { "$ref": "#/components/responses/Error429" }, "502": { "$ref": "#/components/responses/Error502" }, "503": { "$ref": "#/components/responses/Error503" } }, "x-codeSamples": [ { "lang": "Shell", "label": "cURL", "source": "curl \"$OODA_BASE_URL/v1/avatars/avatar-config/00000000-0000-4000-8000-000000000001\" \\\n -H \"Authorization: Bearer $OODA_API_KEY\"" } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Use the value returned by the API. This example is a placeholder.", "schema": { "type": "string" }, "example": "00000000-0000-4000-8000-000000000001" } ], "deprecated": true }, "delete": { "tags": [ "Avatars" ], "summary": "Delete legacy avatar configuration", "description": "Removes the sidecar configuration. To delete the avatar itself, use DELETE /v1/avatars/{id}.", "operationId": "delete_v1_avatars_avatar_config_id", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "string" }, "error": { "type": "string", "nullable": true } }, "required": [ "data", "error" ] }, "example": { "data": "ok", "error": null } } } }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "402": { "$ref": "#/components/responses/Error402" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "429": { "$ref": "#/components/responses/Error429" }, "502": { "$ref": "#/components/responses/Error502" }, "503": { "$ref": "#/components/responses/Error503" } }, "x-codeSamples": [ { "lang": "Shell", "label": "cURL", "source": "curl -X DELETE \"$OODA_BASE_URL/v1/avatars/avatar-config/00000000-0000-4000-8000-000000000001\" \\\n -H \"Authorization: Bearer $OODA_API_KEY\"" } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Use the value returned by the API. This example is a placeholder.", "schema": { "type": "string" }, "example": "00000000-0000-4000-8000-000000000001" } ], "deprecated": true } }, "/v1/avatars/oona-session": { "post": { "tags": [ "Avatars" ], "summary": "Start a platform support conversation", "description": "Starts the fixed platform support avatar in the key’s project. Organization credit limits apply. End the returned conversation through the normal session-end endpoint.", "operationId": "post_v1_avatars_oona_session", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/AvatarSession" }, "error": { "type": "string", "nullable": true } }, "required": [ "data", "error" ] }, "example": { "data": { "conversationId": "00000000-0000-4000-8000-000000000001", "conversationUrl": "https://example.daily.co/example-room" }, "error": null } } } }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "402": { "$ref": "#/components/responses/Error402" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "429": { "$ref": "#/components/responses/Error429" }, "502": { "$ref": "#/components/responses/Error502" }, "503": { "$ref": "#/components/responses/Error503" } }, "x-codeSamples": [ { "lang": "Shell", "label": "cURL", "source": "curl -X POST \"$OODA_BASE_URL/v1/avatars/oona-session\" \\\n -H \"Authorization: Bearer $OODA_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"language\":\"en\"}'" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "language": { "type": "string", "enum": [ "en", "de", "es", "pt", "sv", "it", "fr" ], "default": "en" } } }, "example": { "language": "en" } } } } } }, "/v1/agents/{model_uuid}/files/{path}": { "get": { "tags": [ "Agent files" ], "summary": "Download an Agent output file", "description": "Follow file URLs returned by an Agent chat completion. model_uuid is the UUID portion of the agent/... catalog ID. path may contain slash-separated workspace-relative segments; encode individual segments, and never include traversal. The same organization/project scope is required. Content-Type and Content-Disposition reflect the file.", "operationId": "get_v1_agents_model_uuid_files_path", "responses": { "200": { "description": "Successful response", "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" }, "example": "(binary file bytes)" } } }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "402": { "$ref": "#/components/responses/Error402" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "429": { "$ref": "#/components/responses/Error429" }, "502": { "$ref": "#/components/responses/Error502" }, "503": { "$ref": "#/components/responses/Error503" } }, "x-codeSamples": [ { "lang": "Shell", "label": "cURL", "source": "curl \"$OODA_BASE_URL/v1/agents/00000000-0000-4000-8000-000000000001/files/report.txt\" \\\n -H \"Authorization: Bearer $OODA_API_KEY\" \\\n --output output.bin" } ], "parameters": [ { "name": "model_uuid", "in": "path", "required": true, "description": "Use the value returned by the API. This example is a placeholder.", "schema": { "type": "string" }, "example": "00000000-0000-4000-8000-000000000001" }, { "name": "path", "in": "path", "required": true, "description": "Use the value returned by the API. This example is a placeholder.", "schema": { "type": "string" }, "example": "report.txt" } ] } } }, "components": { "securitySchemes": { "apiKey": { "type": "http", "scheme": "bearer", "bearerFormat": "OODA AI API key", "description": "Create a project key in OODA AI Platform. Pass the complete secret as a Bearer token." } }, "schemas": { "Error": { "type": "object", "properties": { "data": { "nullable": true }, "error": { "oneOf": [ { "type": "string" }, { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string" }, "code": { "type": "string" } } } ] } } }, "Model": { "type": "object", "properties": { "id": { "type": "string", "description": "Pass this exact catalog ID as model." }, "object": { "type": "string", "enum": [ "model" ] }, "created": { "type": "integer" }, "owned_by": { "type": "string", "description": "Model family or resource category." }, "name": { "type": "string" }, "type": { "type": "string", "description": "Modality, such as text, image, video, audio, idp or system1." }, "available": { "type": "boolean" }, "metadata": { "type": "object", "properties": {}, "description": "Model-specific capabilities, input/output limits and supported controls.", "additionalProperties": true } }, "required": [ "id", "object" ] }, "Message": { "type": "object", "properties": { "role": { "type": "string", "enum": [ "system", "developer", "user", "assistant", "tool" ] }, "content": { "nullable": true, "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" }, "text": { "type": "string" }, "image_url": { "type": "object", "properties": { "url": { "type": "string" } } }, "pdf_url": { "type": "object", "properties": { "url": { "type": "string" } } } }, "required": [ "type" ] } } ] }, "tool_call_id": { "type": "string", "description": "Required for a tool result." }, "tool_calls": { "type": "array", "items": { "type": "object", "properties": {}, "additionalProperties": true } } }, "required": [ "role" ] }, "ChatCompletion": { "type": "object", "properties": { "id": { "type": "string" }, "object": { "type": "string" }, "created": { "type": "integer" }, "model": { "type": "string" }, "choices": { "type": "array", "items": { "type": "object", "properties": { "index": { "type": "integer" }, "message": { "$ref": "#/components/schemas/Message" }, "finish_reason": { "type": "string", "nullable": true } } } }, "usage": { "type": "object", "properties": { "prompt_tokens": { "type": "integer" }, "completion_tokens": { "type": "integer" }, "total_tokens": { "type": "integer" } } } } }, "VideoJob": { "type": "object", "properties": { "id": { "type": "string", "description": "Opaque job ID. Do not decode or reconstruct it." }, "status": { "type": "string", "description": "Examples include queued, processing, completed, ready and failed; preserve unknown statuses." }, "polling_url": { "type": "string", "description": "Authenticated absolute polling URL." }, "url": { "type": "string", "description": "Authenticated download URL when ready." }, "error": { "nullable": true, "oneOf": [ { "type": "string" }, { "type": "object", "properties": {}, "additionalProperties": true } ] } }, "additionalProperties": true }, "Voice": { "type": "object", "properties": { "voice_id": { "type": "string" }, "name": { "type": "string" }, "category": { "type": "string" }, "preview_url": { "type": "string" }, "labels": { "type": "object", "properties": {}, "additionalProperties": { "type": "string" } } }, "additionalProperties": true }, "Face": { "type": "object", "properties": { "id": { "type": "string", "description": "Stock face ID or project-local custom face UUID." }, "displayName": { "type": "string" }, "status": { "type": "string", "enum": [ "training", "ready", "error" ] }, "trainingProgress": { "type": "string" }, "thumbnailUrl": { "type": "string" }, "imageUrl": { "type": "string" }, "createdByOrganizationId": { "type": "integer", "nullable": true }, "createdAt": { "type": "string" } }, "required": [ "id", "displayName", "status" ] }, "Avatar": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "description": { "type": "string" }, "faceId": { "type": "string" }, "voiceId": { "type": "string" }, "llmId": { "type": "string" }, "systemPrompt": { "type": "string" }, "greeting": { "type": "string" }, "conferencingEmail": { "type": "string", "description": "Present only when conferencing is provisioned." }, "embed_token": { "type": "string" }, "createdAt": { "type": "string" }, "face": { "type": "object", "properties": { "id": { "type": "string" }, "displayName": { "type": "string" }, "thumbnailUrl": { "type": "string" } } } }, "required": [ "id", "name" ] }, "AvatarSession": { "type": "object", "properties": { "conversationId": { "type": "string", "description": "Local conversation UUID used to end the session.", "format": "uuid" }, "conversationUrl": { "type": "string", "description": "Live room URL; use a compatible browser client to join.", "format": "uri" } }, "required": [ "conversationId", "conversationUrl" ] } }, "responses": { "Error400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "data": null, "error": "Invalid request" } } } }, "Error401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "data": null, "error": "Authentication required" } } } }, "Error402": { "description": "Billing or spending limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "data": null, "error": "Billing or spending limit" } } } }, "Error403": { "description": "Access denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "data": null, "error": "Access denied" } } } }, "Error404": { "description": "Resource not found in this scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "data": null, "error": "Resource not found in this scope" } } } }, "Error409": { "description": "Resource not ready or conflicting state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "data": null, "error": "Resource not ready or conflicting state" } } } }, "Error429": { "description": "Rate or capacity limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "data": null, "error": "Rate or capacity limit" } } } }, "Error502": { "description": "Upstream service failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "data": null, "error": "Upstream service failed" } } } }, "Error503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "data": null, "error": "Service unavailable" } } } } } } }