{ "openapi": "3.1.0", "info": { "title": "Dhanu API", "version": "1.0.0", "description": "Generate images and text, and give work to AI staff, from your own server. Authenticate with `Authorization: Bearer `." }, "servers": [ { "url": "https://api.dhanu.ai/api/pub/v1", "description": "Public API" } ], "tags": [ { "name": "Meta" }, { "name": "MCP" }, { "name": "Keys" }, { "name": "Images" }, { "name": "Text" }, { "name": "Jobs" }, { "name": "Tasks" }, { "name": "Staff" }, { "name": "Workflows" }, { "name": "Files" }, { "name": "Videos" }, { "name": "Brain" }, { "name": "Audio" }, { "name": "OCR" }, { "name": "Embeddings" } ], "paths": { "/openapi.json": { "get": { "operationId": "openapi", "tags": [ "Meta" ], "summary": "Get the OpenAPI document", "description": "This document. Needs no key.", "security": [], "responses": { "200": { "description": "The OpenAPI 3.1 document." } } } }, "/status": { "get": { "operationId": "status", "tags": [ "Meta" ], "summary": "Platform status", "description": "Current state of the public API and its services with 90 days of daily uptime, from probes every five minutes. Needs no key.", "security": [], "responses": { "200": { "description": "The status summary.", "content": { "application/json": { "schema": { "type": "object", "properties": { "state": { "type": "string", "enum": [ "operational", "degraded", "outage", "unknown" ] }, "checkedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "components": { "type": "array", "items": { "type": "object", "properties": { "component": { "type": "string" }, "label": { "type": "string" }, "state": { "type": "string", "enum": [ "operational", "degraded", "outage", "unknown" ] }, "latencyMs": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "checkedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "uptime90dPercent": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "days": { "type": "array", "items": { "type": "object", "properties": { "day": { "type": "string" }, "samples": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "upSamples": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "uptimePercent": { "anyOf": [ { "type": "number" }, { "type": "null" } ] } }, "required": [ "day", "samples", "upSamples", "uptimePercent" ] } } }, "required": [ "component", "label", "state", "latencyMs", "checkedAt", "uptime90dPercent", "days" ] } } }, "required": [ "state", "checkedAt", "components" ] } } } } } } }, "/mcp": { "post": { "operationId": "mcp", "tags": [ "MCP" ], "summary": "Model Context Protocol server", "description": "A remote MCP server over Streamable HTTP: tasks, staff, workflows, projects and brain search as MCP tools. Each tool is gated by the same scope as its REST operation and metered the same way.", "security": [ { "apiKey": [] } ], "responses": { "200": { "description": "The JSON-RPC response." }, "202": { "description": "A notification was accepted; no body." }, "401": { "description": "The key is missing, unknown or revoked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key may not perform this operation, or is outside its project scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited; retry after `Retry-After` seconds.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "jsonrpc": { "type": "string", "const": "2.0" }, "id": { "description": "Absent on a notification.", "anyOf": [ { "type": "string" }, { "type": "number" } ] }, "method": { "type": "string", "description": "initialize, ping, tools/list, tools/call or notifications/initialized." }, "params": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "jsonrpc", "method" ], "description": "One JSON-RPC 2.0 request, as the Model Context Protocol defines it." } } } }, "x-dhanu-error-codes": [ "invalid_api_key", "api_key_revoked", "api_key_expired", "api_key_ip_not_allowed", "developer_access_revoked", "api_key_project_scope" ] } }, "/me": { "get": { "operationId": "me", "tags": [ "Keys" ], "summary": "Check the key", "description": "The projects the key can reach, its name and its scope. The quickest way to confirm a key works.", "security": [ { "apiKey": [] } ], "responses": { "200": { "description": "The key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "app": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "name" ] }, { "type": "null" } ] }, "projects": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "name" ] } }, "key": { "type": "object", "properties": { "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "mode": { "type": "string", "enum": [ "live", "test" ], "description": "Test keys never spend credits and return fixture output." } }, "required": [ "name", "mode" ] }, "scope": { "type": "object", "properties": { "level": { "type": "string" }, "packages": { "type": "array", "items": { "type": "string" } }, "operations": { "type": "array", "items": { "type": "string" } } }, "required": [ "level", "packages", "operations" ] } }, "required": [ "app", "projects", "key", "scope" ] } } } }, "401": { "description": "The key is missing, unknown or revoked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key may not perform this operation, or is outside its project scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited; retry after `Retry-After` seconds.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-dhanu-error-codes": [ "invalid_api_key", "api_key_revoked", "api_key_expired", "api_key_ip_not_allowed", "developer_access_revoked", "api_key_project_scope" ] } }, "/reference": { "get": { "operationId": "reference", "tags": [ "Keys" ], "summary": "List the API catalogue", "description": "Every package and operation, with an `allowed` flag saying whether this key may call it.", "security": [ { "apiKey": [] } ], "responses": { "200": { "description": "The catalogue.", "content": { "application/json": { "schema": { "type": "object", "properties": { "scope": { "type": "object", "properties": { "level": { "type": "string" }, "packages": { "type": "array", "items": { "type": "string" } }, "operations": { "type": "array", "items": { "type": "string" } } }, "required": [ "level", "packages", "operations" ] }, "packages": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "string" }, "operations": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "method": { "type": "string" }, "path": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "string" }, "billed": { "type": "boolean" }, "allowed": { "type": "boolean" } }, "required": [ "id", "method", "path", "title", "description", "billed", "allowed" ] } } }, "required": [ "id", "title", "description", "operations" ] } } }, "required": [ "scope", "packages" ] } } } }, "401": { "description": "The key is missing, unknown or revoked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key may not perform this operation, or is outside its project scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited; retry after `Retry-After` seconds.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-dhanu-error-codes": [ "invalid_api_key", "api_key_revoked", "api_key_expired", "api_key_ip_not_allowed", "developer_access_revoked", "api_key_project_scope" ] } }, "/images": { "post": { "operationId": "images.generate", "tags": [ "Images" ], "summary": "Generate an image", "description": "Generate one image from a prompt and return its bytes as base64. Nothing is stored.", "security": [ { "apiKey": [] } ], "responses": { "201": { "description": "The generated image.", "content": { "application/json": { "schema": { "type": "object", "properties": { "image": { "type": "object", "properties": { "b64": { "type": "string" }, "mimeType": { "type": "string" } }, "required": [ "b64", "mimeType" ] }, "model": { "type": "string" }, "usage": { "type": "object", "properties": { "inputTokens": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "outputTokens": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "inputTokens", "outputTokens" ] }, "cost": { "type": "object", "properties": { "amount": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "In the workspace currency's minor unit." }, "currency": { "type": "string" } }, "required": [ "amount", "currency" ] } }, "required": [ "image", "model", "usage", "cost" ] } } } }, "401": { "description": "The key is missing, unknown or revoked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key may not perform this operation, or is outside its project scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "The request failed validation, or a domain rule rejected it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited; retry after `Retry-After` seconds.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "prompt": { "type": "string", "maxLength": 2000, "description": "What to draw." }, "aspectRatio": { "description": "Defaults to 1:1.", "type": "string", "enum": [ "1:1", "3:4", "9:16", "4:3", "16:9" ] }, "projectId": { "description": "Which of the key's projects the call runs against. Required when the key can access more than one project.", "type": "string" } }, "required": [ "prompt" ] } } } }, "x-dhanu-scope": "images.generate", "x-dhanu-error-codes": [ "invalid_api_key", "api_key_revoked", "api_key_expired", "api_key_ip_not_allowed", "developer_access_revoked", "api_key_project_scope", "invalid_request_body", "project_id_required", "insufficient_credits", "key_spend_limit_reached", "invalid_generation_prompt", "invalid_image_aspect_ratio" ] } }, "/text": { "post": { "operationId": "text.generate", "tags": [ "Text" ], "summary": "Generate text", "description": "Generate a completion from a prompt.", "security": [ { "apiKey": [] } ], "responses": { "200": { "description": "With `stream: true`, a text/event-stream of `delta` events followed by one `done` event carrying the same body as the 201 response." }, "201": { "description": "The generated text.", "content": { "application/json": { "schema": { "type": "object", "properties": { "text": { "type": "string" }, "model": { "type": "string" }, "usage": { "type": "object", "properties": { "inputTokens": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "outputTokens": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "inputTokens", "outputTokens" ] }, "cost": { "type": "object", "properties": { "amount": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "In the workspace currency's minor unit." }, "currency": { "type": "string" } }, "required": [ "amount", "currency" ] } }, "required": [ "text", "model", "usage", "cost" ] } } } }, "401": { "description": "The key is missing, unknown or revoked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key may not perform this operation, or is outside its project scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "The request failed validation, or a domain rule rejected it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited; retry after `Retry-After` seconds.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "prompt": { "type": "string", "maxLength": 2000 }, "system": { "description": "A system instruction.", "type": "string" }, "maxTokens": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "projectId": { "description": "Which of the key's projects the call runs against. Required when the key can access more than one project.", "type": "string" }, "stream": { "description": "Stream the reply as server-sent events (`delta` events, then one `done` event) instead of one JSON body.", "type": "boolean" } }, "required": [ "prompt" ] } } } }, "x-dhanu-scope": "text.generate", "x-dhanu-error-codes": [ "invalid_api_key", "api_key_revoked", "api_key_expired", "api_key_ip_not_allowed", "developer_access_revoked", "api_key_project_scope", "invalid_request_body", "project_id_required", "insufficient_credits", "key_spend_limit_reached", "invalid_generation_prompt" ] } }, "/projects": { "get": { "operationId": "projects", "tags": [ "Keys" ], "summary": "List projects", "description": "The projects this key can act in, the same list as `GET /me`, for clients that want it on its own.", "security": [ { "apiKey": [] } ], "responses": { "200": { "description": "The projects.", "content": { "application/json": { "schema": { "type": "object", "properties": { "projects": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "name" ] } } }, "required": [ "projects" ] } } } }, "401": { "description": "The key is missing, unknown or revoked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key may not perform this operation, or is outside its project scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited; retry after `Retry-After` seconds.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-dhanu-error-codes": [ "invalid_api_key", "api_key_revoked", "api_key_expired", "api_key_ip_not_allowed", "developer_access_revoked", "api_key_project_scope" ] } }, "/jobs/{jobId}": { "get": { "operationId": "jobs.read", "tags": [ "Jobs" ], "summary": "Read a job", "description": "A background job the API started for you, a video render, an export. Poll it until `status` is `succeeded` or `failed`, or subscribe to the `job.succeeded` / `job.failed` webhooks instead.", "security": [ { "apiKey": [] } ], "responses": { "200": { "description": "The job.", "content": { "application/json": { "schema": { "type": "object", "properties": { "job": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string" }, "status": { "type": "string", "enum": [ "queued", "running", "succeeded", "failed", "cancelled" ] }, "result": { "anyOf": [ {}, { "type": "null" } ] }, "error": { "anyOf": [ { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] }, { "type": "null" } ] }, "createdAt": { "type": "string" }, "completedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "type", "status", "result", "error", "createdAt", "completedAt" ] } }, "required": [ "job" ] } } } }, "401": { "description": "The key is missing, unknown or revoked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key may not perform this operation, or is outside its project scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited; retry after `Retry-After` seconds.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "jobId", "in": "path", "required": true, "schema": { "type": "string" } } ], "x-dhanu-scope": "jobs.read", "x-dhanu-error-codes": [ "invalid_api_key", "api_key_revoked", "api_key_expired", "api_key_ip_not_allowed", "developer_access_revoked", "api_key_project_scope", "not_found" ] } }, "/staff/{address}/trigger": { "post": { "operationId": "tasks.trigger", "tags": [ "Tasks" ], "summary": "Trigger a staff member", "description": "Hand a staff member a piece of work through its API address. Returns at once with the task; poll its messages for the reply.", "security": [ { "apiKey": [] } ], "responses": { "202": { "description": "The task that was started.", "content": { "application/json": { "schema": { "type": "object", "properties": { "task": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "assigneeStaffIds": { "type": "array", "items": { "type": "string" } }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "id", "title", "assigneeStaffIds", "createdAt", "updatedAt" ] } }, "required": [ "task" ] } } } }, "401": { "description": "The key is missing, unknown or revoked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key may not perform this operation, or is outside its project scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "The request failed validation, or a domain rule rejected it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited; retry after `Retry-After` seconds.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "address", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "input": { "type": "string", "minLength": 1, "maxLength": 50000, "description": "The work to hand over, as plain text." }, "subject": { "type": "string" }, "threadId": { "description": "Continue an earlier task instead of starting a new one.", "type": "string" } }, "required": [ "input" ] } } } }, "x-dhanu-scope": "tasks.trigger", "x-dhanu-error-codes": [ "invalid_api_key", "api_key_revoked", "api_key_expired", "api_key_ip_not_allowed", "developer_access_revoked", "api_key_project_scope", "invalid_request_body", "channel_route_not_found" ] } }, "/tasks/{taskId}": { "get": { "operationId": "tasks.read", "tags": [ "Tasks" ], "summary": "Read a task", "description": "Read one task owned by the key's workspace.", "security": [ { "apiKey": [] } ], "responses": { "200": { "description": "The task.", "content": { "application/json": { "schema": { "type": "object", "properties": { "task": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "assigneeStaffIds": { "type": "array", "items": { "type": "string" } }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "id", "title", "assigneeStaffIds", "createdAt", "updatedAt" ] } }, "required": [ "task" ] } } } }, "401": { "description": "The key is missing, unknown or revoked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key may not perform this operation, or is outside its project scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited; retry after `Retry-After` seconds.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "taskId", "in": "path", "required": true, "schema": { "type": "string" } } ], "x-dhanu-scope": "tasks.read", "x-dhanu-error-codes": [ "invalid_api_key", "api_key_revoked", "api_key_expired", "api_key_ip_not_allowed", "developer_access_revoked", "api_key_project_scope", "not_found" ] } }, "/tasks/{taskId}/messages": { "get": { "operationId": "tasks.messages", "tags": [ "Tasks" ], "summary": "Read a task's messages", "description": "The task's messages, oldest first, one page at a time.", "security": [ { "apiKey": [] } ], "responses": { "200": { "description": "One page of messages.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "role": { "type": "string" }, "text": { "type": "string" }, "createdAt": { "type": "string" } }, "required": [ "id", "role", "text", "createdAt" ] } }, "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "hasMore": { "type": "boolean" }, "messages": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "role": { "type": "string" }, "text": { "type": "string" }, "createdAt": { "type": "string" } }, "required": [ "id", "role", "text", "createdAt" ] } } }, "required": [ "data", "nextCursor", "hasMore", "messages" ] } } } }, "401": { "description": "The key is missing, unknown or revoked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key may not perform this operation, or is outside its project scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "The request failed validation, or a domain rule rejected it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited; retry after `Retry-After` seconds.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "taskId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100 }, "description": "Rows per page, 1 to 100; defaults to 50." }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" }, "description": "The nextCursor from the previous page, verbatim." } ], "x-dhanu-scope": "tasks.read", "x-dhanu-error-codes": [ "invalid_api_key", "api_key_revoked", "api_key_expired", "api_key_ip_not_allowed", "developer_access_revoked", "api_key_project_scope", "not_found", "invalid_cursor" ], "x-dhanu-deprecated-fields": [ { "field": "messages", "sunset": "2027-09-17T00:00:00Z", "replacement": "data", "note": "Mirrors data for clients written before pagination." } ] }, "post": { "operationId": "tasks.messages.create", "tags": [ "Tasks" ], "summary": "Send a message", "description": "Add a message to a task and start the reply. Returns the message you sent; the reply follows in the background.", "security": [ { "apiKey": [] } ], "responses": { "202": { "description": "The message that was sent.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "object", "properties": { "id": { "type": "string" }, "role": { "type": "string" }, "text": { "type": "string" }, "createdAt": { "type": "string" } }, "required": [ "id", "role", "text", "createdAt" ] } }, "required": [ "message" ] } } } }, "401": { "description": "The key is missing, unknown or revoked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key may not perform this operation, or is outside its project scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "The request failed validation, or a domain rule rejected it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited; retry after `Retry-After` seconds.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "taskId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "input": { "type": "string", "minLength": 1, "maxLength": 50000, "description": "The message, as plain text." }, "fileIds": { "description": "Files (from POST /files) to attach to the message.", "maxItems": 20, "type": "array", "items": { "type": "string" } } }, "required": [ "input" ] } } } }, "x-dhanu-scope": "tasks.create", "x-dhanu-error-codes": [ "invalid_api_key", "api_key_revoked", "api_key_expired", "api_key_ip_not_allowed", "developer_access_revoked", "api_key_project_scope", "invalid_request_body", "not_found" ] } }, "/tasks": { "post": { "operationId": "tasks.create", "tags": [ "Tasks" ], "summary": "Create a task", "description": "Start a task from a first message. With `staffId` the reply comes from that staff member's run; without it the workspace assistant replies. Returns at once; read the messages, stream them, or subscribe to `task.message.created`.", "security": [ { "apiKey": [] } ], "responses": { "202": { "description": "The task that was started.", "content": { "application/json": { "schema": { "type": "object", "properties": { "task": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "assigneeStaffIds": { "type": "array", "items": { "type": "string" } }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "id", "title", "assigneeStaffIds", "createdAt", "updatedAt" ] } }, "required": [ "task" ] } } } }, "401": { "description": "The key is missing, unknown or revoked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key may not perform this operation, or is outside its project scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "The request failed validation, or a domain rule rejected it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited; retry after `Retry-After` seconds.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "input": { "type": "string", "minLength": 1, "maxLength": 50000, "description": "The first message, as plain text." }, "title": { "type": "string", "maxLength": 200 }, "staffId": { "description": "Assign the task to this staff member; the reply then comes from a staff run.", "type": "string" }, "fileIds": { "description": "Files (from POST /files) to attach to the message.", "maxItems": 20, "type": "array", "items": { "type": "string" } } }, "required": [ "input" ] } } } }, "x-dhanu-scope": "tasks.create", "x-dhanu-error-codes": [ "invalid_api_key", "api_key_revoked", "api_key_expired", "api_key_ip_not_allowed", "developer_access_revoked", "api_key_project_scope", "invalid_request_body", "not_found" ] }, "get": { "operationId": "tasks.list", "tags": [ "Tasks" ], "summary": "List tasks", "description": "Tasks the key's creator can see in the workspace, newest first, one page at a time.", "security": [ { "apiKey": [] } ], "responses": { "200": { "description": "One page of tasks.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "assigneeStaffIds": { "type": "array", "items": { "type": "string" } }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "id", "title", "assigneeStaffIds", "createdAt", "updatedAt" ] } }, "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "hasMore": { "type": "boolean" } }, "required": [ "data", "nextCursor", "hasMore" ] } } } }, "401": { "description": "The key is missing, unknown or revoked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key may not perform this operation, or is outside its project scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "The request failed validation, or a domain rule rejected it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited; retry after `Retry-After` seconds.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100 }, "description": "Rows per page, 1 to 100; defaults to 50." }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" }, "description": "The nextCursor from the previous page, verbatim." } ], "x-dhanu-scope": "tasks.read", "x-dhanu-error-codes": [ "invalid_api_key", "api_key_revoked", "api_key_expired", "api_key_ip_not_allowed", "developer_access_revoked", "api_key_project_scope", "invalid_cursor" ] } }, "/tasks/{taskId}/stream": { "get": { "operationId": "tasks.stream", "tags": [ "Tasks" ], "summary": "Stream a task's replies", "description": "Server-sent events: one `message` event per completed assistant message that arrives after `cursor` (or after now), then `done` when the connection closes. Holds the connection for up to 60 seconds; reconnect with the last cursor.", "security": [ { "apiKey": [] } ], "responses": { "200": { "description": "A text/event-stream." }, "401": { "description": "The key is missing, unknown or revoked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key may not perform this operation, or is outside its project scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "The request failed validation, or a domain rule rejected it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited; retry after `Retry-After` seconds.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "taskId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Only messages after this cursor; omit to start from now." } ], "x-dhanu-scope": "tasks.read", "x-dhanu-error-codes": [ "invalid_api_key", "api_key_revoked", "api_key_expired", "api_key_ip_not_allowed", "developer_access_revoked", "api_key_project_scope", "not_found", "invalid_cursor" ] } }, "/staff": { "get": { "operationId": "staff.read", "tags": [ "Staff" ], "summary": "List staff", "description": "Every active staff member in the workspace, with the trigger address of each one that has the API channel switched on.", "security": [ { "apiKey": [] } ], "responses": { "200": { "description": "The staff.", "content": { "application/json": { "schema": { "type": "object", "properties": { "staff": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "role": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "status": { "type": "string" }, "apiAddress": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The address for POST /staff/{address}/trigger, or null when the API channel is off." } }, "required": [ "id", "name", "role", "status", "apiAddress" ] } } }, "required": [ "staff" ] } } } }, "401": { "description": "The key is missing, unknown or revoked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key may not perform this operation, or is outside its project scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited; retry after `Retry-After` seconds.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-dhanu-scope": "staff.read", "x-dhanu-error-codes": [ "invalid_api_key", "api_key_revoked", "api_key_expired", "api_key_ip_not_allowed", "developer_access_revoked", "api_key_project_scope" ] } }, "/staff/{staffId}": { "get": { "operationId": "staff.get", "tags": [ "Staff" ], "summary": "Read a staff member", "description": "One staff member by id.", "security": [ { "apiKey": [] } ], "responses": { "200": { "description": "The staff member.", "content": { "application/json": { "schema": { "type": "object", "properties": { "staff": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "role": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "status": { "type": "string" }, "apiAddress": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The address for POST /staff/{address}/trigger, or null when the API channel is off." } }, "required": [ "id", "name", "role", "status", "apiAddress" ] } }, "required": [ "staff" ] } } } }, "401": { "description": "The key is missing, unknown or revoked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key may not perform this operation, or is outside its project scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited; retry after `Retry-After` seconds.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "staffId", "in": "path", "required": true, "schema": { "type": "string" } } ], "x-dhanu-scope": "staff.read", "x-dhanu-error-codes": [ "invalid_api_key", "api_key_revoked", "api_key_expired", "api_key_ip_not_allowed", "developer_access_revoked", "api_key_project_scope", "not_found" ] } }, "/workflows": { "get": { "operationId": "workflows.read", "tags": [ "Workflows" ], "summary": "List workflows", "description": "Saved workflows the key's creator can see, each with the typed fields its form asks for.", "security": [ { "apiKey": [] } ], "responses": { "200": { "description": "The workflows.", "content": { "application/json": { "schema": { "type": "object", "properties": { "workflows": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "category": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "fields": { "type": "array", "items": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } } }, "required": [ "id", "title", "description", "category", "fields" ] } } }, "required": [ "workflows" ] } } } }, "401": { "description": "The key is missing, unknown or revoked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key may not perform this operation, or is outside its project scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited; retry after `Retry-After` seconds.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-dhanu-scope": "workflows.read", "x-dhanu-error-codes": [ "invalid_api_key", "api_key_revoked", "api_key_expired", "api_key_ip_not_allowed", "developer_access_revoked", "api_key_project_scope" ] } }, "/workflows/{workflowId}/run": { "post": { "operationId": "workflows.run", "tags": [ "Workflows" ], "summary": "Run a workflow", "description": "Fill the workflow's fields and start the task it composes. Values are validated against the stored field definitions, never trusted from the client.", "security": [ { "apiKey": [] } ], "responses": { "202": { "description": "The task that was started.", "content": { "application/json": { "schema": { "type": "object", "properties": { "task": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "assigneeStaffIds": { "type": "array", "items": { "type": "string" } }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "id", "title", "assigneeStaffIds", "createdAt", "updatedAt" ] } }, "required": [ "task" ] } } } }, "401": { "description": "The key is missing, unknown or revoked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key may not perform this operation, or is outside its project scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "The request failed validation, or a domain rule rejected it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited; retry after `Retry-After` seconds.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "workflowId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "values": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "array", "items": { "type": "string" } } ] }, "description": "One entry per field key; required fields must be present." } }, "required": [ "values" ] } } } }, "x-dhanu-scope": "workflows.run", "x-dhanu-error-codes": [ "invalid_api_key", "api_key_revoked", "api_key_expired", "api_key_ip_not_allowed", "developer_access_revoked", "api_key_project_scope", "invalid_request_body", "not_found", "invalid_workflow_values" ] } }, "/files/uploads": { "post": { "operationId": "files.uploads.create", "tags": [ "Files" ], "summary": "Start a presigned upload", "description": "For files over the direct-upload limit: returns presigned part URLs to PUT the bytes to, then complete the upload.", "security": [ { "apiKey": [] } ], "responses": { "201": { "description": "The upload session.", "content": { "application/json": { "schema": { "type": "object", "properties": { "upload": { "type": "object", "properties": { "sessionId": { "type": "string" }, "partSize": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "partCount": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "parts": { "type": "array", "items": { "type": "object", "properties": { "partNumber": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "url": { "type": "string" } }, "required": [ "partNumber", "url" ] } }, "expiresInSeconds": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "sessionId", "partSize", "partCount", "parts", "expiresInSeconds" ] } }, "required": [ "upload" ] } } } }, "401": { "description": "The key is missing, unknown or revoked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key may not perform this operation, or is outside its project scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "The request failed validation, or a domain rule rejected it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited; retry after `Retry-After` seconds.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "filename": { "type": "string", "minLength": 1, "maxLength": 255 }, "mimeType": { "type": "string", "minLength": 1 }, "sizeBytes": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "filename", "mimeType", "sizeBytes" ] } } } }, "x-dhanu-scope": "files.write", "x-dhanu-error-codes": [ "invalid_api_key", "api_key_revoked", "api_key_expired", "api_key_ip_not_allowed", "developer_access_revoked", "api_key_project_scope", "invalid_request_body", "unsupported_media_type", "file_too_large", "storage_quota_exceeded" ] } }, "/files/uploads/{uploadId}/complete": { "post": { "operationId": "files.uploads.complete", "tags": [ "Files" ], "summary": "Complete a presigned upload", "description": "Finish a multipart upload with the ETag of each part; returns the file.", "security": [ { "apiKey": [] } ], "responses": { "201": { "description": "The file.", "content": { "application/json": { "schema": { "type": "object", "properties": { "file": { "type": "object", "properties": { "id": { "type": "string" }, "filename": { "type": "string" }, "mimeType": { "type": "string" }, "sizeBytes": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "kind": { "type": "string", "description": "file, image, audio, video, canvas, page, sheet, deck or app." }, "createdAt": { "type": "string" } }, "required": [ "id", "filename", "mimeType", "sizeBytes", "kind", "createdAt" ] } }, "required": [ "file" ] } } } }, "401": { "description": "The key is missing, unknown or revoked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key may not perform this operation, or is outside its project scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "The request failed validation, or a domain rule rejected it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited; retry after `Retry-After` seconds.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "uploadId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "parts": { "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "partNumber": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "etag": { "type": "string", "minLength": 1 } }, "required": [ "partNumber", "etag" ] } } }, "required": [ "parts" ] } } } }, "x-dhanu-scope": "files.write", "x-dhanu-error-codes": [ "invalid_api_key", "api_key_revoked", "api_key_expired", "api_key_ip_not_allowed", "developer_access_revoked", "api_key_project_scope", "invalid_request_body", "not_found" ] } }, "/files": { "post": { "operationId": "files.write", "tags": [ "Files" ], "summary": "Upload a file", "description": "Multipart form with one `file` field, up to 25 MB, stored in the key creator's drive.", "security": [ { "apiKey": [] } ], "responses": { "201": { "description": "The file.", "content": { "application/json": { "schema": { "type": "object", "properties": { "file": { "type": "object", "properties": { "id": { "type": "string" }, "filename": { "type": "string" }, "mimeType": { "type": "string" }, "sizeBytes": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "kind": { "type": "string", "description": "file, image, audio, video, canvas, page, sheet, deck or app." }, "createdAt": { "type": "string" } }, "required": [ "id", "filename", "mimeType", "sizeBytes", "kind", "createdAt" ] } }, "required": [ "file" ] } } } }, "401": { "description": "The key is missing, unknown or revoked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key may not perform this operation, or is outside its project scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "The request failed validation, or a domain rule rejected it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited; retry after `Retry-After` seconds.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-dhanu-scope": "files.write", "x-dhanu-error-codes": [ "invalid_api_key", "api_key_revoked", "api_key_expired", "api_key_ip_not_allowed", "developer_access_revoked", "api_key_project_scope", "invalid_request_body", "unsupported_media_type", "file_too_large", "storage_quota_exceeded" ] } }, "/files/{fileId}": { "get": { "operationId": "files.read", "tags": [ "Files" ], "summary": "Read a file", "description": "A file's metadata.", "security": [ { "apiKey": [] } ], "responses": { "200": { "description": "The file.", "content": { "application/json": { "schema": { "type": "object", "properties": { "file": { "type": "object", "properties": { "id": { "type": "string" }, "filename": { "type": "string" }, "mimeType": { "type": "string" }, "sizeBytes": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "kind": { "type": "string", "description": "file, image, audio, video, canvas, page, sheet, deck or app." }, "createdAt": { "type": "string" } }, "required": [ "id", "filename", "mimeType", "sizeBytes", "kind", "createdAt" ] } }, "required": [ "file" ] } } } }, "401": { "description": "The key is missing, unknown or revoked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key may not perform this operation, or is outside its project scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited; retry after `Retry-After` seconds.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "fileId", "in": "path", "required": true, "schema": { "type": "string" } } ], "x-dhanu-scope": "files.read", "x-dhanu-error-codes": [ "invalid_api_key", "api_key_revoked", "api_key_expired", "api_key_ip_not_allowed", "developer_access_revoked", "api_key_project_scope", "not_found" ] } }, "/files/{fileId}/download": { "get": { "operationId": "files.download", "tags": [ "Files" ], "summary": "Download a file", "description": "The file's bytes, with its content type and a download disposition.", "security": [ { "apiKey": [] } ], "responses": { "200": { "description": "The bytes." }, "401": { "description": "The key is missing, unknown or revoked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key may not perform this operation, or is outside its project scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited; retry after `Retry-After` seconds.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "fileId", "in": "path", "required": true, "schema": { "type": "string" } } ], "x-dhanu-scope": "files.read", "x-dhanu-error-codes": [ "invalid_api_key", "api_key_revoked", "api_key_expired", "api_key_ip_not_allowed", "developer_access_revoked", "api_key_project_scope", "not_found" ] } }, "/files/{fileId}/export": { "get": { "operationId": "files.export", "tags": [ "Files" ], "summary": "Export an artifact", "description": "A page as html, a sheet as csv or xlsx, a deck as pptx or, once rendered, pdf.", "security": [ { "apiKey": [] } ], "responses": { "200": { "description": "The exported bytes." }, "401": { "description": "The key is missing, unknown or revoked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key may not perform this operation, or is outside its project scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "The request failed validation, or a domain rule rejected it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited; retry after `Retry-After` seconds.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "fileId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "format", "in": "query", "required": true, "schema": { "type": "string", "enum": [ "html", "csv", "xlsx", "pdf", "pptx" ] }, "description": "Pages export as html, sheets as csv or xlsx, decks as pdf (after render) or pptx." } ], "x-dhanu-scope": "files.read", "x-dhanu-error-codes": [ "invalid_api_key", "api_key_revoked", "api_key_expired", "api_key_ip_not_allowed", "developer_access_revoked", "api_key_project_scope", "not_found", "invalid_request_body", "unsupported_export_format", "export_not_rendered" ] } }, "/files/{fileId}/render": { "post": { "operationId": "files.render", "tags": [ "Files" ], "summary": "Render a deck to PDF", "description": "Starts the PDF render for a deck and returns a job; export as pdf once it succeeds.", "security": [ { "apiKey": [] } ], "responses": { "202": { "description": "The render job.", "content": { "application/json": { "schema": { "type": "object", "properties": { "job": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string" }, "status": { "type": "string", "enum": [ "queued", "running", "succeeded", "failed", "cancelled" ] }, "result": { "anyOf": [ {}, { "type": "null" } ] }, "error": { "anyOf": [ { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] }, { "type": "null" } ] }, "createdAt": { "type": "string" }, "completedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "type", "status", "result", "error", "createdAt", "completedAt" ] } }, "required": [ "job" ] } } } }, "401": { "description": "The key is missing, unknown or revoked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key may not perform this operation, or is outside its project scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited; retry after `Retry-After` seconds.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "fileId", "in": "path", "required": true, "schema": { "type": "string" } } ], "x-dhanu-scope": "files.write", "x-dhanu-error-codes": [ "invalid_api_key", "api_key_revoked", "api_key_expired", "api_key_ip_not_allowed", "developer_access_revoked", "api_key_project_scope", "not_found", "unsupported_export_format" ] } }, "/videos": { "post": { "operationId": "videos.generate", "tags": [ "Videos" ], "summary": "Generate a video", "description": "Start a video render on a task. Returns the video (status `generating`) and the job to follow; `video.ready` fires when it is done.", "security": [ { "apiKey": [] } ], "responses": { "202": { "description": "The video and its render job.", "content": { "application/json": { "schema": { "type": "object", "properties": { "video": { "type": "object", "properties": { "id": { "type": "string" }, "taskId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "title": { "type": "string" }, "status": { "type": "string", "enum": [ "generating", "ready", "failed" ] }, "error": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "aspectRatio": { "type": "string" }, "resolution": { "type": "string" }, "durationSeconds": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "id", "taskId", "title", "status", "error", "aspectRatio", "resolution", "durationSeconds", "createdAt", "updatedAt" ] }, "jobId": { "type": "string" } }, "required": [ "video", "jobId" ] } } } }, "401": { "description": "The key is missing, unknown or revoked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key may not perform this operation, or is outside its project scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "The request failed validation, or a domain rule rejected it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited; retry after `Retry-After` seconds.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "taskId": { "type": "string", "description": "The task the video belongs to (from POST /tasks)." }, "prompt": { "type": "string", "minLength": 1, "maxLength": 2000 }, "negativePrompt": { "type": "string", "maxLength": 2000 }, "aspectRatio": { "type": "string", "enum": [ "16:9", "9:16" ] }, "resolution": { "type": "string", "enum": [ "720p", "1080p" ] }, "durationSeconds": { "type": "integer", "minimum": 1, "maximum": 60 } }, "required": [ "taskId", "prompt" ] } } } }, "x-dhanu-scope": "videos.generate", "x-dhanu-error-codes": [ "invalid_api_key", "api_key_revoked", "api_key_expired", "api_key_ip_not_allowed", "developer_access_revoked", "api_key_project_scope", "invalid_request_body", "project_id_required", "insufficient_credits", "key_spend_limit_reached", "invalid_generation_prompt", "not_found" ] } }, "/videos/{videoId}": { "get": { "operationId": "videos.read", "tags": [ "Videos" ], "summary": "Read a video", "description": "A video's status; `ready` means the file can be fetched.", "security": [ { "apiKey": [] } ], "responses": { "200": { "description": "The video.", "content": { "application/json": { "schema": { "type": "object", "properties": { "video": { "type": "object", "properties": { "id": { "type": "string" }, "taskId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "title": { "type": "string" }, "status": { "type": "string", "enum": [ "generating", "ready", "failed" ] }, "error": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "aspectRatio": { "type": "string" }, "resolution": { "type": "string" }, "durationSeconds": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "id", "taskId", "title", "status", "error", "aspectRatio", "resolution", "durationSeconds", "createdAt", "updatedAt" ] } }, "required": [ "video" ] } } } }, "401": { "description": "The key is missing, unknown or revoked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key may not perform this operation, or is outside its project scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited; retry after `Retry-After` seconds.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "videoId", "in": "path", "required": true, "schema": { "type": "string" } } ], "x-dhanu-scope": "videos.read", "x-dhanu-error-codes": [ "invalid_api_key", "api_key_revoked", "api_key_expired", "api_key_ip_not_allowed", "developer_access_revoked", "api_key_project_scope", "not_found" ] } }, "/videos/{videoId}/file": { "get": { "operationId": "videos.file", "tags": [ "Videos" ], "summary": "Download a video", "description": "The rendered MP4, with HTTP range support for scrubbing.", "security": [ { "apiKey": [] } ], "responses": { "200": { "description": "The bytes." }, "401": { "description": "The key is missing, unknown or revoked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key may not perform this operation, or is outside its project scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited; retry after `Retry-After` seconds.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "videoId", "in": "path", "required": true, "schema": { "type": "string" } } ], "x-dhanu-scope": "videos.read", "x-dhanu-error-codes": [ "invalid_api_key", "api_key_revoked", "api_key_expired", "api_key_ip_not_allowed", "developer_access_revoked", "api_key_project_scope", "not_found", "video_not_ready" ] } }, "/brain/search": { "post": { "operationId": "brain.search", "tags": [ "Brain" ], "summary": "Search the brain", "description": "Semantic search over the brain pages the key's creator can see.", "security": [ { "apiKey": [] } ], "responses": { "200": { "description": "Ranked results.", "content": { "application/json": { "schema": { "type": "object", "properties": { "results": { "type": "array", "items": { "type": "object", "properties": { "pageId": { "type": "string" }, "slug": { "type": "string" }, "title": { "type": "string" }, "score": { "type": "number" }, "snippet": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "pageId", "slug", "title", "score", "snippet" ] } } }, "required": [ "results" ] } } } }, "401": { "description": "The key is missing, unknown or revoked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key may not perform this operation, or is outside its project scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "The request failed validation, or a domain rule rejected it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited; retry after `Retry-After` seconds.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "query": { "type": "string", "minLength": 1, "maxLength": 2000 } }, "required": [ "query" ] } } } }, "x-dhanu-scope": "brain.search", "x-dhanu-error-codes": [ "invalid_api_key", "api_key_revoked", "api_key_expired", "api_key_ip_not_allowed", "developer_access_revoked", "api_key_project_scope", "invalid_request_body" ] } }, "/transcriptions": { "post": { "operationId": "audio.transcribe", "tags": [ "Audio" ], "summary": "Transcribe audio", "description": "Multipart form with one `audio` field; returns the transcript.", "security": [ { "apiKey": [] } ], "responses": { "201": { "description": "The transcript.", "content": { "application/json": { "schema": { "type": "object", "properties": { "text": { "type": "string" }, "cost": { "type": "object", "properties": { "amount": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "In the workspace currency's minor unit." }, "currency": { "type": "string" } }, "required": [ "amount", "currency" ] } }, "required": [ "text", "cost" ] } } } }, "401": { "description": "The key is missing, unknown or revoked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key may not perform this operation, or is outside its project scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "The request failed validation, or a domain rule rejected it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited; retry after `Retry-After` seconds.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-dhanu-scope": "audio.transcribe", "x-dhanu-error-codes": [ "invalid_api_key", "api_key_revoked", "api_key_expired", "api_key_ip_not_allowed", "developer_access_revoked", "api_key_project_scope", "invalid_request_body", "project_id_required", "insufficient_credits", "key_spend_limit_reached", "invalid_generation_prompt", "unsupported_media_type" ] } }, "/ocr": { "post": { "operationId": "ocr.extract", "tags": [ "OCR" ], "summary": "Extract text", "description": "Runs OCR over a base64 image or PDF in the background; the job's result carries the text.", "security": [ { "apiKey": [] } ], "responses": { "202": { "description": "The OCR job.", "content": { "application/json": { "schema": { "type": "object", "properties": { "job": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string" }, "status": { "type": "string", "enum": [ "queued", "running", "succeeded", "failed", "cancelled" ] }, "result": { "anyOf": [ {}, { "type": "null" } ] }, "error": { "anyOf": [ { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] }, { "type": "null" } ] }, "createdAt": { "type": "string" }, "completedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "type", "status", "result", "error", "createdAt", "completedAt" ] } }, "required": [ "job" ] } } } }, "401": { "description": "The key is missing, unknown or revoked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key may not perform this operation, or is outside its project scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "The request failed validation, or a domain rule rejected it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited; retry after `Retry-After` seconds.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "string", "minLength": 1, "description": "The file bytes, base64-encoded." }, "mimeType": { "type": "string", "minLength": 1 }, "filename": { "type": "string", "maxLength": 255 }, "languageHint": { "description": "The document's language: ne, en, or auto to decide from the filename.", "type": "string", "enum": [ "ne", "en", "auto" ] } }, "required": [ "data", "mimeType" ] } } } }, "x-dhanu-scope": "ocr.extract", "x-dhanu-error-codes": [ "invalid_api_key", "api_key_revoked", "api_key_expired", "api_key_ip_not_allowed", "developer_access_revoked", "api_key_project_scope", "invalid_request_body", "project_id_required", "insufficient_credits", "key_spend_limit_reached", "invalid_generation_prompt" ] } }, "/embeddings": { "post": { "operationId": "embeddings.create", "tags": [ "Embeddings" ], "summary": "Create embeddings", "description": "One vector per input text, in order.", "security": [ { "apiKey": [] } ], "responses": { "201": { "description": "The vectors.", "content": { "application/json": { "schema": { "type": "object", "properties": { "embeddings": { "type": "array", "items": { "type": "array", "items": { "type": "number" } } }, "model": { "type": "string" }, "usage": { "type": "object", "properties": { "inputTokens": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "inputTokens" ] }, "cost": { "type": "object", "properties": { "amount": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "In the workspace currency's minor unit." }, "currency": { "type": "string" } }, "required": [ "amount", "currency" ] } }, "required": [ "embeddings", "model", "usage", "cost" ] } } } }, "401": { "description": "The key is missing, unknown or revoked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key may not perform this operation, or is outside its project scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "The request failed validation, or a domain rule rejected it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited; retry after `Retry-After` seconds.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "input": { "minItems": 1, "maxItems": 100, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 8000 } }, "projectId": { "description": "Which of the key's projects the call runs against. Required when the key can access more than one project.", "type": "string" } }, "required": [ "input" ] } } } }, "x-dhanu-scope": "embeddings.create", "x-dhanu-error-codes": [ "invalid_api_key", "api_key_revoked", "api_key_expired", "api_key_ip_not_allowed", "developer_access_revoked", "api_key_project_scope", "invalid_request_body", "project_id_required", "insufficient_credits", "key_spend_limit_reached", "invalid_generation_prompt" ] } } }, "components": { "securitySchemes": { "apiKey": { "type": "http", "scheme": "bearer" } }, "schemas": { "Error": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }