{"openapi":"3.1.0","info":{"version":"1.0.0","title":"Kindo API","description":"Kindo API"},"servers":[{"url":"/v1"}],"components":{"securitySchemes":{"xApiKeyHeaderAuth":{"type":"apiKey","in":"header","name":"x-api-key","description":"Use your Kindo API key in the x-api-key header. Consulted only when no Authorization header is present."},"bearerApiKeyAuth":{"type":"http","scheme":"bearer","description":"Use your Kindo API key as a Bearer token in the Authorization header. When both Authorization: Bearer and x-api-key are provided, Bearer takes precedence. If the Authorization header is present but malformed, the request is rejected."}},"schemas":{"GetConversationItemParams":{"type":"object","properties":{"conversation_id":{"type":"string","description":"The conversation ID (conv_-prefixed or bare)"},"item_id":{"type":"string","description":"The item ID (msg_ for messages or tool call ID)"}},"required":["conversation_id","item_id"]},"ListConversationItemsParams":{"type":"object","properties":{"conversation_id":{"type":"string","description":"The conversation ID (conv_-prefixed or bare)"}},"required":["conversation_id"]},"ListConversationItemsQuery":{"type":"object","properties":{"limit":{"type":"integer","minimum":1,"maximum":100,"default":20,"description":"Messages per page (1-100). Each message may expand to multiple items."},"order":{"type":"string","enum":["asc","desc"],"default":"desc","description":"Sort order by message index"},"after":{"type":"string","description":"Cursor: return items after this item ID"}}},"ListModelsQuery":{"type":"object","properties":{"include_agents":{"type":"string","enum":["true","false"],"description":"When \"true\", append the caller’s accessible agents as `agent/<uuid>` model entries. Defaults to \"false\"."},"limit":{"type":"integer","minimum":1,"maximum":1000,"description":"Max agent entries to return (1-1000, default 500). Ignored unless `include_agents=true`. Proxied models are not affected. Out-of-range values are clamped, not rejected: values below 1 (or non-numeric) fall back to the default 500, and values above 1000 are capped at 1000."},"after":{"type":["integer","null"],"minimum":0,"description":"Offset into the agents list for the next page (default 0). Pass the `next_after` value from the previous response. Ignored unless `include_agents=true`. Out-of-range values are clamped, not rejected: negative or non-numeric values fall back to 0."}}},"ListInputItemsParams":{"type":"object","properties":{"response_id":{"type":"string","description":"The response ID (format: resp_<conversationId>_<index>)"}},"required":["response_id"]},"GetResponseParams":{"type":"object","properties":{"response_id":{"type":"string","description":"The response ID (format: resp_<conversationId>_<index>, or resp_run_<runId> for agent-run-backed responses)"}},"required":["response_id"]},"GetResponseQuery":{"type":"object","properties":{"stream":{"type":"string","enum":["true","false"],"description":"Set to `true` to resume the response as Server-Sent Events instead of returning the final JSON object."},"starting_after":{"type":["integer","null"],"minimum":0,"description":"Resume cursor: replay only events whose `sequence_number` is greater than this value. Requires `stream=true`. Omit to replay from the beginning. Agent-run responses (`resp_run_*` ids) support replay-only resume: `starting_after` must be 0 or omitted for those ids, and a positive cursor is rejected with HTTP 400."}}},"AgentCreateResponse":{"type":"object","properties":{"agentId":{"type":"string","format":"uuid"},"warnings":{"type":"array","items":{"$ref":"#/components/schemas/AgentCreateWarning"},"description":"One entry for each requested model, by UUID or API model name, that was unavailable and fell back. Omitted when no model fell back."}},"required":["agentId"]},"AgentCreateWarning":{"type":"object","properties":{"field":{"type":"string","description":"The request field that fell back, as a dotted path: modelId or steps.<index>.llmStep.model.id."},"requested":{"type":"string","description":"The value sent in the field, exactly as sent."},"message":{"type":"string","description":"What happened to the requested model."}},"required":["field","requested","message"]},"ErrorResponse":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error","message"]},"AgentCreateRequestBody":{"type":"object","properties":{"id":{"type":"string"},"displayName":{"type":["string","null"]},"description":{"type":["string","null"]},"systemPrompt":{"type":["string","null"]},"modelId":{"type":"string"},"conversationMetadataSchema":{"type":"object","properties":{"type":{"type":"string","enum":["object"]},"properties":{"type":"object","additionalProperties":{"anyOf":[{"type":"object","properties":{"type":{"type":"string","enum":["string"]},"title":{"type":"string","maxLength":4096},"description":{"type":"string","maxLength":4096},"enum":{"type":"array","items":{"type":"string","maxLength":4096},"maxItems":128},"format":{"type":"string","enum":["date-time","uri"]},"minLength":{"type":"integer","minimum":0,"maximum":4096},"maxLength":{"type":"integer","minimum":0,"maximum":4096}},"required":["type"]},{"type":"object","properties":{"type":{"type":"string","enum":["integer","number"]},"title":{"type":"string","maxLength":4096},"description":{"type":"string","maxLength":4096},"minimum":{"type":"number"},"maximum":{"type":"number"}},"required":["type"]},{"type":"object","properties":{"type":{"type":"string","enum":["boolean"]},"title":{"type":"string","maxLength":4096},"description":{"type":"string","maxLength":4096}},"required":["type"]},{"type":"object","properties":{"type":{"type":"string","enum":["array"]},"title":{"type":"string","maxLength":4096},"description":{"type":"string","maxLength":4096},"items":{"anyOf":[{"type":"object","properties":{"type":{"type":"string","enum":["string"]},"title":{"type":"string","maxLength":4096},"description":{"type":"string","maxLength":4096},"enum":{"type":"array","items":{"type":"string","maxLength":4096},"maxItems":128},"format":{"type":"string","enum":["date-time","uri"]},"minLength":{"type":"integer","minimum":0,"maximum":4096},"maxLength":{"type":"integer","minimum":0,"maximum":4096}},"required":["type"]},{"type":"object","properties":{"type":{"type":"string","enum":["integer","number"]},"title":{"type":"string","maxLength":4096},"description":{"type":"string","maxLength":4096},"minimum":{"type":"number"},"maximum":{"type":"number"}},"required":["type"]},{"type":"object","properties":{"type":{"type":"string","enum":["boolean"]},"title":{"type":"string","maxLength":4096},"description":{"type":"string","maxLength":4096}},"required":["type"]}]}},"required":["type","items"]},{"type":"object","properties":{"type":{"type":"string","enum":["object"]},"title":{"type":"string","maxLength":4096},"description":{"type":"string","maxLength":4096},"properties":{"type":"object","additionalProperties":{"anyOf":[{"type":"object","properties":{"type":{"type":"string","enum":["string"]},"title":{"type":"string","maxLength":4096},"description":{"type":"string","maxLength":4096},"enum":{"type":"array","items":{"type":"string","maxLength":4096},"maxItems":128},"format":{"type":"string","enum":["date-time","uri"]},"minLength":{"type":"integer","minimum":0,"maximum":4096},"maxLength":{"type":"integer","minimum":0,"maximum":4096}},"required":["type"]},{"type":"object","properties":{"type":{"type":"string","enum":["integer","number"]},"title":{"type":"string","maxLength":4096},"description":{"type":"string","maxLength":4096},"minimum":{"type":"number"},"maximum":{"type":"number"}},"required":["type"]},{"type":"object","properties":{"type":{"type":"string","enum":["boolean"]},"title":{"type":"string","maxLength":4096},"description":{"type":"string","maxLength":4096}},"required":["type"]}]}},"required":{"type":"array","items":{"type":"string"},"maxItems":64}},"required":["type","properties"]}]}},"required":{"type":"array","items":{"type":"string"},"maxItems":64},"additionalProperties":{"type":"boolean"}},"required":["type","properties"]},"toolServerConfigs":{"type":"array","items":{"type":"object","properties":{"enabled":{"type":"boolean"},"id":{"type":"string"},"integrationConfigNangoId":{"type":"string"},"integrationConnectionId":{"type":["string","null"]},"integrationConnectionIds":{"type":"array","items":{"type":"string"}},"useMock":{"type":["boolean","null"]}},"required":["enabled","id","integrationConfigNangoId","integrationConnectionId"]}},"dashboardId":{"type":["string","null"]},"sourceWorkflowId":{"type":["string","null"]},"isMockMode":{"type":"boolean"},"isAvailableAsChildWorkflow":{"type":"boolean"},"lastGenerationPrompt":{"type":["string","null"]},"creator":{"type":"object","properties":{"id":{"type":"string"},"email":{"type":"string"}},"required":["id","email"]},"triggers":{"type":"array","items":{"type":"object","properties":{"conditions":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string"},"id":{"type":"string"},"type":{"type":"string"},"value":{"type":"string"}},"required":["field","id","type","value"]}},"cronExpression":{"type":["string","null"]},"directWebhookEnabled":{"type":"boolean"},"displayTimeZone":{"type":["string","null"]},"enabled":{"type":"boolean"},"id":{"type":"string"},"inputId":{"type":["string","null"]},"integrationConnectionId":{"type":["string","null"]},"integrationInputType":{"type":["string","null"]},"naturalLanguageCondition":{"type":["string","null"]},"operator":{"type":["string","null"]}},"required":["conditions","cronExpression","directWebhookEnabled","displayTimeZone","enabled","id","inputId","integrationConnectionId","integrationInputType","naturalLanguageCondition","operator"]}},"steps":{"type":"array","items":{"anyOf":[{"type":"object","properties":{"id":{"type":"string"},"stepNumber":{"type":"number"},"displayName":{"type":["string","null"]},"inputIds":{"type":"array","items":{"type":"string"}},"staticContentIds":{"type":"array","items":{"type":"string"}},"llmStep":{"type":"object","properties":{"id":{"type":"string"},"model":{"type":"object","properties":{"id":{"type":"string"},"displayName":{"type":"string"}},"required":["id"]},"promptTemplate":{"type":"string"},"llmInteractionMode":{"type":"string"},"toolServerConfigs":{"type":"array","items":{"type":"object","properties":{"enabled":{"type":"boolean"},"id":{"type":"string"},"integrationConfigNangoId":{"type":"string"},"integrationConnectionId":{"type":["string","null"]},"integrationConnectionIds":{"type":"array","items":{"type":"string"}},"useMock":{"type":["boolean","null"]}},"required":["enabled","id","integrationConfigNangoId","integrationConnectionId"]}}},"required":["id","model","promptTemplate","llmInteractionMode","toolServerConfigs"]}},"required":["id","stepNumber","displayName","inputIds","staticContentIds","llmStep"]},{"type":"object","properties":{"id":{"type":"string"},"stepNumber":{"type":"number"},"displayName":{"type":["string","null"]},"inputIds":{"type":"array","items":{"type":"string"}},"staticContentIds":{"type":"array","items":{"type":"string"}},"apiActionStep":{"type":"object","properties":{"id":{"type":"string"},"endpoint":{"anyOf":[{"type":"object","properties":{"text":{"type":"string","format":"uri"}},"required":["text"]},{"type":"object","properties":{"dynamicPrompt":{"type":"string"}},"required":["dynamicPrompt"]}]},"headers":{"type":"object","additionalProperties":{"anyOf":[{"type":"object","properties":{"text":{"type":"string"}},"required":["text"]},{"type":"object","properties":{"secretId":{"type":"string","format":"uuid"}},"required":["secretId"]},{"type":"object","properties":{"dynamicPrompt":{"type":"string"}},"required":["dynamicPrompt"]}]}},"method":{"type":"string"},"parameters":{"type":["object","null"],"additionalProperties":{"anyOf":[{"type":"object","properties":{"text":{"type":"string"}},"required":["text"]},{"type":"object","properties":{"secretId":{"type":"string","format":"uuid"}},"required":["secretId"]},{"type":"object","properties":{"dynamicPrompt":{"type":"string"}},"required":["dynamicPrompt"]}]}},"body":{"anyOf":[{"type":"object","properties":{"requestBody":{"type":"object","additionalProperties":{}}},"required":["requestBody"]},{"type":"object","properties":{"dynamicPrompt":{"type":"string"}},"required":["dynamicPrompt"]},{"type":"null"}]},"secrets":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"label":{"type":"string"}},"required":["id","label"]}},"validateResponse":{"type":"boolean"}},"required":["id","endpoint","headers","method","parameters","body","secrets","validateResponse"]}},"required":["id","stepNumber","displayName","inputIds","staticContentIds","apiActionStep"]},{"type":"object","properties":{"id":{"type":"string"},"stepNumber":{"type":"number"},"displayName":{"type":["string","null"]},"inputIds":{"type":"array","items":{"type":"string"}},"staticContentIds":{"type":"array","items":{"type":"string"}},"skillScriptStep":{"type":"object","properties":{"id":{"type":"string"},"skillLineageId":{"type":"string"},"scriptPath":{"type":"string"},"timeoutSeconds":{"type":"number"},"allowInference":{"type":"boolean"}},"required":["id","skillLineageId","scriptPath","timeoutSeconds","allowInference"]}},"required":["id","stepNumber","displayName","inputIds","staticContentIds","skillScriptStep"]}]}},"inputs":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string","enum":["TEXT_OR_CONTENT","TICKETING_INTEGRATION_TICKET"]},"displayName":{"type":"string"},"integrationName":{"type":["string","null"]},"templateResolutionName":{"type":["string","null"]},"integrationConnectionId":{"type":["string","null"]},"triggerId":{"type":["string","null"]}},"required":["id","type","displayName","integrationName","templateResolutionName","integrationConnectionId","triggerId"]}},"skills":{"type":"array","items":{"type":"object","properties":{"skillLineageId":{"type":"string"},"skillName":{"type":"string"}},"required":["skillLineageId","skillName"]}},"knowledgeStoreContentIds":{"type":"array","items":{"type":"string"}}},"required":["id","displayName","description","systemPrompt","sourceWorkflowId","isMockMode","isAvailableAsChildWorkflow","lastGenerationPrompt","creator","triggers","steps","inputs","knowledgeStoreContentIds"],"description":"The agent definition: its steps, inputs, prompts, and settings. Send a file downloaded from Kindo as-is, or write one from scratch. Select the agent model with modelId and each LLM step model with model.id. Each field accepts an internal model UUID or an API model name from GET /v1/models. UUID-shaped strings are internal IDs; other nonblank strings are API model names, resolved against the chat models the API-key owner can use. An unavailable UUID or name does not return 400: a step uses the default step model, an agent-level model is cleared, and the response warnings list each one. Step displayName is optional. Kindo assigns new IDs to the agent and its parts while preserving matching references. Inaccessible integration connections are left unset; secrets and content must be accessible, skills (referenced by lineage in `skills` and by script steps) must be ones the caller can attach, and tool integrations must be set up on this deployment."},"AgentFetchResponse":{"type":"object","properties":{"agentId":{"type":"string","format":"uuid"},"createdAt":{"type":"string","format":"date-time"},"creatorName":{"type":"string"},"description":{"type":"string"},"lastRunAtUtc":{"type":["string","null"],"format":"date-time"},"modelsInUse":{"type":"array","items":{"type":"string"}},"recentRunIds":{"type":"array","items":{"type":"string","format":"uuid"}},"nextCursor":{"type":["string","null"],"description":"Opaque pagination token for fetching the next page of runs. Present (string or null) only when one of the run-list query parameters is supplied (`limit`, `cursor`, `startDate`, or `endDate`); absent (undefined) otherwise. `null` indicates there are no more pages."},"hasTriggers":{"type":"boolean"},"inputs":{"type":"array","items":{"type":"string"}},"name":{"type":"string"},"metadata":{"type":"object","properties":{"userPermissions":{"type":"array","items":{"type":"string","enum":["delete","edit","share","spawn","view"]}}},"required":["userPermissions"]}},"required":["agentId","createdAt","creatorName","description","lastRunAtUtc","modelsInUse","recentRunIds","hasTriggers","inputs","name","metadata"]},"AgentRunEvalsResponse":{"type":"object","properties":{"runId":{"type":"string","format":"uuid"},"result":{"type":"string","enum":["fail","partial","pass","pending","skipped","unknown"],"description":"Aggregate eval result: \"pass\" = all objectives satisfied; \"fail\" = at least one failed; \"pending\" = run in progress or verdicts not yet written; \"skipped\" = run failed/cancelled before evaluation or no objectives evaluated; \"unknown\" = no definitive result."},"steps":{"type":"array","items":{"type":"object","properties":{"stepNumber":{"type":"number","description":"1-indexed step position in the run."},"name":{"type":["string","null"],"description":"Display name of the step, or null if unnamed."},"result":{"type":["string","null"],"enum":["fail","not_evaluated","pass","unknown",null],"description":"Step eval result: \"pass\" = objective satisfied; \"fail\" = objective not satisfied; \"not_evaluated\" = evaluation did not run; \"unknown\" = verdict could not be determined. Null when no verdict has been recorded yet."},"explanation":{"type":["string","null"],"description":"Free-form explanation of the verdict; null when not evaluated."}},"required":["stepNumber","name","result","explanation"]}}},"required":["runId","result","steps"]},"AgentRunResultResponse":{"type":"object","properties":{"runId":{"type":"string","format":"uuid"},"agentId":{"type":["string","null"],"format":"uuid"},"conversationId":{"type":["string","null"],"description":"The conversation ID associated with this run. Use with GET /v1/conversations/{conversation_id}/items to read conversation history."},"createdAtUtc":{"type":"string","format":"date-time"},"endedAtUtc":{"type":["string","null"],"format":"date-time"},"result":{"type":["string","null"]},"status":{"type":"string","enum":["cancelled","failure","in_progress","success"]}},"required":["runId","agentId","conversationId","createdAtUtc","endedAtUtc","result","status"]},"AgentListResponse":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","properties":{"agentId":{"type":"string","format":"uuid"},"createdAt":{"type":"string","format":"date-time"},"creatorName":{"type":"string"},"description":{"type":"string"},"name":{"type":"string"},"metadata":{"type":"object","properties":{"userPermissions":{"type":"array","items":{"type":"string","enum":["delete","edit","share","spawn","view"]}}},"required":["userPermissions"]}},"required":["agentId","createdAt","creatorName","description","name","metadata"]}},"total":{"type":"number"}},"required":["items","total"]},"AgentRunCreationResponse":{"type":"object","properties":{"runId":{"type":"string","format":"uuid"},"conversationId":{"type":"string","description":"The conversation ID associated with this run. Use with GET /v1/conversations/{conversation_id}/items to read conversation history."}},"required":["runId","conversationId"]},"AgentRunCreationRequestBody":{"type":"object","properties":{"agentId":{"type":"string","format":"uuid"},"inputs":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"value":{"type":"string"}},"required":["name","value"]}}},"required":["agentId"]},"ChatCompletionsResponse":{"type":"object","properties":{"id":{"type":"string"},"object":{"type":"string","enum":["chat.completion"]},"created":{"type":"number"},"model":{"type":"string"},"choices":{"type":"array","items":{"type":"object","properties":{"index":{"type":"number"},"message":{"type":"object","properties":{"role":{"type":"string"},"content":{"type":["string","null"]},"tool_calls":{"type":"array","items":{}}},"required":["role","content"],"additionalProperties":{}},"finish_reason":{"type":["string","null"]}},"required":["index","message","finish_reason"],"additionalProperties":{}}},"usage":{"type":"object","properties":{"prompt_tokens":{"type":"number"},"completion_tokens":{"type":"number"},"total_tokens":{"type":"number"}},"required":["prompt_tokens","completion_tokens","total_tokens"],"additionalProperties":{}}},"required":["id","object","created","model","choices"],"additionalProperties":{},"description":"Response mirrors the OpenAI Chat Completion shape. Additional fields (for example `system_fingerprint`, `service_tier`, `logprobs`, `tool_calls`, and `refusal`) may be present and are forwarded verbatim from the upstream provider."},"ResponsesApiError":{"type":"object","properties":{"error":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string"},"code":{"type":["string","null"]}},"required":["message","type","code"]}},"required":["error"]},"ChatCompletionsRequestBody":{"type":"object","properties":{"model":{"type":"string","description":"Model name to use for generation"},"messages":{"type":"array","items":{"type":"object","properties":{"role":{"type":"string","enum":["system","developer","user","assistant","tool"]},"content":{"anyOf":[{"type":"string"},{"type":"array","items":{}},{"type":"null"}]},"name":{"type":"string"},"tool_calls":{"type":"array","items":{}},"tool_call_id":{"type":"string"}},"required":["role"],"additionalProperties":{}},"minItems":1,"description":"Array of messages comprising the conversation"},"stream":{"type":"boolean","default":false,"description":"If true, returns Server-Sent Events"},"temperature":{"type":"number"},"max_tokens":{"type":"number"},"top_p":{"type":"number"},"frequency_penalty":{"type":"number"},"presence_penalty":{"type":"number"},"stop":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}]},"tools":{"type":"array","items":{},"description":"OpenAI tools array. Each item mirrors the upstream OpenAI tools spec and is forwarded verbatim."},"tool_choice":{"anyOf":[{"type":"string"},{"type":"object","properties":{"type":{"type":"string","enum":["function"]},"function":{"type":"object","properties":{"name":{"type":"string"}},"required":["name"],"additionalProperties":{}}},"required":["type","function"],"additionalProperties":{}}]},"response_format":{"type":"object","properties":{"type":{"type":"string"}},"required":["type"],"additionalProperties":{}},"user":{"type":"string"}},"required":["model","messages"],"additionalProperties":{},"description":"Note: client-supplied 'metadata', 'litellm_metadata', and 'proxy_server_request' fields are dropped by Kindo to prevent spoofing of trusted org/user headers."},"ConversationItem":{"anyOf":[{"$ref":"#/components/schemas/MessageItem"},{"$ref":"#/components/schemas/ReasoningItem"},{"$ref":"#/components/schemas/McpCall"},{"$ref":"#/components/schemas/KindoCall"},{"$ref":"#/components/schemas/WebSearchCall"},{"$ref":"#/components/schemas/ShellCall"},{"$ref":"#/components/schemas/ShellCallOutput"},{"$ref":"#/components/schemas/FunctionCall"},{"$ref":"#/components/schemas/FunctionCallOutput"},{"$ref":"#/components/schemas/InputItem"}]},"MessageItem":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for this message item"},"type":{"type":"string","enum":["message"]},"role":{"type":"string","enum":["assistant"]},"content":{"type":"array","items":{"$ref":"#/components/schemas/OutputText"},"description":"Content parts of the message"},"status":{"type":"string","enum":["completed","in_progress","incomplete"],"description":"Processing status"}},"required":["id","type","role","content","status"]},"OutputText":{"type":"object","properties":{"type":{"type":"string","enum":["output_text"]},"text":{"type":"string","description":"The text content"},"annotations":{"type":"array","items":{"$ref":"#/components/schemas/UrlCitation"}}},"required":["type","text","annotations"]},"UrlCitation":{"type":"object","properties":{"type":{"type":"string","enum":["url_citation"]},"url":{"type":"string"},"title":{"type":"string"},"start_index":{"type":"number"},"end_index":{"type":"number"}},"required":["type","url","title","start_index","end_index"]},"ReasoningItem":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for this reasoning item"},"type":{"type":"string","enum":["reasoning"]},"summary":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["summary_text"]},"text":{"type":"string","description":"Summary text of the reasoning"}},"required":["type","text"]}}},"required":["id","type","summary"]},"McpCall":{"type":"object","properties":{"type":{"type":"string","enum":["mcp_call"]},"call_id":{"type":"string","description":"Unique call identifier"},"server_label":{"type":"string","description":"MCP server integration name"},"name":{"type":"string","description":"Tool name on the MCP server"},"arguments":{"type":"string","description":"JSON-encoded tool arguments"},"output":{"type":["string","null"],"description":"Tool output, null if still in progress"},"status":{"type":"string","enum":["completed","in_progress","failed"]}},"required":["type","call_id","server_label","name","arguments","output","status"]},"KindoCall":{"type":"object","properties":{"type":{"type":"string","enum":["kindo_call"]},"call_id":{"type":"string","description":"Unique call identifier"},"name":{"type":"string","description":"Kindo tool name"},"arguments":{"type":"string","description":"JSON-encoded tool arguments"},"output":{"type":["string","null"],"description":"Tool output, null if still in progress"},"status":{"type":"string","enum":["completed","in_progress","failed"]}},"required":["type","call_id","name","arguments","output","status"]},"WebSearchCall":{"type":"object","properties":{"type":{"type":"string","enum":["web_search_call"]},"call_id":{"type":"string","description":"Unique call identifier"},"status":{"type":"string","enum":["completed","in_progress","failed"]}},"required":["type","call_id","status"]},"ShellCall":{"type":"object","properties":{"type":{"type":"string","enum":["shell_call"]},"call_id":{"type":"string","description":"Unique call identifier"},"name":{"type":"string","description":"Shell tool name"},"action":{"type":"object","properties":{"commands":{"type":"array","items":{"type":"string"},"description":"Shell commands executed"},"timeout_ms":{"type":"number","description":"Timeout in milliseconds"}},"required":["commands"]},"status":{"type":"string","enum":["completed","in_progress","incomplete"]}},"required":["type","call_id","name","action","status"]},"ShellCallOutput":{"type":"object","properties":{"type":{"type":"string","enum":["shell_call_output"]},"call_id":{"type":"string","description":"Matching call identifier"},"name":{"type":"string","description":"Shell tool name"},"output":{"type":"array","items":{"type":"object","properties":{"stdout":{"type":"string"},"stderr":{"type":"string"},"outcome":{"type":"object","properties":{"type":{"type":"string","enum":["exit","timeout"]},"exit_code":{"type":"number"}},"required":["type"]}}},"description":"Shell execution results"}},"required":["type","call_id","name","output"]},"FunctionCall":{"type":"object","properties":{"type":{"type":"string","enum":["function_call"]},"id":{"type":"string","description":"Unique identifier for this function call item"},"call_id":{"type":"string","description":"Unique call identifier for matching output"},"name":{"type":"string","description":"Function name"},"arguments":{"type":"string","description":"JSON-encoded function arguments"},"status":{"type":"string","enum":["completed","in_progress","incomplete"]}},"required":["type","id","call_id","name","arguments","status"]},"FunctionCallOutput":{"type":"object","properties":{"type":{"type":"string","enum":["function_call_output"]},"call_id":{"type":"string","description":"Matching call identifier from function_call"},"output":{"type":"string","description":"JSON-encoded function output"}},"required":["type","call_id","output"]},"InputItem":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string","enum":["message"]},"role":{"type":"string","enum":["user","system","assistant"]},"content":{"type":"array","items":{"anyOf":[{"type":"object","properties":{"type":{"type":"string","enum":["input_text"]},"text":{"type":"string"}},"required":["type","text"]},{"$ref":"#/components/schemas/OutputText"}]}},"status":{"type":"string","enum":["completed","in_progress","incomplete"]}},"required":["id","type","role","content","status"]},"ConversationItemList":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"$ref":"#/components/schemas/ConversationItem"}},"has_more":{"type":"boolean"},"first_id":{"type":["string","null"]},"last_id":{"type":["string","null"]}},"required":["object","data","has_more","first_id","last_id"]},"ListIntegrationConnectionsResponse":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/IntegrationConnection"}}},"required":["data"]},"IntegrationConnection":{"type":"object","properties":{"id":{"type":"string"},"display_name":{"type":"string"},"integration_config_id":{"type":"string"},"nango_connection_id":{"type":"string"},"is_preferred":{"type":"boolean"},"created_at":{"type":"string","format":"date-time"}},"required":["id","display_name","integration_config_id","nango_connection_id","is_preferred","created_at"]},"SetDefaultIntegrationConnectionResponse":{"type":"object","properties":{"integration_config_id":{"type":"string"},"connection_id":{"type":"string"}},"required":["integration_config_id","connection_id"]},"SetDefaultIntegrationConnectionRequest":{"type":"object","properties":{"connection_id":{"type":"string"}},"required":["connection_id"]},"ListModelsResponse":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"$ref":"#/components/schemas/Model"}},"has_more":{"type":"boolean"},"next_after":{"type":["integer","null"]}},"required":["object","data","has_more","next_after"]},"Model":{"type":"object","properties":{"id":{"type":"string"},"object":{"type":"string","enum":["model"]},"created":{"type":"integer"},"owned_by":{"type":"string"},"display_name":{"type":"string"}},"required":["id","object","created","owned_by"]},"InputItemList":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"$ref":"#/components/schemas/InputItem"}},"has_more":{"type":"boolean"},"first_id":{"type":["string","null"]},"last_id":{"type":["string","null"]}},"required":["object","data","has_more","first_id","last_id"]},"ResponseObject":{"type":"object","properties":{"id":{"type":"string","description":"Unique response identifier"},"previous_response_id":{"type":["string","null"],"description":"The ID of the previous response in this conversation, or null for the first response"},"object":{"type":"string","enum":["response"]},"created_at":{"type":"number","description":"Unix timestamp"},"model":{"type":"string","description":"Model used for generation"},"status":{"type":"string","enum":["completed","failed","in_progress","incomplete","queued","cancelled"],"description":"Response status. \"incomplete\" indicates the model called a function tool and is waiting for the client to provide the result via function_call_output. \"cancelled\" occurs only on agent-run-backed responses (model: \"agent/<uuid>\"); \"queued\" is reserved for future background-mode support."},"incomplete_details":{"type":["object","null"],"properties":{"reason":{"type":"string","description":"Reason for incomplete status (e.g. \"tool_use\" when a function tool call is pending)"}},"required":["reason"],"description":"Present when status is \"incomplete\". The reason field indicates why the response is not yet complete."},"output":{"type":"array","items":{"$ref":"#/components/schemas/OutputItem"},"description":"Ordered list of output items"},"output_text":{"type":"string","description":"Concatenated text from all message items"},"error":{"type":["object","null"],"properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]},"instructions":{"type":["string","null"]},"conversation":{"type":["object","null"],"properties":{"id":{"type":"string"}},"required":["id"]},"metadata":{"type":["object","null"],"additionalProperties":{"type":"string"}},"tool_choice":{"$ref":"#/components/schemas/ToolChoice"},"tools":{"type":"array","items":{"oneOf":[{"$ref":"#/components/schemas/McpTool"},{"$ref":"#/components/schemas/FunctionTool"},{"$ref":"#/components/schemas/WebSearchToolEntry"},{"$ref":"#/components/schemas/ShellToolEntry"},{"$ref":"#/components/schemas/ComputerToolEntry"},{"$ref":"#/components/schemas/KindoToolEntry"}],"discriminator":{"propertyName":"type","mapping":{"mcp":"#/components/schemas/McpTool","function":"#/components/schemas/FunctionTool","web_search":"#/components/schemas/WebSearchToolEntry","shell":"#/components/schemas/ShellToolEntry","computer":"#/components/schemas/ComputerToolEntry","kindo":"#/components/schemas/KindoToolEntry"}}},"description":"All tools available to the model for this response. Use these type/name values in tool_choice.allowed_tools to filter per-turn."},"usage":{"$ref":"#/components/schemas/ResponseUsage"}},"required":["id","previous_response_id","object","created_at","model","status","incomplete_details","output","output_text","error","instructions","conversation","metadata","tool_choice","tools","usage"]},"OutputItem":{"oneOf":[{"$ref":"#/components/schemas/MessageItem"},{"$ref":"#/components/schemas/ReasoningItem"},{"$ref":"#/components/schemas/McpCall"},{"$ref":"#/components/schemas/KindoCall"},{"$ref":"#/components/schemas/WebSearchCall"},{"$ref":"#/components/schemas/ShellCall"},{"$ref":"#/components/schemas/ShellCallOutput"},{"$ref":"#/components/schemas/FunctionCall"},{"$ref":"#/components/schemas/FunctionCallOutput"}],"discriminator":{"propertyName":"type","mapping":{"message":"#/components/schemas/MessageItem","reasoning":"#/components/schemas/ReasoningItem","mcp_call":"#/components/schemas/McpCall","kindo_call":"#/components/schemas/KindoCall","web_search_call":"#/components/schemas/WebSearchCall","shell_call":"#/components/schemas/ShellCall","shell_call_output":"#/components/schemas/ShellCallOutput","function_call":"#/components/schemas/FunctionCall","function_call_output":"#/components/schemas/FunctionCallOutput"}}},"ToolChoice":{"anyOf":[{"type":"string","enum":["auto"]},{"type":"string","enum":["none"]},{"type":"object","properties":{"type":{"type":"string","enum":["allowed_tools"]},"mode":{"type":"string","enum":["auto","none"],"default":"auto","description":"'auto' lets the model choose, 'none' disables tool use"},"tools":{"type":"array","items":{"oneOf":[{"$ref":"#/components/schemas/FunctionToolRef"},{"$ref":"#/components/schemas/McpToolRef"},{"$ref":"#/components/schemas/WebSearchTool"},{"$ref":"#/components/schemas/ShellTool"},{"$ref":"#/components/schemas/ComputerTool"},{"$ref":"#/components/schemas/KindoToolRef"}],"discriminator":{"propertyName":"type","mapping":{"function":"#/components/schemas/FunctionToolRef","mcp":"#/components/schemas/McpToolRef","web_search":"#/components/schemas/WebSearchTool","shell":"#/components/schemas/ShellTool","computer":"#/components/schemas/ComputerTool","kindo":"#/components/schemas/KindoToolRef"}}},"description":"Tools the model is allowed to choose from this turn. References by type and name — no need to repeat full definitions."}},"required":["type","tools"]},{"type":"null"}]},"FunctionToolRef":{"type":"object","properties":{"type":{"type":"string","enum":["function"]},"name":{"type":"string","description":"Function tool name to allow"}},"required":["type","name"]},"McpToolRef":{"type":"object","properties":{"type":{"type":"string","enum":["mcp"]},"server_label":{"type":"string","description":"MCP server label to allow"}},"required":["type","server_label"]},"WebSearchTool":{"type":"object","properties":{"type":{"type":"string","enum":["web_search"]}},"required":["type"]},"ShellTool":{"type":"object","properties":{"type":{"type":"string","enum":["shell"]}},"required":["type"]},"ComputerTool":{"type":"object","properties":{"type":{"type":"string","enum":["computer"]}},"required":["type"]},"KindoToolRef":{"type":"object","properties":{"type":{"type":"string","enum":["kindo"]},"name":{"type":"string","description":"Kindo tool name to allow"}},"required":["type","name"]},"McpTool":{"type":"object","properties":{"type":{"type":"string","enum":["mcp"]},"server_label":{"type":"string","description":"Integration identifier for the MCP server (e.g. \"linear\", \"github\")","example":"linear"},"allowed_tools":{"type":"array","items":{"type":"string"},"description":"Restrict to specific tool names. Omit to allow all tools"}},"required":["type","server_label"]},"FunctionTool":{"type":"object","properties":{"type":{"type":"string","enum":["function"]},"name":{"type":"string","description":"Function name"},"description":{"type":"string","description":"Description of the function"},"parameters":{"type":"object","additionalProperties":{},"description":"JSON Schema for function parameters"},"strict":{"type":"boolean","default":false}},"required":["type","name","parameters"]},"WebSearchToolEntry":{"type":"object","properties":{"type":{"type":"string","enum":["web_search"]}},"required":["type"]},"ShellToolEntry":{"type":"object","properties":{"type":{"type":"string","enum":["shell"]}},"required":["type"]},"ComputerToolEntry":{"type":"object","properties":{"type":{"type":"string","enum":["computer"]}},"required":["type"]},"KindoToolEntry":{"type":"object","properties":{"type":{"type":"string","enum":["kindo"]},"name":{"type":"string","description":"Internal Kindo tool name (e.g. web_download, file_read)"}},"required":["type","name"]},"ResponseUsage":{"type":["object","null"],"properties":{"input_tokens":{"type":"number"},"output_tokens":{"type":"number"},"total_tokens":{"type":"number"},"input_tokens_details":{"type":"object","properties":{"cached_tokens":{"type":"number"}},"required":["cached_tokens"]},"output_tokens_details":{"type":"object","properties":{"reasoning_tokens":{"type":"number"}},"required":["reasoning_tokens"]}},"required":["input_tokens","output_tokens","total_tokens"]},"CreateResponseRequest":{"type":"object","properties":{"model":{"type":"string","description":"Model name to use for generation. Pass a stored agent as `agent/<uuid>` to trigger an agent run through this endpoint (see the Agent invocation section)."},"input":{"anyOf":[{"type":"string","description":"The user message to send"},{"type":"array","items":{"anyOf":[{"$ref":"#/components/schemas/InputMessageItem"},{"$ref":"#/components/schemas/FunctionCallOutput"},{"$ref":"#/components/schemas/FunctionCall"},{"$ref":"#/components/schemas/UnknownInputItem"}]},"description":"Array of input items including messages, function_call, and function_call_output"}]},"instructions":{"type":"string","description":"Additional system-level instructions for this response. Applied per-request, not persisted on the conversation."},"store":{"type":"boolean","description":"Whether to store the generated response for later retrieval. Defaults to false."},"conversation":{"type":"string","description":"Existing conversation ID to continue"},"kindo":{"type":"object","properties":{"system_prompt":{"type":"string","enum":["agent_default","off"],"description":"Opt-in for Kindo curated system prompt. \"agent_default\" prepends Kindo operational guidance to instructions. \"off\" (default) sends instructions verbatim."}},"additionalProperties":false,"description":"Kindo-specific extensions to the OpenAI Responses API spec"},"tools":{"type":"array","items":{"anyOf":[{"$ref":"#/components/schemas/McpTool"},{"$ref":"#/components/schemas/FunctionTool"},{"$ref":"#/components/schemas/ShellTool"},{"$ref":"#/components/schemas/WebSearchTool"},{"$ref":"#/components/schemas/ComputerTool"},{"$ref":"#/components/schemas/KindoToolsBundle"},{"$ref":"#/components/schemas/KindoHostedTool"},{"$ref":"#/components/schemas/UnknownTool"}]},"description":"Tools to enable. MCP tools connect to server-side integrations and are supported only on the stateful path (`store: true`, `conversation`, or `previous_response_id` set); stateless requests that include them are rejected with HTTP 400. Function tools are client-side — the model can call them, but the server returns the call details for the client to execute and send back via function_call_output. Provider-hosted tools (shell, web_search, computer) are server-executed. Kindo-hosted tools (kindo_*) are server-executed on the stateful path (`store: true`, `conversation`, or `previous_response_id` set); on the stateless path they are forwarded to upstream and will be rejected. Use kindo_tools as sugar for all current Kindo-hosted tools. Unrecognized entries with a string type are accepted and forwarded verbatim for forward-compatibility."},"stream":{"type":"boolean","default":false,"description":"If true, returns Server-Sent Events"},"tool_choice":{"anyOf":[{"type":"string","enum":["auto"]},{"type":"string","enum":["none"]},{"type":"object","properties":{"type":{"type":"string","enum":["allowed_tools"]},"mode":{"type":"string","enum":["auto","none"],"default":"auto","description":"'auto' lets the model choose, 'none' disables tool use"},"tools":{"type":"array","items":{"oneOf":[{"$ref":"#/components/schemas/FunctionToolRef"},{"$ref":"#/components/schemas/McpToolRef"},{"$ref":"#/components/schemas/WebSearchTool"},{"$ref":"#/components/schemas/ShellTool"},{"$ref":"#/components/schemas/ComputerTool"},{"$ref":"#/components/schemas/KindoToolRef"}],"discriminator":{"propertyName":"type","mapping":{"function":"#/components/schemas/FunctionToolRef","mcp":"#/components/schemas/McpToolRef","web_search":"#/components/schemas/WebSearchTool","shell":"#/components/schemas/ShellTool","computer":"#/components/schemas/ComputerTool","kindo":"#/components/schemas/KindoToolRef"}}},"description":"Tools the model is allowed to choose from this turn. References by type and name — no need to repeat full definitions."}},"required":["type","tools"]}],"default":"auto","description":"Controls which tools the model can use for this message."},"metadata":{"type":"object","additionalProperties":{"type":"string"},"description":"Arbitrary key-value pairs attached to the response"},"previous_response_id":{"type":"string","description":"The ID of a previous stored response to continue from. Kindo resolves the conversation that produced the referenced response and continues it — equivalent to passing that conversation's ID via `conversation`. Forces stateful routing. Mutually exclusive with `conversation`. Only stored responses (created with `store: true` or `conversation`) can be chained; unknown, inaccessible, or unstored response IDs return HTTP 404 with code `previous_response_not_found`."},"reasoning":{"type":["object","null"],"properties":{},"additionalProperties":{},"description":"Configuration for reasoning models (e.g. {effort, summary, generate_summary})"},"text":{"type":["object","null"],"properties":{},"additionalProperties":{},"description":"Response format configuration (e.g. {format: {type: \"json_schema\" | \"json_object\" | \"text\"}}). Replaces Chat Completions response_format"},"include":{"type":"array","items":{"type":"string"},"description":"Extra fields to include in the response (e.g. [\"reasoning.encrypted_content\"])"},"parallel_tool_calls":{"type":"boolean","description":"Whether to allow parallel tool calls"},"truncation":{"type":"string","enum":["auto","disabled"],"description":"Context truncation policy"},"background":{"type":"boolean","description":"Whether to run the model response in the background. Returns a partial response immediately and is polled. Stateless path: forwarded verbatim to upstream. Stateful path (`store: true` or `conversation` set): `background: true` is rejected with HTTP 400 (`unsupported_parameter`) — background execution is not yet supported on Kindo-managed conversations; omit it or use `stream: true` for synchronous streaming"},"service_tier":{"type":"string","enum":["auto","default","flex","priority"],"description":"SLA tier for the request (\"auto\", \"default\", \"flex\", \"priority\")"},"max_output_tokens":{"type":"integer","exclusiveMinimum":0,"description":"Maximum number of output tokens to generate"},"temperature":{"type":"number","minimum":0,"maximum":2,"description":"Sampling temperature (0–2)"},"top_p":{"type":"number","minimum":0,"maximum":1,"description":"Nucleus sampling probability mass (0–1)"},"n":{"type":"integer","exclusiveMinimum":0,"description":"Number of completions to generate"},"stop":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}],"description":"Stop sequence(s) to halt generation"}},"required":["model","input"],"additionalProperties":{},"description":"Spec-native passthrough fields (reasoning, text, include, parallel_tool_calls, truncation, service_tier, max_output_tokens, temperature, top_p, n, stop) apply to stateless requests and are currently ignored on Kindo-managed conversations (`store: true`, `conversation`, or `previous_response_id` set). Exception: `background: true` is rejected with 400 unsupported_parameter on Kindo-managed conversations. `previous_response_id` continues the conversation that produced the referenced stored response — equivalent to passing that conversation's ID via `conversation`, and mutually exclusive with it; unknown or inaccessible response IDs are rejected with 404 previous_response_not_found. `metadata` is accepted but never forwarded to upstream model providers. Agent invocations (`model: \"agent/<uuid>\"`) accept `input`, `instructions`, `stream`, and `metadata`; fields pinned by the agent's stored configuration (tools, tool_choice, sampling parameters, background, previous_response_id, conversation) are rejected with 400 unsupported_parameter naming the field.","examples":[{"model":"claude-opus-4-5","input":"What is the capital of France?"},{"model":"claude-opus-4-5","input":"What's the weather in San Francisco?","tools":[{"type":"function","name":"get_weather","description":"Get current weather for a location","parameters":{"type":"object","properties":{"location":{"type":"string"}},"required":["location"]}}]},{"model":"claude-opus-4-5","conversation":"conv_abc123","input":[{"type":"function_call_output","call_id":"toolu_xyz789","output":"{\"temperature\": 68, \"unit\": \"fahrenheit\"}"}],"tools":[{"type":"function","name":"get_weather","description":"Get current weather for a location","parameters":{"type":"object","properties":{"location":{"type":"string"}},"required":["location"]}}]}]},"InputMessageItem":{"type":"object","properties":{"type":{"type":"string","enum":["message"]},"role":{"type":"string","enum":["user","system","assistant","developer"]},"content":{"anyOf":[{"type":"string"},{"type":"array","items":{"anyOf":[{"type":"object","properties":{"type":{"type":"string","enum":["input_text"]},"text":{"type":"string"}},"required":["type","text"]},{"type":"object","properties":{"type":{"type":"string","enum":["output_text"]},"text":{"type":"string"}},"required":["type","text"]},{"type":"object","properties":{"type":{"type":"string"}},"required":["type"],"additionalProperties":{}}]}}]}},"required":["type","role","content"]},"UnknownInputItem":{"type":"object","properties":{"type":{"type":"string"}},"required":["type"],"additionalProperties":{}},"KindoToolsBundle":{"type":"object","properties":{"type":{"type":"string","enum":["kindo_tools"]}},"required":["type"]},"KindoHostedTool":{"type":"object","properties":{"type":{"type":"string","enum":["kindo_shell","kindo_web_search","kindo_browser_control","kindo_browser_screenshot","kindo_browser_list_network_requests","kindo_browser_export_request_as_curl","kindo_file_read","kindo_file_write","kindo_file_list","kindo_web_download","kindo_files_download_original","kindo_files_download_as_text","kindo_file_share_with_user","kindo_vpn_connect","kindo_vpn_disconnect","kindo_knowledge_store_search"]}},"required":["type"],"additionalProperties":{}},"UnknownTool":{"type":"object","properties":{"type":{"type":"string"}},"required":["type"],"additionalProperties":{}}},"parameters":{}},"paths":{"/agents/create":{"post":{"tags":["agents"],"summary":"Create an agent from a definition","description":"Creates a new agent, owned by the caller, from an agent definition. The definition can be written from scratch or exported from Kindo. Integration connections the caller cannot use are left unset for the caller to reconnect. All imported triggers start disabled; enable them in the agent builder.","security":[{"bearerApiKeyAuth":[]},{"xApiKeyHeaderAuth":[]}],"requestBody":{"description":"The agent definition to create the agent from, such as a file downloaded from Kindo.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentCreateRequestBody"}}}},"responses":{"201":{"description":"Agent successfully created with id 'agentId'. When a requested model was unavailable and fell back, 'warnings' lists each one.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentCreateResponse"}}}},"400":{"description":"Bad request (invalid definition, inaccessible required resource, or a tool integration not set up on this deployment)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Authentication failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"API access is disabled for the API key owner, or the owner belongs to groups that all disallow agent creation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/agents/{agentId}":{"get":{"tags":["agents"],"summary":"Get agent details","description":"Gets details for the specified agent, including recent run ids. Optional query parameters paginate recentRunIds and filter them by createdAt. Calling with no query parameters returns the legacy response: up to 5 recent run ids and no nextCursor. Supplying any query parameter switches to the paginated response, where limit defaults to 20.","security":[{"bearerApiKeyAuth":[]},{"xApiKeyHeaderAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"agentId","in":"path"},{"schema":{"type":"string","maxLength":4096,"description":"Opaque pagination cursor returned from the previous response. Pass it back unchanged to fetch the next page. Clients must not parse, modify, or construct cursors — the encoding is internal and may change. The cursor does NOT encode the startDate/endDate filters; callers MUST re-pass the same startDate/endDate (if any) used to obtain it on each subsequent page request. Passing the cursor with different (or omitted) date filters will produce a different result set, since the cursor predicate is AND-ed with the date filters server-side rather than replacing them."},"required":false,"description":"Opaque pagination cursor returned from the previous response. Pass it back unchanged to fetch the next page. Clients must not parse, modify, or construct cursors — the encoding is internal and may change. The cursor does NOT encode the startDate/endDate filters; callers MUST re-pass the same startDate/endDate (if any) used to obtain it on each subsequent page request. Passing the cursor with different (or omitted) date filters will produce a different result set, since the cursor predicate is AND-ed with the date filters server-side rather than replacing them.","name":"cursor","in":"query"},{"schema":{"type":"string","format":"date-time","description":"Inclusive ISO-8601 upper bound for filtering agent runs by createdAt."},"required":false,"description":"Inclusive ISO-8601 upper bound for filtering agent runs by createdAt.","name":"endDate","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":20,"description":"Maximum number of run ids to return. Must be between 1 and 100 (inclusive). Defaults to 20.","example":20},"required":false,"description":"Maximum number of run ids to return. Must be between 1 and 100 (inclusive). Defaults to 20.","name":"limit","in":"query"},{"schema":{"type":"string","format":"date-time","description":"Inclusive ISO-8601 lower bound for filtering agent runs by createdAt."},"required":false,"description":"Inclusive ISO-8601 lower bound for filtering agent runs by createdAt.","name":"startDate","in":"query"}],"responses":{"200":{"description":"Agent details successfully retrieved","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentFetchResponse"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Authentication failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Agent cannot be found or accessed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/runs/{runId}/evals":{"get":{"tags":["runs"],"summary":"Get evaluation results for a workflow run","description":"Returns the aggregate evaluation result and per-step verdicts for the specified run.","security":[{"bearerApiKeyAuth":[]},{"xApiKeyHeaderAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"runId","in":"path"}],"responses":{"200":{"description":"Run evaluation results successfully retrieved","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentRunEvalsResponse"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Authentication failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Run does not exist, or the caller lacks access. The API intentionally does not distinguish these cases.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/runs/{runId}":{"get":{"tags":["runs"],"summary":"Get agent run result details","description":"Gets agent run result details for the specified run","security":[{"bearerApiKeyAuth":[]},{"xApiKeyHeaderAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"runId","in":"path"}],"responses":{"200":{"description":"Agent run result details successfully retrieved","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentRunResultResponse"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Authentication failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Run cannot be found or accessed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/agents/list":{"get":{"tags":["agents"],"summary":"List all accessible agents","description":"Lists all agents accessible to the authenticated user","security":[{"bearerApiKeyAuth":[]},{"xApiKeyHeaderAuth":[]}],"responses":{"200":{"description":"List of accessible agents successfully retrieved","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentListResponse"}}}},"401":{"description":"Authentication failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/runs/{runId}/restart":{"post":{"tags":["runs"],"summary":"Restart an agent run","description":"Starts a new run that re-uses the original inputs from the source run and returns a new runId. The source run is unchanged; the new run uses the latest agent version.","security":[{"bearerApiKeyAuth":[]},{"xApiKeyHeaderAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"runId","in":"path"}],"responses":{"202":{"description":"Agent run successfully restarted with a new id 'runId'","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentRunCreationResponse"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Authentication failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Run does not exist, or the caller lacks access. The API intentionally does not distinguish these cases.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/agents/runs":{"post":{"tags":["agents"],"summary":"Create run for the specified agent","description":"Creates a run from an agent","security":[{"bearerApiKeyAuth":[]},{"xApiKeyHeaderAuth":[]}],"requestBody":{"description":"Parameters for agent run execution. Input name-value pairs must exactly match the input label as displayed in the UI.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentRunCreationRequestBody"}}}},"responses":{"202":{"description":"Agent run successfully created with id 'runId'","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentRunCreationResponse"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Authentication failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Agent cannot be found or accessed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Agent cannot be run (missing required inputs)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/chat/completions":{"post":{"operationId":"createChatCompletion","tags":["Chat Completions"],"summary":"Create a chat completion","description":"Proxies OpenAI-compatible chat completion requests to LiteLLM. Supports streaming (SSE) and non-streaming responses.","security":[{"bearerApiKeyAuth":[]},{"xApiKeyHeaderAuth":[]}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChatCompletionsRequestBody"}}}},"responses":{"200":{"description":"Chat completion response. When stream is false, returns the full completion object. When stream is true, returns an SSE stream.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChatCompletionsResponse"}},"text/event-stream":{"schema":{"type":"string","description":"SSE stream of chat completion chunks; each event is `data: {chunk-json}\\n\\n`. Final event is `data: [DONE]\\n\\n`."}}}},"400":{"description":"Validation error — missing or invalid fields in the request body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResponsesApiError"}}}},"401":{"description":"Authentication failed — missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResponsesApiError"}}}},"403":{"description":"Permission denied — the requested model is not available for your organization or user group.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResponsesApiError"}}}},"429":{"description":"Rate limited — upstream rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResponsesApiError"}}}},"500":{"description":"Internal server error during chat completion","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResponsesApiError"}}}},"502":{"description":"Bad gateway — upstream LiteLLM/provider error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResponsesApiError"}}}}}}},"/conversations/{conversation_id}/items/{item_id}":{"get":{"operationId":"getConversationItem","tags":["Chat Actions"],"summary":"Get a single item from a Chat Actions conversation","description":"Retrieve a single item from a conversation by its ID.","security":[{"bearerApiKeyAuth":[]},{"xApiKeyHeaderAuth":[]}],"parameters":[{"schema":{"type":"string","description":"The conversation ID (conv_-prefixed or bare)"},"required":true,"description":"The conversation ID (conv_-prefixed or bare)","name":"conversation_id","in":"path"},{"schema":{"type":"string","description":"The item ID (msg_ for messages or tool call ID)"},"required":true,"description":"The item ID (msg_ for messages or tool call ID)","name":"item_id","in":"path"}],"responses":{"200":{"description":"The conversation item","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConversationItem"}}}},"401":{"description":"Authentication failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResponsesApiError"}}}},"403":{"description":"Permission denied","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResponsesApiError"}}}},"404":{"description":"Item or conversation not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResponsesApiError"}}}}}}},"/conversations/{conversation_id}/items":{"get":{"operationId":"listConversationItems","tags":["Chat Actions"],"summary":"List items in a Chat Actions conversation","description":"List all items in a conversation — messages, tool calls, reasoning — in chronological order.","security":[{"bearerApiKeyAuth":[]},{"xApiKeyHeaderAuth":[]}],"parameters":[{"schema":{"type":"string","description":"The conversation ID (conv_-prefixed or bare)"},"required":true,"description":"The conversation ID (conv_-prefixed or bare)","name":"conversation_id","in":"path"},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":20,"description":"Messages per page (1-100). Each message may expand to multiple items."},"required":false,"description":"Messages per page (1-100). Each message may expand to multiple items.","name":"limit","in":"query"},{"schema":{"type":"string","enum":["asc","desc"],"default":"desc","description":"Sort order by message index"},"required":false,"description":"Sort order by message index","name":"order","in":"query"},{"schema":{"type":"string","description":"Cursor: return items after this item ID"},"required":false,"description":"Cursor: return items after this item ID","name":"after","in":"query"}],"responses":{"200":{"description":"Paginated list of conversation items","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConversationItemList"}}}},"401":{"description":"Authentication failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResponsesApiError"}}}},"403":{"description":"Permission denied","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResponsesApiError"}}}},"404":{"description":"Conversation not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResponsesApiError"}}}}}}},"/integrations/connections":{"get":{"tags":["integrations"],"summary":"List integration connections","description":"Returns all integration connections accessible to the API-key holder, including shared group connections. `is_preferred` marks every member of the user's default connection set for that integration — zero or more entries per integration may be true.","security":[{"bearerApiKeyAuth":[]},{"xApiKeyHeaderAuth":[]}],"responses":{"200":{"description":"List of integration connections","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ListIntegrationConnectionsResponse"}}}},"401":{"description":"Authentication failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/integrations/connections/{integration_id}/default":{"post":{"tags":["integrations"],"summary":"Set default integration connection","description":"Sets the preferred (default) connection for a given integration. Requires `connection_id` in the request body. Single-valued: replaces the user's whole default connection set for the integration with the supplied connection.","security":[{"bearerApiKeyAuth":[]},{"xApiKeyHeaderAuth":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"integration_id","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SetDefaultIntegrationConnectionRequest"}}}},"responses":{"200":{"description":"Default connection set successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SetDefaultIntegrationConnectionResponse"}}}},"400":{"description":"Bad request — connection_id is missing, or it does not belong to the specified integration","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Authentication failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden — not authorized to use this connection","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Integration connection not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/models":{"get":{"tags":["models"],"summary":"List available models","description":"Returns a list of all models available to the authenticated user based on their organization settings, user group access controls, and payment tier.\n\nEach proxied-model entry carries the four OpenAI-compatible fields (`id`, `object`, `created`, `owned_by`) plus an additive Kindo `display_name` (the human-readable model name). This extra field is optional and OpenAI SDK clients ignore unknown fields, so the endpoint stays OpenAI-compatible. The `id` is still the LiteLLM model name verbatim (pass it back as the `model` parameter). Agent entries (`include_agents=true`) omit `display_name`.\n\nSet `include_agents=true` to also list the caller’s accessible Kindo agents as model entries (`id: \"agent/<uuid>\"`, `owned_by: <org name>`). Agent entries can be passed directly as the `model` parameter of `POST /v1/responses` to invoke the agent. Trigger-bearing agents (event, direct webhook, or cron) are directly invocable and are included. By default agents are not included.\n\nThe agents portion is paginated via the additive `limit`/`after` query params and a `has_more`/`next_after` response field. Proxied models are always returned in full on the first page; only agents page. Omitting the params yields the prior flat response (with `has_more: false`).","security":[{"bearerApiKeyAuth":[]},{"xApiKeyHeaderAuth":[]}],"parameters":[{"schema":{"type":"string","enum":["true","false"],"description":"When \"true\", append the caller’s accessible agents as `agent/<uuid>` model entries. Defaults to \"false\"."},"required":false,"description":"When \"true\", append the caller’s accessible agents as `agent/<uuid>` model entries. Defaults to \"false\".","name":"include_agents","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":1000,"description":"Max agent entries to return (1-1000, default 500). Ignored unless `include_agents=true`. Proxied models are not affected. Out-of-range values are clamped, not rejected: values below 1 (or non-numeric) fall back to the default 500, and values above 1000 are capped at 1000."},"required":false,"description":"Max agent entries to return (1-1000, default 500). Ignored unless `include_agents=true`. Proxied models are not affected. Out-of-range values are clamped, not rejected: values below 1 (or non-numeric) fall back to the default 500, and values above 1000 are capped at 1000.","name":"limit","in":"query"},{"schema":{"type":["integer","null"],"minimum":0,"description":"Offset into the agents list for the next page (default 0). Pass the `next_after` value from the previous response. Ignored unless `include_agents=true`. Out-of-range values are clamped, not rejected: negative or non-numeric values fall back to 0."},"required":false,"description":"Offset into the agents list for the next page (default 0). Pass the `next_after` value from the previous response. Ignored unless `include_agents=true`. Out-of-range values are clamped, not rejected: negative or non-numeric values fall back to 0.","name":"after","in":"query"}],"responses":{"200":{"description":"List of available models","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ListModelsResponse"}}}},"401":{"description":"Authentication failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/responses/{response_id}/input_items":{"get":{"operationId":"listInputItems","tags":["Chat Actions"],"summary":"List input items for a Chat Actions response","description":"Returns the input items that were sent to generate this response.","security":[{"bearerApiKeyAuth":[]},{"xApiKeyHeaderAuth":[]}],"parameters":[{"schema":{"type":"string","description":"The response ID (format: resp_<conversationId>_<index>)"},"required":true,"description":"The response ID (format: resp_<conversationId>_<index>)","name":"response_id","in":"path"}],"responses":{"200":{"description":"Paginated list of input items","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InputItemList"}}}},"400":{"description":"Invalid response ID format","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResponsesApiError"}}}},"401":{"description":"Authentication failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResponsesApiError"}}}},"403":{"description":"Permission denied","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResponsesApiError"}}}},"404":{"description":"Response not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResponsesApiError"}}}}}}},"/responses/{response_id}":{"get":{"operationId":"getResponse","tags":["Chat Actions"],"summary":"Get Chat Actions response details","description":"Retrieve a previously created response by its ID.\n\n### Resume a streamed response (`?stream=true`)\nIf the SSE connection from a `stream: true` create call drops, reconnect with `GET /v1/responses/{response_id}?stream=true&starting_after=<sequence_number>` to replay every event *after* that `sequence_number` and then continue live (or terminate with `response.completed` if the response already finished) — without starting a new response. Every streamed event carries its `sequence_number` both in the event body and as the SSE `id:` line, so browser `EventSource` clients can reconnect automatically via `Last-Event-ID` when `starting_after` is omitted. Omitting the cursor entirely replays the response from the beginning. A negative or non-integer `starting_after` is rejected with HTTP 400.\n\nThe resume window is **time-bounded** (the same window over which a response is retained for polling). After it elapses the streamed replay falls back to the response's final items followed by `response.completed`; the per-token deltas of the original stream are no longer available — retrieve the final object with a plain `GET` (no `stream`) instead.","security":[{"bearerApiKeyAuth":[]},{"xApiKeyHeaderAuth":[]}],"parameters":[{"schema":{"type":"string","description":"The response ID (format: resp_<conversationId>_<index>, or resp_run_<runId> for agent-run-backed responses)"},"required":true,"description":"The response ID (format: resp_<conversationId>_<index>, or resp_run_<runId> for agent-run-backed responses)","name":"response_id","in":"path"},{"schema":{"type":"string","enum":["true","false"],"description":"Set to `true` to resume the response as Server-Sent Events instead of returning the final JSON object."},"required":false,"description":"Set to `true` to resume the response as Server-Sent Events instead of returning the final JSON object.","name":"stream","in":"query"},{"schema":{"type":["integer","null"],"minimum":0,"description":"Resume cursor: replay only events whose `sequence_number` is greater than this value. Requires `stream=true`. Omit to replay from the beginning. Agent-run responses (`resp_run_*` ids) support replay-only resume: `starting_after` must be 0 or omitted for those ids, and a positive cursor is rejected with HTTP 400."},"required":false,"description":"Resume cursor: replay only events whose `sequence_number` is greater than this value. Requires `stream=true`. Omit to replay from the beginning. Agent-run responses (`resp_run_*` ids) support replay-only resume: `starting_after` must be 0 or omitted for those ids, and a positive cursor is rejected with HTTP 400.","name":"starting_after","in":"query"}],"responses":{"200":{"description":"The response object. When `stream=true`, an SSE stream (`text/event-stream`) replaying the response from the resume cursor and ending with `response.completed`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResponseObject"}}}},"400":{"description":"Invalid response ID format, or invalid `starting_after` (negative / non-integer)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResponsesApiError"}}}},"401":{"description":"Authentication failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResponsesApiError"}}}},"403":{"description":"Permission denied","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResponsesApiError"}}}},"404":{"description":"Response not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResponsesApiError"}}}}}}},"/responses":{"post":{"operationId":"createResponse","tags":["Chat Actions"],"summary":"Create a Chat Actions response","description":"Send a message and get a response. By default the request is forwarded statelessly to upstream — no conversation is created. Opt in to a Kindo-managed conversation by setting `store: true`, passing an existing `conversation` ID, or chaining from a stored response via `previous_response_id`.\n\n**Routing:** The request is routed based on spec-native fields. If `store: true`, `conversation`, or `previous_response_id` is set, the request is stateful (Kindo-managed conversation via Hatchet). Otherwise it is stateless (direct proxy to LiteLLM `/v1/responses`).\n\n**Multi-turn chaining:** Pass the `id` of a previous stored response as `previous_response_id` to continue the conversation that produced it — equivalent to passing that conversation's ID via `conversation` (the two parameters are mutually exclusive). Only stored responses (created with `store: true` or `conversation`) can be chained; referencing an unknown, inaccessible, or unstored response returns HTTP 404 with code `previous_response_not_found`. Kindo conversations are linear: chaining from an older response continues the full conversation history — it does not fork at that response.\n\n**Spec passthrough fields:** `reasoning`, `text`, `include`, `parallel_tool_calls`, `truncation`, `service_tier`, `max_output_tokens`, `temperature`, `top_p`, `n`, `stop`, and `background` are forwarded verbatim to upstream on the stateless path. On the stateful path they are currently stripped before the worker, except `background: true`, which is rejected with HTTP 400 (`unsupported_parameter`) — background execution is not yet supported on Kindo-managed conversations.\n\n### Agent invocation (`model: \"agent/<uuid>\"`)\nPass a stored Kindo agent as the model to trigger an agent run through this endpoint. Agent invocations always run on the stateful path (Kindo-hosted tools only execute there) and behave asynchronously: the response (`id: \"resp_run_<runId>\"`, `status: \"in_progress\"`, run linkage in `metadata.kindo_run_id`/`metadata.kindo_agent_id`) returns immediately and is polled via `GET /v1/responses/{response_id}`. `stream: true` streams run lifecycle events at message granularity. Request `instructions` compose with the agent (appended after its system prompt); `input` binds to the single declared agent input, or seeds the run conversation as the opening user message when the agent declares none. Fields pinned by the agent config (`tools`, non-`auto` `tool_choice`, sampling parameters, `background`, `previous_response_id`, ...) are rejected with `invalid_request_error` naming the field. Agent-run responses are not yet chainable via `previous_response_id` (conversation continuity for agent runs is planned). Version pinning (`agent/<uuid>@<version>`) is not available yet (HTTP 400). Unknown or inaccessible agents return `model_not_found`, indistinguishable from an unknown model. Accessible agents are discoverable via `GET /v1/models?include_agents=true`.\n\nThe model can use built-in tools (shell, web search, file operations), MCP integrations, Kindo-hosted tools, and client-side **function tools**. MCP tools (`type: \"mcp\"`) are label-only references resolved server-side, so they require the stateful path — stateless requests that include them are rejected with HTTP 400.\n\n### System prompt\nBy default `instructions` passes through verbatim with no Kindo injection. Set `kindo.system_prompt: \"agent_default\"` to prepend Kindo curated operational guidance.\n\n### Tool sugar\nInclude `{type: \"kindo_tools\"}` in the `tools` array to expand to all current Kindo-hosted tools at request time. This is purely sugar — it does not change routing. Note: Kindo-hosted tools execute server-side **only on the stateful path**; on the stateless path they are forwarded to upstream which will reject them.\n\n### Function tools round-trip\n1. Include `{\"type\":\"function\", ...}` definitions in `tools`\n2. If the model calls a function tool, the response has `status: \"incomplete\"` with `incomplete_details.reason: \"tool_use\"` and a `function_call` output item\n3. Send a continuation request with the same `conversation` ID and `input: [{\"type\":\"function_call_output\", \"call_id\":\"...\", \"output\":\"...\"}]`\n4. The model uses the function result and returns a completed response\n\nSet `stream: true` for Server-Sent Events or `stream: false` (default) to block until complete.","security":[{"bearerApiKeyAuth":[]},{"xApiKeyHeaderAuth":[]}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateResponseRequest"}}}},"responses":{"200":{"description":"The completed response object. When stream is false, contains the full response. When stream is true, the final response is sent as a response.completed SSE event","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResponseObject"}}}},"400":{"description":"Validation error — missing or invalid fields in the request body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResponsesApiError"}}}},"401":{"description":"Authentication failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResponsesApiError"}}}},"403":{"description":"Permission denied — user lacks access to the specified conversation or model","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResponsesApiError"}}}},"404":{"description":"Conversation not found, or the response referenced by `previous_response_id` is unknown, inaccessible, or was not stored (`previous_response_not_found`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResponsesApiError"}}}},"500":{"description":"Response generation or internal server error","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/ResponsesApiError"},{"$ref":"#/components/schemas/ErrorResponse"}]}}}}}}}},"webhooks":{}}