{"openapi":"3.1.0","info":{"title":"Keiki Agent API","version":"1.0.0","description":"Call Keiki agents through provider-compatible HTTP APIs. Each model is an enabled Keiki agent with its own instructions, memory, tools, and channels.","contact":{"name":"Keiki","email":"nizzy@orchid.ai","url":"https://onkeiki.com/contact"},"license":{"name":"Proprietary"}},"servers":[{"url":"https://onkeiki.com","description":"Keiki production API"}],"externalDocs":{"description":"Keiki developer portal","url":"https://onkeiki.com/developers"},"tags":[{"name":"OpenAI compatibility","description":"Use an enabled Keiki agent as an OpenAI model."},{"name":"Anthropic compatibility","description":"Use an enabled Keiki agent through the Anthropic Messages API shape."}],"paths":{"/api/v1/openai/models":{"get":{"operationId":"listKeikiAgentModels","summary":"List enabled Keiki agents","description":"Returns the agents that the authenticated API key can call and whose API gateway is enabled. Use an agent name or ID as the model in a completion request.","tags":["OpenAI compatibility"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Enabled agents visible to this API key.","content":{"application/json":{"schema":{"type":"object","required":["object","data"],"properties":{"object":{"type":"string","const":"list"},"data":{"type":"array","items":{"$ref":"#/components/schemas/AgentModel"}}}}}}},"401":{"description":"The API key is missing or invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"The key does not have the agents:chat scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v1/openai/chat/completions":{"post":{"operationId":"createKeikiChatCompletion","summary":"Run a Keiki agent turn","description":"Starts or continues a persisted conversation with the named Keiki agent. The agent uses its configured model, instructions, memory, and server-side tools. Client-declared tools are returned for the caller to execute.","tags":["OpenAI compatibility"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"x-conversation-id","in":"header","required":false,"description":"Stable conversation identifier. Omit it to create a new conversation.","schema":{"type":"string","minLength":1,"maxLength":64,"pattern":"^[A-Za-z0-9_-]+$"}}],"requestBody":{"required":true,"description":"The agent model and provider-compatible conversation transcript.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChatCompletionRequest"}}}},"responses":{"200":{"description":"The completed turn, or a server-sent event stream when stream is true.","headers":{"x-conversation-id":{"description":"Conversation identifier to send on the next turn.","schema":{"type":"string","minLength":1,"maxLength":64,"pattern":"^[A-Za-z0-9_-]+$"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChatCompletionResponse"}},"text/event-stream":{"schema":{"type":"string","description":"OpenAI-compatible data events terminated by data: [DONE]."}}}},"400":{"description":"The JSON body, messages, tools, or model value is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"The API key is missing or invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"The key lacks agents:chat or the requested agent gateway is disabled.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"No enabled agent matches the requested model.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"The named conversation already has a turn in progress.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"The agent turn failed before producing a response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/anthropic/v1/messages":{"post":{"operationId":"createKeikiAnthropicMessage","summary":"Run a Keiki agent through the Anthropic Messages API","description":"Starts or continues the same Keiki agent turn exposed by chat completions, translated into Anthropic request, response, and streaming event shapes.","tags":["Anthropic compatibility"],"security":[{"apiKeyAuth":[]}],"parameters":[{"name":"anthropic-version","in":"header","required":false,"description":"Anthropic protocol version expected by the client.","schema":{"type":"string","example":"2023-06-01"}},{"name":"x-conversation-id","in":"header","required":false,"description":"Stable conversation identifier. Omit it to create a new conversation.","schema":{"type":"string","minLength":1,"maxLength":64,"pattern":"^[A-Za-z0-9_-]+$"}}],"requestBody":{"required":true,"description":"The agent model and Anthropic-compatible conversation transcript.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AnthropicMessageRequest"}}}},"responses":{"200":{"description":"The completed message or an Anthropic-compatible event stream.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AnthropicMessageResponse"}},"text/event-stream":{"schema":{"type":"string","description":"Anthropic-compatible server-sent message events."}}}},"400":{"description":"The message request is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AnthropicErrorResponse"}}}},"401":{"description":"The API key is missing or invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AnthropicErrorResponse"}}}},"403":{"description":"The key lacks agents:chat or the requested agent gateway is disabled.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AnthropicErrorResponse"}}}},"404":{"description":"No enabled agent matches the requested model.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AnthropicErrorResponse"}}}},"409":{"description":"The named conversation already has a turn in progress.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AnthropicErrorResponse"}}}},"500":{"description":"The agent turn failed before producing a response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AnthropicErrorResponse"}}}}}}},"/api/anthropic/v1/messages/count_tokens":{"post":{"operationId":"countKeikiAnthropicMessageTokens","summary":"Count input tokens","description":"Estimates the number of tokens in an Anthropic-compatible system prompt and message transcript before starting an agent turn.","tags":["Anthropic compatibility"],"security":[{"apiKeyAuth":[]}],"requestBody":{"required":true,"description":"The same model and message fields accepted by the Messages API.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AnthropicTokenCountRequest"}}}},"responses":{"200":{"description":"Estimated token count for the request input.","content":{"application/json":{"schema":{"type":"object","required":["input_tokens"],"properties":{"input_tokens":{"type":"integer","minimum":0}}}}}},"400":{"description":"The message request is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AnthropicErrorResponse"}}}},"401":{"description":"The API key is missing or invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AnthropicErrorResponse"}}}}}}},"/api/v1/developer/deployments":{"post":{"operationId":"createDeployment","summary":"Create or update a partner deployment","description":"Creates or updates an agent by the partner-supplied external_ref and connects channels.","tags":["Partner deployments"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["external_ref","agent"],"properties":{"external_ref":{"type":"string","minLength":1,"maxLength":200},"agent":{"type":"object","additionalProperties":true,"description":"Either { template, name? } or an inline spec.","properties":{"template":{"type":"string"},"name":{"type":"string"},"model":{"type":"string"},"system_prompt":{"type":"string"},"max_steps":{"type":"integer","minimum":1,"maximum":50},"history_limit":{"type":"integer","minimum":1,"maximum":200},"turn_deadline_ms":{"type":["integer","null"],"minimum":30000,"maximum":900000,"description":"Wall-clock budget of one turn in ms. Omitted: platform default (300000); null clears it."},"features":{"type":"object","additionalProperties":{"type":"boolean"}},"harness":{"type":"string","enum":["flue","hermes"]}}},"channels":{"type":"array","description":"Messaging channels to connect, plus `{ type: \"api\", passthrough? }` to turn on the API gateway.","items":{"type":"object","additionalProperties":true}},"webhook_url":{"type":["string","null"]},"mcp_connections":{"type":"array","maxItems":10,"description":"The agent's whole list of MCP / OpenAPI connections, keyed by `name`: connections not listed are removed, an unchanged entry is kept as is. Omit the field to leave connections alone. `headers` are agent-wide; per-sender headers go through PUT /mcp-senders. Requires the `sandbox` and `mcp` features.","items":{"type":"object","required":["name","endpoint"],"properties":{"name":{"type":"string"},"endpoint":{"type":"string","format":"uri"},"kind":{"type":"string","enum":["mcp","openapi"],"default":"mcp"},"auth_mode":{"type":"string","enum":["public","headers","oauth","user"],"default":"public","description":"`user`: MCP only; each conversation user authorizes their own account on first chat."},"headers":{"type":"object","additionalProperties":{"type":"string"},"description":"Agent-wide headers for `auth_mode: headers`; required when the connection is new, omit to keep the stored ones."},"icon_url":{"type":"string"},"default_permission":{"type":"string","enum":["allow","ask","deny"],"default":"allow"}}}}}}}}},"responses":{"200":{"description":"Deployment updated."},"201":{"description":"Deployment created."},"400":{"description":"Malformed request, or `mcp_connections` given while the agent lacks the sandbox/mcp features."},"402":{"description":"An active plan is required to connect channels."},"403":{"description":"The key lacks deployment write access."},"502":{"description":"An MCP connection could not be reached."}}}},"/api/v1/developer/deployments/{external_ref}":{"parameters":[{"name":"external_ref","in":"path","required":true,"schema":{"type":"string"}}],"get":{"operationId":"getDeployment","summary":"Get a partner deployment","description":"Read one partner deployment and its configured channels using the external reference.","tags":["Partner deployments"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Deployment details."},"404":{"description":"Deployment not found."}}},"delete":{"operationId":"deleteDeployment","summary":"Delete a partner deployment","description":"Delete one partner deployment and stop serving its configured channels.","tags":["Partner deployments"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Deployment deleted."},"404":{"description":"Deployment not found."}}}},"/api/v1/developer/deployments/{external_ref}/mcp-senders":{"parameters":[{"name":"external_ref","in":"path","required":true,"schema":{"type":"string"}}],"get":{"operationId":"listDeploymentMcpSenders","summary":"List per-sender MCP credentials","description":"Header names and timestamps only; values are never returned.","tags":["Partner deployments"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Sender entries of the deployment.","content":{"application/json":{"schema":{"type":"object","properties":{"credentials":{"type":"array","items":{"type":"object","required":["source","channel","header_names","updated_at"],"properties":{"source":{"type":"string"},"channel":{"type":"string","enum":["slack","api"]},"team_id":{"type":"string","description":"With `channel: \"slack\"`."},"user_id":{"type":"string","description":"With `channel: \"slack\"`."},"conversation_id":{"type":"string","description":"With `channel: \"api\"`."},"header_names":{"type":"array","items":{"type":"string"}},"updated_at":{"type":"string","format":"date-time"}}}}}}}}},"404":{"description":"Deployment not found."}}},"put":{"operationId":"setDeploymentMcpSender","summary":"Set or replace one sender's headers for one MCP connection","description":"The headers the agent calls the named MCP connection with on behalf of one sender: a Slack user (`channel: \"slack\"` with `team_id` and `user_id`) or an API-gateway conversation (`channel: \"api\"` with the client's `conversation_id`). Stored encrypted and never shown to the model.","tags":["Partner deployments"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["source","channel","headers"],"properties":{"source":{"type":"string","description":"Name of the MCP connection on the deployment."},"channel":{"type":"string","enum":["slack","api"]},"team_id":{"type":"string","description":"Slack team id. Required with `channel: \"slack\"`."},"user_id":{"type":"string","description":"Slack user id. Required with `channel: \"slack\"`."},"conversation_id":{"type":"string","description":"The client's conversation id on the API gateway: the `x-conversation-id` it sends (or was returned). Required with `channel: \"api\"`."},"headers":{"type":"object","additionalProperties":{"type":"string"},"minProperties":1},"connection":{"type":"object","description":"Creates the MCP connection named `source` when the deployment has none: connected public, with no agent-wide credential. Ignored when the connection exists.","required":["endpoint"],"properties":{"endpoint":{"type":"string","format":"uri","description":"MCP endpoint, or the OpenAPI spec URL."},"kind":{"type":"string","enum":["mcp","openapi"],"default":"mcp"},"icon_url":{"type":"string","format":"uri"}}}}}}}},"responses":{"200":{"description":"Credential stored; takes effect on the sender's next turn.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"created":{"type":"boolean","description":"Whether `connection` created the MCP connection."}}}}}},"400":{"description":"Malformed sender, headers or connection."},"403":{"description":"An org-wide key with deployments:write is required."},"404":{"description":"Deployment or MCP connection not found (and no `connection` given)."},"409":{"description":"Another MCP connection on this deployment already uses the given endpoint."},"502":{"description":"The connection given could not be reached; it is not kept and nothing is stored."}}},"delete":{"operationId":"deleteDeploymentMcpSender","summary":"Revoke one sender's headers for one MCP connection","description":"Revoke the stored MCP headers for one sender on one deployment connection: `team_id` and `user_id` with `channel=slack`, `conversation_id` with `channel=api`.","tags":["Partner deployments"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"source","in":"query","required":true,"schema":{"type":"string"}},{"name":"channel","in":"query","required":true,"schema":{"type":"string","enum":["slack","api"]}},{"name":"team_id","in":"query","required":false,"schema":{"type":"string"}},{"name":"user_id","in":"query","required":false,"schema":{"type":"string"}},{"name":"conversation_id","in":"query","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"Credential revoked (or none existed)."},"404":{"description":"Deployment or MCP connection not found."}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"A scoped Keiki developer API key."},"apiKeyAuth":{"type":"apiKey","in":"header","name":"x-api-key","description":"A scoped Keiki developer API key."}},"schemas":{"ErrorResponse":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","resolution"],"properties":{"code":{"type":"string","description":"Stable machine-readable error code.","example":"unauthorized"},"message":{"type":"string","description":"Human-readable explanation of the failure."},"resolution":{"type":"string","description":"Concrete guidance for correcting or retrying the request."}}}}},"AnthropicErrorResponse":{"type":"object","required":["type","error"],"properties":{"type":{"type":"string","const":"error"},"error":{"type":"object","required":["type","code","message","resolution"],"properties":{"type":{"type":"string","description":"Anthropic-compatible error category."},"code":{"type":"string","description":"Stable Keiki machine-readable error code."},"message":{"type":"string"},"resolution":{"type":"string","description":"Concrete guidance for correcting or retrying the request."}}}}},"AgentModel":{"type":"object","required":["id","object","created","owned_by","name"],"properties":{"id":{"type":"string","description":"Stable Keiki agent identifier."},"object":{"type":"string","const":"model"},"created":{"type":"integer","description":"Agent creation time as Unix seconds."},"owned_by":{"type":"string","description":"Organization identifier."},"name":{"type":"string","description":"Human-readable agent name accepted as model."}}},"ChatCompletionRequestMessage":{"oneOf":[{"type":"object","required":["role","content"],"properties":{"role":{"type":"string","enum":["system","developer","user"]},"content":{"oneOf":[{"type":"string"},{"type":"array","items":{"type":"object","required":["type"],"properties":{"type":{"type":"string"},"text":{"type":"string"}}}}]}}},{"type":"object","required":["role","content"],"properties":{"role":{"type":"string","const":"assistant"},"content":{"oneOf":[{"type":"string"},{"type":"array","items":{"type":"object","required":["type"],"properties":{"type":{"type":"string"},"text":{"type":"string"}}}},{"type":"null"}]}}},{"type":"object","required":["role","content","tool_call_id"],"properties":{"role":{"type":"string","const":"tool"},"content":{"oneOf":[{"type":"string"},{"type":"array","items":{"type":"object","required":["type"],"properties":{"type":{"type":"string"},"text":{"type":"string"}}}}]},"tool_call_id":{"type":"string","description":"Tool call answered by this message."}}}]},"ChatCompletionResponseMessage":{"type":"object","required":["role","content"],"properties":{"role":{"type":"string","const":"assistant"},"content":{"oneOf":[{"type":"string"},{"type":"null"}]},"tool_calls":{"type":"array","items":{"$ref":"#/components/schemas/OpenAiToolCall"}}}},"OpenAiToolCall":{"type":"object","required":["index","id","type","function"],"properties":{"index":{"type":"integer","minimum":0},"id":{"type":"string"},"type":{"type":"string","const":"function"},"function":{"type":"object","required":["name","arguments"],"properties":{"name":{"type":"string"},"arguments":{"type":"string","description":"JSON-encoded function arguments."}}}}},"AnthropicMessage":{"type":"object","required":["role","content"],"properties":{"role":{"type":"string","enum":["system","developer","user","assistant","tool"]},"content":{"oneOf":[{"type":"string"},{"type":"array","items":{"oneOf":[{"type":"object","required":["type","text"],"properties":{"type":{"type":"string","const":"text"},"text":{"type":"string"}}},{"type":"object","required":["type","id","name","input"],"properties":{"type":{"type":"string","const":"tool_use"},"id":{"type":"string"},"name":{"type":"string"},"input":{"type":"object","additionalProperties":true}}},{"type":"object","required":["type","tool_use_id","content"],"properties":{"type":{"type":"string","const":"tool_result"},"tool_use_id":{"type":"string"},"content":{"oneOf":[{"type":"string"},{"type":"array","items":{"type":"object","required":["type","text"],"properties":{"type":{"type":"string","const":"text"},"text":{"type":"string"}}}}]}}}]}}]}}},"ChatCompletionRequest":{"type":"object","required":["model","messages"],"properties":{"model":{"type":"string","minLength":1,"description":"Enabled Keiki agent name or ID."},"messages":{"type":"array","minItems":1,"items":{"$ref":"#/components/schemas/ChatCompletionRequestMessage"}},"stream":{"type":"boolean","default":false,"description":"Return server-sent events instead of one JSON response."},"user":{"type":"string","description":"Caller-defined end-user identifier."},"tools":{"type":"array","description":"Functions the caller can execute when the agent requests them.","items":{"type":"object","required":["type","function"],"properties":{"type":{"type":"string","const":"function"},"function":{"type":"object","required":["name","parameters"],"properties":{"name":{"type":"string","minLength":1},"description":{"type":"string"},"parameters":{"type":"object","additionalProperties":true,"description":"JSON Schema for the function arguments."}}}}}},"tool_choice":{"oneOf":[{"type":"string","enum":["auto","none","required"]},{"type":"object","required":["type","function"],"properties":{"type":{"type":"string","const":"function"},"function":{"type":"object","required":["name"],"properties":{"name":{"type":"string","minLength":1,"maxLength":64}}}}}]},"response_format":{"oneOf":[{"type":"object","required":["type"],"properties":{"type":{"type":"string","const":"text"}}},{"type":"object","required":["type"],"properties":{"type":{"type":"string","const":"json_object"}}},{"type":"object","required":["type","json_schema"],"properties":{"type":{"type":"string","const":"json_schema"},"json_schema":{"type":"object","required":["schema"],"properties":{"name":{"type":"string"},"description":{"type":"string"},"strict":{"type":"boolean"},"schema":{"type":"object","additionalProperties":true}}}}}]},"reasoning_effort":{"type":"string","enum":["minimal","none","low","medium","high"]},"reasoning":{"type":"object","properties":{"enabled":{"type":"boolean"},"effort":{"type":"string","enum":["minimal","none","low","medium","high"]},"max_tokens":{"type":"integer","minimum":0}}}}},"ChatCompletionResponse":{"type":"object","required":["id","object","created","model","choices"],"properties":{"id":{"type":"string"},"object":{"type":"string","const":"chat.completion"},"created":{"type":"integer"},"model":{"type":"string"},"choices":{"type":"array","items":{"type":"object","required":["index","message","finish_reason"],"properties":{"index":{"type":"integer"},"message":{"$ref":"#/components/schemas/ChatCompletionResponseMessage"},"finish_reason":{"type":["string","null"],"enum":["stop","tool_calls",null]}}}},"usage":{"type":"object","properties":{"prompt_tokens":{"type":"integer"},"completion_tokens":{"type":"integer"},"total_tokens":{"type":"integer"}}}}},"AnthropicMessageRequest":{"type":"object","required":["model","messages","max_tokens"],"properties":{"model":{"type":"string","minLength":1,"description":"Enabled Keiki agent name or ID."},"max_tokens":{"type":"integer","minimum":1},"messages":{"type":"array","minItems":1,"items":{"$ref":"#/components/schemas/AnthropicMessage"}},"system":{"oneOf":[{"type":"string"},{"type":"array","items":{"type":"object","additionalProperties":true}}]},"stream":{"type":"boolean","default":false},"thinking":{"oneOf":[{"type":"object","required":["type"],"properties":{"type":{"type":"string","const":"disabled"}}},{"type":"object","required":["type","budget_tokens"],"properties":{"type":{"type":"string","const":"enabled"},"budget_tokens":{"type":"integer","minimum":0}}}]},"tools":{"type":"array","items":{"type":"object","required":["name","input_schema"],"properties":{"name":{"type":"string","minLength":1},"description":{"type":"string"},"input_schema":{"type":"object","additionalProperties":true,"description":"JSON Schema for tool input."}}}},"tool_choice":{"oneOf":[{"type":"object","required":["type"],"properties":{"type":{"type":"string","enum":["auto","any","none"]}}},{"type":"object","required":["type","name"],"properties":{"type":{"type":"string","const":"tool"},"name":{"type":"string","minLength":1,"maxLength":64}}}]}}},"AnthropicTokenCountRequest":{"type":"object","required":["model","messages"],"properties":{"model":{"type":"string","minLength":1,"description":"Enabled Keiki agent name or ID."},"messages":{"type":"array","minItems":1,"items":{"$ref":"#/components/schemas/AnthropicMessage"}},"system":{"oneOf":[{"type":"string"},{"type":"array","items":{"type":"object","additionalProperties":true}}]}}},"AnthropicMessageResponse":{"type":"object","required":["id","type","role","model","content","stop_reason","usage"],"properties":{"id":{"type":"string"},"type":{"type":"string","const":"message"},"role":{"type":"string","const":"assistant"},"model":{"type":"string"},"content":{"type":"array","items":{"type":"object","required":["type"],"properties":{"type":{"type":"string","enum":["text","tool_use"]},"text":{"type":"string"},"id":{"type":"string"},"name":{"type":"string"},"input":{"type":"object","additionalProperties":true}}}},"stop_reason":{"type":["string","null"],"enum":["end_turn","tool_use",null]},"usage":{"type":"object","required":["input_tokens","output_tokens"],"properties":{"input_tokens":{"type":"integer"},"output_tokens":{"type":"integer"}}}}}}}}