{"openapi":"3.1.0","info":{"title":"onetype API","version":"1.0.0"},"servers":[{"url":"/"}],"paths":{"/v1/agents":{"get":{"operationId":"agents.getV1Agents","summary":"Lists the workspace's agents, newest first, a page at a time.","tags":["agents"],"security":[{"apiKey":[]}],"parameters":[{"name":"limit","in":"query","required":false,"schema":{"default":20,"type":"integer","minimum":1,"maximum":100}},{"name":"cursor","in":"query","required":false,"schema":{"type":"string","minLength":1,"maxLength":200}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","const":"list"},"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"object":{"type":"string","const":"agent"},"name":{"type":"string"},"status":{"type":"string","enum":["draft","active"]},"instructions":{"type":"string"},"model":{"type":"string"},"fallbacks":{"type":"array","items":{"type":"string"}},"temperature":{"type":"number","minimum":0,"maximum":1},"fallback":{"type":"string","enum":["escalate","collect-contact","apologize"]},"fallback_message":{"type":"string"},"answers_from_knowledge_only":{"type":"boolean"},"collects_leads":{"type":"boolean"},"welcome_message":{"type":"string"},"suggested_questions":{"type":"array","items":{"type":"string"}},"visibility":{"type":"string","enum":["private","public"]},"allowed_domains":{"type":"array","items":{"type":"string"}},"requires_verified_identity":{"type":"boolean"},"shares_attributes_with_model":{"type":"boolean"},"allows_attachments":{"type":"boolean"},"allows_opt_in_models":{"type":"boolean"},"strict_tools":{"type":"boolean"},"max_tool_iterations":{"type":"integer","minimum":1,"maximum":8},"revision":{"type":"integer","minimum":1,"maximum":9007199254740991},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","object","name","status","instructions","model","fallbacks","temperature","fallback","fallback_message","answers_from_knowledge_only","collects_leads","welcome_message","suggested_questions","visibility","allowed_domains","requires_verified_identity","shares_attributes_with_model","allows_attachments","allows_opt_in_models","strict_tools","max_tool_iterations","revision","created_at","updated_at"],"additionalProperties":false}},"has_more":{"type":"boolean"},"next_cursor":{"type":["string","null"]}},"required":["object","data","has_more","next_cursor"],"additionalProperties":false}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"},"500":{"$ref":"#/components/responses/Error"}},"x-required-permissions":["agents.read"],"x-rate-limit":{"requests":120,"seconds":60}},"post":{"operationId":"agents.postV1Agents","summary":"Creates an agent, a draft unless `status` says otherwise; visibility and domains need agents.security.","tags":["agents"],"security":[{"apiKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"model":{"type":"string","pattern":"^[a-z0-9][a-z0-9._:/-]{0,99}$"},"status":{"type":"string","enum":["draft","active"]},"instructions":{"type":"string"},"visibility":{"type":"string","enum":["private","public"]},"fallback":{"type":"string","enum":["escalate","collect-contact","apologize"]},"fallback_message":{"type":"string"},"fallbacks":{"maxItems":3,"type":"array","items":{"type":"string","pattern":"^[a-z0-9][a-z0-9._:/-]{0,99}$"}},"temperature":{"type":"number","minimum":0,"maximum":1},"answers_from_knowledge_only":{"type":"boolean"},"collects_leads":{"type":"boolean"},"welcome_message":{"type":"string"},"suggested_questions":{"maxItems":10,"type":"array","items":{"type":"string"}},"allowed_domains":{"maxItems":50,"type":"array","items":{"type":"string"}},"requires_verified_identity":{"type":"boolean"},"shares_attributes_with_model":{"type":"boolean"},"allows_attachments":{"type":"boolean"},"max_tool_iterations":{"type":"integer","minimum":1,"maximum":8},"strict_tools":{"type":"boolean"},"allows_opt_in_models":{"type":"boolean"}},"required":["name","model"],"additionalProperties":false}}}},"responses":{"201":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"object":{"type":"string","const":"agent"},"name":{"type":"string"},"status":{"type":"string","enum":["draft","active"]},"instructions":{"type":"string"},"model":{"type":"string"},"fallbacks":{"type":"array","items":{"type":"string"}},"temperature":{"type":"number","minimum":0,"maximum":1},"fallback":{"type":"string","enum":["escalate","collect-contact","apologize"]},"fallback_message":{"type":"string"},"answers_from_knowledge_only":{"type":"boolean"},"collects_leads":{"type":"boolean"},"welcome_message":{"type":"string"},"suggested_questions":{"type":"array","items":{"type":"string"}},"visibility":{"type":"string","enum":["private","public"]},"allowed_domains":{"type":"array","items":{"type":"string"}},"requires_verified_identity":{"type":"boolean"},"shares_attributes_with_model":{"type":"boolean"},"allows_attachments":{"type":"boolean"},"allows_opt_in_models":{"type":"boolean"},"strict_tools":{"type":"boolean"},"max_tool_iterations":{"type":"integer","minimum":1,"maximum":8},"revision":{"type":"integer","minimum":1,"maximum":9007199254740991},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","object","name","status","instructions","model","fallbacks","temperature","fallback","fallback_message","answers_from_knowledge_only","collects_leads","welcome_message","suggested_questions","visibility","allowed_domains","requires_verified_identity","shares_attributes_with_model","allows_attachments","allows_opt_in_models","strict_tools","max_tool_iterations","revision","created_at","updated_at"],"additionalProperties":false}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"},"500":{"$ref":"#/components/responses/Error"}},"x-required-permissions":["agents.create"],"x-rate-limit":{"requests":30,"seconds":60}}},"/v1/agents/{id}":{"get":{"operationId":"agents.getV1AgentsId","summary":"Reads one agent.","tags":["agents"],"security":[{"apiKey":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":64}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"object":{"type":"string","const":"agent"},"name":{"type":"string"},"status":{"type":"string","enum":["draft","active"]},"instructions":{"type":"string"},"model":{"type":"string"},"fallbacks":{"type":"array","items":{"type":"string"}},"temperature":{"type":"number","minimum":0,"maximum":1},"fallback":{"type":"string","enum":["escalate","collect-contact","apologize"]},"fallback_message":{"type":"string"},"answers_from_knowledge_only":{"type":"boolean"},"collects_leads":{"type":"boolean"},"welcome_message":{"type":"string"},"suggested_questions":{"type":"array","items":{"type":"string"}},"visibility":{"type":"string","enum":["private","public"]},"allowed_domains":{"type":"array","items":{"type":"string"}},"requires_verified_identity":{"type":"boolean"},"shares_attributes_with_model":{"type":"boolean"},"allows_attachments":{"type":"boolean"},"allows_opt_in_models":{"type":"boolean"},"strict_tools":{"type":"boolean"},"max_tool_iterations":{"type":"integer","minimum":1,"maximum":8},"revision":{"type":"integer","minimum":1,"maximum":9007199254740991},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","object","name","status","instructions","model","fallbacks","temperature","fallback","fallback_message","answers_from_knowledge_only","collects_leads","welcome_message","suggested_questions","visibility","allowed_domains","requires_verified_identity","shares_attributes_with_model","allows_attachments","allows_opt_in_models","strict_tools","max_tool_iterations","revision","created_at","updated_at"],"additionalProperties":false}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"},"500":{"$ref":"#/components/responses/Error"}},"x-required-permissions":["agents.read"],"x-rate-limit":{"requests":120,"seconds":60}},"patch":{"operationId":"agents.patchV1AgentsId","summary":"Changes the named fields; `revision` from a read refuses a change made since. Visibility and domains need agents.security.","tags":["agents"],"security":[{"apiKey":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":64}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"model":{"type":"string","pattern":"^[a-z0-9][a-z0-9._:/-]{0,99}$"},"status":{"type":"string","enum":["draft","active"]},"instructions":{"type":"string"},"visibility":{"type":"string","enum":["private","public"]},"fallback":{"type":"string","enum":["escalate","collect-contact","apologize"]},"fallback_message":{"type":"string"},"fallbacks":{"maxItems":3,"type":"array","items":{"type":"string","pattern":"^[a-z0-9][a-z0-9._:/-]{0,99}$"}},"temperature":{"type":"number","minimum":0,"maximum":1},"answers_from_knowledge_only":{"type":"boolean"},"collects_leads":{"type":"boolean"},"welcome_message":{"type":"string"},"suggested_questions":{"maxItems":10,"type":"array","items":{"type":"string"}},"allowed_domains":{"maxItems":50,"type":"array","items":{"type":"string"}},"requires_verified_identity":{"type":"boolean"},"shares_attributes_with_model":{"type":"boolean"},"allows_attachments":{"type":"boolean"},"max_tool_iterations":{"type":"integer","minimum":1,"maximum":8},"strict_tools":{"type":"boolean"},"allows_opt_in_models":{"type":"boolean"},"revision":{"type":"integer","minimum":1,"maximum":9007199254740991}},"additionalProperties":false}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"object":{"type":"string","const":"agent"},"name":{"type":"string"},"status":{"type":"string","enum":["draft","active"]},"instructions":{"type":"string"},"model":{"type":"string"},"fallbacks":{"type":"array","items":{"type":"string"}},"temperature":{"type":"number","minimum":0,"maximum":1},"fallback":{"type":"string","enum":["escalate","collect-contact","apologize"]},"fallback_message":{"type":"string"},"answers_from_knowledge_only":{"type":"boolean"},"collects_leads":{"type":"boolean"},"welcome_message":{"type":"string"},"suggested_questions":{"type":"array","items":{"type":"string"}},"visibility":{"type":"string","enum":["private","public"]},"allowed_domains":{"type":"array","items":{"type":"string"}},"requires_verified_identity":{"type":"boolean"},"shares_attributes_with_model":{"type":"boolean"},"allows_attachments":{"type":"boolean"},"allows_opt_in_models":{"type":"boolean"},"strict_tools":{"type":"boolean"},"max_tool_iterations":{"type":"integer","minimum":1,"maximum":8},"revision":{"type":"integer","minimum":1,"maximum":9007199254740991},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","object","name","status","instructions","model","fallbacks","temperature","fallback","fallback_message","answers_from_knowledge_only","collects_leads","welcome_message","suggested_questions","visibility","allowed_domains","requires_verified_identity","shares_attributes_with_model","allows_attachments","allows_opt_in_models","strict_tools","max_tool_iterations","revision","created_at","updated_at"],"additionalProperties":false}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"},"500":{"$ref":"#/components/responses/Error"}},"x-required-permissions":["agents.update"],"x-rate-limit":{"requests":60,"seconds":60}},"delete":{"operationId":"agents.deleteV1AgentsId","summary":"Deletes an agent.","tags":["agents"],"security":[{"apiKey":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":64}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"object":{"type":"string","const":"agent"},"deleted":{"type":"boolean","const":true}},"required":["id","object","deleted"],"additionalProperties":false}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"},"500":{"$ref":"#/components/responses/Error"}},"x-required-permissions":["agents.delete"],"x-rate-limit":{"requests":30,"seconds":60}}},"/v1/conversations":{"post":{"operationId":"answers.postV1Conversations","summary":"Opens a conversation with an agent, for your server to send messages into. Retry safely with an Idempotency-Key.","tags":["answers"],"security":[{"apiKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"agent":{"type":"string","minLength":1,"maxLength":200}},"required":["agent"],"additionalProperties":false}}}},"responses":{"201":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"object":{"type":"string","const":"conversation"},"agent":{"type":"string"},"contact":{"type":["string","null"]},"channel":{"type":"string","enum":["widget","api","playground","preview"]},"status":{"type":"string","enum":["open","escalated","resolved","unresolved","failed"]},"handler":{"type":"string","enum":["ai","human"]},"resolved_by":{"anyOf":[{"type":"string","enum":["member","idle","visitor","ai"]},{"type":"null"}]},"topic":{"type":["string","null"]},"message_count":{"type":"integer","minimum":0,"maximum":9007199254740991},"created_at":{"type":"string"},"last_active_at":{"type":"string"},"resolved_at":{"type":["string","null"]}},"required":["id","object","agent","contact","channel","status","handler","resolved_by","topic","message_count","created_at","last_active_at","resolved_at"],"additionalProperties":false}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"},"500":{"$ref":"#/components/responses/Error"}},"x-required-permissions":[],"x-rate-limit":{"requests":60,"seconds":60}},"get":{"operationId":"conversations.getV1Conversations","summary":"Lists conversations, newest first, a page at a time; narrowed by agent, status, and started at or after `created[gte]` (epoch ms).","tags":["conversations"],"security":[{"apiKey":[]}],"parameters":[{"name":"limit","in":"query","required":false,"schema":{"default":20,"type":"integer","minimum":1,"maximum":100}},{"name":"cursor","in":"query","required":false,"schema":{"type":"string","minLength":1,"maxLength":200}},{"name":"agent","in":"query","required":false,"schema":{"type":"string","minLength":1,"maxLength":64}},{"name":"status","in":"query","required":false,"schema":{"type":"string","enum":["open","escalated","resolved","unresolved","failed"]}},{"name":"created[gte]","in":"query","required":false,"schema":{"type":"integer","minimum":0,"maximum":9007199254740991}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","const":"list"},"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"object":{"type":"string","const":"conversation"},"agent":{"type":"string"},"contact":{"type":["string","null"]},"channel":{"type":"string","enum":["widget","api","playground","preview"]},"status":{"type":"string","enum":["open","escalated","resolved","unresolved","failed"]},"handler":{"type":"string","enum":["ai","human"]},"resolved_by":{"anyOf":[{"type":"string","enum":["member","idle","visitor","ai"]},{"type":"null"}]},"topic":{"type":["string","null"]},"message_count":{"type":"integer","minimum":0,"maximum":9007199254740991},"created_at":{"type":"string"},"last_active_at":{"type":"string"},"resolved_at":{"type":["string","null"]}},"required":["id","object","agent","contact","channel","status","handler","resolved_by","topic","message_count","created_at","last_active_at","resolved_at"],"additionalProperties":false}},"has_more":{"type":"boolean"},"next_cursor":{"type":["string","null"]}},"required":["object","data","has_more","next_cursor"],"additionalProperties":false}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"},"500":{"$ref":"#/components/responses/Error"}},"x-required-permissions":["conversations.read"],"x-rate-limit":{"requests":120,"seconds":60}}},"/v1/conversations/{id}/messages":{"post":{"operationId":"answers.postV1ConversationsIdMessages","summary":"Sends a message into a conversation and answers the agent's reply once it is written. Retry safely with an Idempotency-Key.","tags":["answers"],"security":[{"apiKey":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":200}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"content":{"type":"string"},"stream":{"type":"boolean"}},"required":["content"],"additionalProperties":false}}}},"responses":{"201":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"object":{"type":"string","const":"message"},"conversation":{"type":"string"},"role":{"type":"string","enum":["user","assistant","human","system","tool"]},"is_ai_generated":{"type":"boolean"},"parts":{"type":"array","items":{"oneOf":[{"type":"object","properties":{"type":{"type":"string","const":"text"},"text":{"type":"string"}},"required":["type","text"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"notice"},"code":{"type":"string","enum":["human_joined","human_left","ai_resumed","resolved"]},"name":{"type":"string"}},"required":["type","code"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"source-document"},"sourceId":{"type":"string","minLength":1,"maxLength":200},"chunkId":{"type":"string","minLength":1,"maxLength":200},"mediaType":{"type":"string","minLength":1,"maxLength":100},"title":{"type":"string"},"url":{"type":"string","format":"uri"},"page":{"type":"integer","minimum":1,"maximum":100000}},"required":["type","sourceId","title"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"file"},"mediaType":{"type":"string","enum":["image/png","image/jpeg","image/webp"]},"objectId":{"type":"string","minLength":1,"maxLength":200},"filename":{"type":"string"}},"required":["type","mediaType","objectId"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"tool-call"},"toolCallId":{"type":"string","minLength":1,"maxLength":200},"toolName":{"type":"string","pattern":"^[A-Za-z0-9_-]{1,64}$"},"input":{"type":"string","maxLength":20000},"approval":{"type":"string","enum":["approved","denied","expired"]}},"required":["type","toolCallId","toolName","input"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"tool-result"},"toolCallId":{"type":"string","minLength":1,"maxLength":200},"toolName":{"type":"string","pattern":"^[A-Za-z0-9_-]{1,64}$"},"output":{"type":"string","maxLength":20000},"isError":{"type":"boolean"}},"required":["type","toolCallId","toolName","output","isError"],"additionalProperties":false}]}},"rating":{"anyOf":[{"type":"string","enum":["up","down"]},{"type":"null"}]},"created_at":{"type":"string"}},"required":["id","object","conversation","role","is_ai_generated","parts","rating","created_at"],"additionalProperties":false}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"},"500":{"$ref":"#/components/responses/Error"}},"x-required-permissions":[],"x-rate-limit":{"requests":20,"seconds":10}},"get":{"operationId":"conversations.getV1ConversationsIdMessages","summary":"Lists a conversation's messages, oldest first, a page at a time; each says whether a machine made it.","tags":["conversations"],"security":[{"apiKey":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":64}},{"name":"limit","in":"query","required":false,"schema":{"default":20,"type":"integer","minimum":1,"maximum":100}},{"name":"cursor","in":"query","required":false,"schema":{"type":"string","minLength":1,"maxLength":200}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","const":"list"},"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"object":{"type":"string","const":"message"},"conversation":{"type":"string"},"role":{"type":"string","enum":["user","assistant","human","system","tool"]},"is_ai_generated":{"type":"boolean"},"parts":{"type":"array","items":{"oneOf":[{"type":"object","properties":{"type":{"type":"string","const":"text"},"text":{"type":"string"}},"required":["type","text"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"notice"},"code":{"type":"string","enum":["human_joined","human_left","ai_resumed","resolved"]},"name":{"type":"string"}},"required":["type","code"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"source-document"},"sourceId":{"type":"string","minLength":1,"maxLength":200},"chunkId":{"type":"string","minLength":1,"maxLength":200},"mediaType":{"type":"string","minLength":1,"maxLength":100},"title":{"type":"string"},"url":{"type":"string","format":"uri"},"page":{"type":"integer","minimum":1,"maximum":100000}},"required":["type","sourceId","title"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"file"},"mediaType":{"type":"string","enum":["image/png","image/jpeg","image/webp"]},"objectId":{"type":"string","minLength":1,"maxLength":200},"filename":{"type":"string"}},"required":["type","mediaType","objectId"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"tool-call"},"toolCallId":{"type":"string","minLength":1,"maxLength":200},"toolName":{"type":"string","pattern":"^[A-Za-z0-9_-]{1,64}$"},"input":{"type":"string","maxLength":20000},"approval":{"type":"string","enum":["approved","denied","expired"]}},"required":["type","toolCallId","toolName","input"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"tool-result"},"toolCallId":{"type":"string","minLength":1,"maxLength":200},"toolName":{"type":"string","pattern":"^[A-Za-z0-9_-]{1,64}$"},"output":{"type":"string","maxLength":20000},"isError":{"type":"boolean"}},"required":["type","toolCallId","toolName","output","isError"],"additionalProperties":false}]}},"rating":{"anyOf":[{"type":"string","enum":["up","down"]},{"type":"null"}]},"created_at":{"type":"string"}},"required":["id","object","conversation","role","is_ai_generated","parts","rating","created_at"],"additionalProperties":false}},"has_more":{"type":"boolean"},"next_cursor":{"type":["string","null"]}},"required":["object","data","has_more","next_cursor"],"additionalProperties":false}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"},"500":{"$ref":"#/components/responses/Error"}},"x-required-permissions":["conversations.read"],"x-rate-limit":{"requests":120,"seconds":60}}},"/v1/contacts":{"get":{"operationId":"contacts.getV1Contacts","summary":"Lists the workspace's contacts, newest first, a page at a time; narrowed to one agent's by agent.","tags":["contacts"],"security":[{"apiKey":[]}],"parameters":[{"name":"limit","in":"query","required":false,"schema":{"default":20,"type":"integer","minimum":1,"maximum":100}},{"name":"cursor","in":"query","required":false,"schema":{"type":"string","minLength":1,"maxLength":200}},{"name":"agent","in":"query","required":false,"schema":{"type":"string","minLength":1,"maxLength":64}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","const":"list"},"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"object":{"type":"string","const":"contact"},"agent":{"type":["string","null"]},"external_id":{"type":["string","null"]},"name":{"type":["string","null"]},"email":{"type":["string","null"]},"phone":{"type":["string","null"]},"is_verified":{"type":"boolean"},"is_lead":{"type":"boolean"},"lead_captured_at":{"type":["string","null"]},"consent":{"anyOf":[{"type":"object","properties":{"marketing":{"type":"boolean"},"at":{"type":"string"}},"required":["marketing","at"],"additionalProperties":false},{"type":"null"}]},"source":{"type":"string","enum":["widget","api","import"]},"attributes":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string"},"value":{"anyOf":[{"type":"string","maxLength":2000},{"type":"number"},{"type":"boolean"}]}},"required":["key","value"],"additionalProperties":false}},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","object","agent","external_id","name","email","phone","is_verified","is_lead","lead_captured_at","consent","source","attributes","created_at","updated_at"],"additionalProperties":false}},"has_more":{"type":"boolean"},"next_cursor":{"type":["string","null"]}},"required":["object","data","has_more","next_cursor"],"additionalProperties":false}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"},"500":{"$ref":"#/components/responses/Error"}},"x-required-permissions":["contacts.read"],"x-rate-limit":{"requests":120,"seconds":60}}},"/v1/contacts/{id}":{"get":{"operationId":"contacts.getV1ContactsId","summary":"Reads one contact; the secure claims never leave the server.","tags":["contacts"],"security":[{"apiKey":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":64}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"object":{"type":"string","const":"contact"},"agent":{"type":["string","null"]},"external_id":{"type":["string","null"]},"name":{"type":["string","null"]},"email":{"type":["string","null"]},"phone":{"type":["string","null"]},"is_verified":{"type":"boolean"},"is_lead":{"type":"boolean"},"lead_captured_at":{"type":["string","null"]},"consent":{"anyOf":[{"type":"object","properties":{"marketing":{"type":"boolean"},"at":{"type":"string"}},"required":["marketing","at"],"additionalProperties":false},{"type":"null"}]},"source":{"type":"string","enum":["widget","api","import"]},"attributes":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string"},"value":{"anyOf":[{"type":"string","maxLength":2000},{"type":"number"},{"type":"boolean"}]}},"required":["key","value"],"additionalProperties":false}},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","object","agent","external_id","name","email","phone","is_verified","is_lead","lead_captured_at","consent","source","attributes","created_at","updated_at"],"additionalProperties":false}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"},"500":{"$ref":"#/components/responses/Error"}},"x-required-permissions":["contacts.read"],"x-rate-limit":{"requests":120,"seconds":60}}},"/v1/conversations/{id}":{"get":{"operationId":"conversations.getV1ConversationsId","summary":"Reads one conversation.","tags":["conversations"],"security":[{"apiKey":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":64}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"object":{"type":"string","const":"conversation"},"agent":{"type":"string"},"contact":{"type":["string","null"]},"channel":{"type":"string","enum":["widget","api","playground","preview"]},"status":{"type":"string","enum":["open","escalated","resolved","unresolved","failed"]},"handler":{"type":"string","enum":["ai","human"]},"resolved_by":{"anyOf":[{"type":"string","enum":["member","idle","visitor","ai"]},{"type":"null"}]},"topic":{"type":["string","null"]},"message_count":{"type":"integer","minimum":0,"maximum":9007199254740991},"created_at":{"type":"string"},"last_active_at":{"type":"string"},"resolved_at":{"type":["string","null"]}},"required":["id","object","agent","contact","channel","status","handler","resolved_by","topic","message_count","created_at","last_active_at","resolved_at"],"additionalProperties":false}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"},"500":{"$ref":"#/components/responses/Error"}},"x-required-permissions":["conversations.read"],"x-rate-limit":{"requests":120,"seconds":60}}},"/v1/mcp":{"post":{"operationId":"mcp.postV1Mcp","summary":"The MCP server (Streamable HTTP): one JSON-RPC message a request, answered as JSON.","tags":["mcp"],"security":[{"apiKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"jsonrpc":{"type":"string","const":"2.0"},"id":{"anyOf":[{"type":"string","maxLength":200},{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}]},"method":{"type":"string","minLength":1,"maxLength":100},"params":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}}},"required":["jsonrpc","method"],"additionalProperties":false}}}},"responses":{"201":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"jsonrpc":{"type":"string","const":"2.0"},"id":{"anyOf":[{"anyOf":[{"type":"string","maxLength":200},{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}]},{"type":"null"}]},"result":{"type":"object","properties":{"protocolVersion":{"type":"string"},"capabilities":{"type":"object","properties":{"tools":{"type":"object","properties":{"listChanged":{"type":"boolean"}},"required":["listChanged"],"additionalProperties":false},"resources":{"type":"object","properties":{"listChanged":{"type":"boolean"},"subscribe":{"type":"boolean"}},"required":["listChanged","subscribe"],"additionalProperties":false},"prompts":{"type":"object","properties":{"listChanged":{"type":"boolean"}},"required":["listChanged"],"additionalProperties":false}},"additionalProperties":false},"serverInfo":{"type":"object","properties":{"name":{"type":"string"},"title":{"type":"string"},"version":{"type":"string"}},"required":["name","title","version"],"additionalProperties":false},"instructions":{"type":"string"},"tools":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"title":{"type":"string"},"description":{"type":"string"},"inputSchema":{"type":"object","properties":{"type":{"type":"string","const":"object"},"properties":{"type":"object","propertyNames":{"type":"string","pattern":"^[a-z][a-z_]{0,39}$"},"additionalProperties":{"type":"object","properties":{"type":{"type":"string","enum":["string","integer","number","boolean"]},"description":{"type":"string"},"enum":{"readOnly":true,"type":"array","items":{"type":"string"}},"minimum":{"type":"number"},"maximum":{"type":"number"},"maxLength":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["type"],"additionalProperties":false}},"required":{"type":"array","items":{"type":"string"}},"additionalProperties":{"type":"boolean"}},"required":["type","properties","required","additionalProperties"],"additionalProperties":false},"annotations":{"type":"object","properties":{"title":{"type":"string"},"readOnlyHint":{"type":"boolean"},"destructiveHint":{"type":"boolean"},"idempotentHint":{"type":"boolean"},"openWorldHint":{"type":"boolean"}},"required":["title","readOnlyHint","destructiveHint","idempotentHint","openWorldHint"],"additionalProperties":false}},"required":["name","title","description","inputSchema","annotations"],"additionalProperties":false}},"content":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","const":"text"},"text":{"type":"string"}},"required":["type","text"],"additionalProperties":false}},"isError":{"type":"boolean"},"resources":{"type":"array","items":{"type":"object","properties":{"uri":{"type":"string"},"name":{"type":"string"},"title":{"type":"string"},"mimeType":{"type":"string"},"description":{"type":"string"}},"required":["uri","name","title","mimeType"],"additionalProperties":false}},"resourceTemplates":{"type":"array","items":{"type":"object","properties":{"uriTemplate":{"type":"string"},"name":{"type":"string"},"title":{"type":"string"},"mimeType":{"type":"string"},"description":{"type":"string"}},"required":["uriTemplate","name","title","mimeType","description"],"additionalProperties":false}},"contents":{"type":"array","items":{"type":"object","properties":{"uri":{"type":"string"},"mimeType":{"type":"string"},"text":{"type":"string"}},"required":["uri","mimeType","text"],"additionalProperties":false}},"prompts":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"title":{"type":"string"},"description":{"type":"string"},"arguments":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string"},"required":{"type":"boolean"}},"required":["name","description","required"],"additionalProperties":false}}},"required":["name","title","description","arguments"],"additionalProperties":false}},"description":{"type":"string"},"messages":{"type":"array","items":{"type":"object","properties":{"role":{"type":"string","const":"user"},"content":{"type":"object","properties":{"type":{"type":"string","const":"text"},"text":{"type":"string"}},"required":["type","text"],"additionalProperties":false}},"required":["role","content"],"additionalProperties":false}}},"additionalProperties":false},"error":{"type":"object","properties":{"code":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false}},"additionalProperties":false}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"},"500":{"$ref":"#/components/responses/Error"}},"x-required-permissions":[],"x-rate-limit":{"requests":120,"seconds":60}},"get":{"operationId":"mcp.getV1Mcp","summary":"No server-sent stream is offered; MCP clients read the 405 as that.","tags":["mcp"],"security":[{"apiKey":[]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{},"additionalProperties":false}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"},"500":{"$ref":"#/components/responses/Error"}},"x-required-permissions":[],"x-rate-limit":{"requests":60,"seconds":60}},"delete":{"operationId":"mcp.deleteV1Mcp","summary":"Ends the MCP session named by Mcp-Session-Id.","tags":["mcp"],"security":[{"apiKey":[]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"},"500":{"$ref":"#/components/responses/Error"}},"x-required-permissions":[],"x-rate-limit":{"requests":60,"seconds":60}}},"/v1/mcp/agents/{agent}":{"post":{"operationId":"mcp.postV1McpAgentsAgent","summary":"One agent's hosted MCP server: search_docs and ask_agent over that agent's knowledge, for a key holding mcp.agent.","tags":["mcp"],"security":[{"apiKey":[]}],"parameters":[{"name":"agent","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":80}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"jsonrpc":{"type":"string","const":"2.0"},"id":{"anyOf":[{"type":"string","maxLength":200},{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}]},"method":{"type":"string","minLength":1,"maxLength":100},"params":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}}},"required":["jsonrpc","method"],"additionalProperties":false}}}},"responses":{"201":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"jsonrpc":{"type":"string","const":"2.0"},"id":{"anyOf":[{"anyOf":[{"type":"string","maxLength":200},{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}]},{"type":"null"}]},"result":{"type":"object","properties":{"protocolVersion":{"type":"string"},"capabilities":{"type":"object","properties":{"tools":{"type":"object","properties":{"listChanged":{"type":"boolean"}},"required":["listChanged"],"additionalProperties":false},"resources":{"type":"object","properties":{"listChanged":{"type":"boolean"},"subscribe":{"type":"boolean"}},"required":["listChanged","subscribe"],"additionalProperties":false},"prompts":{"type":"object","properties":{"listChanged":{"type":"boolean"}},"required":["listChanged"],"additionalProperties":false}},"additionalProperties":false},"serverInfo":{"type":"object","properties":{"name":{"type":"string"},"title":{"type":"string"},"version":{"type":"string"}},"required":["name","title","version"],"additionalProperties":false},"instructions":{"type":"string"},"tools":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"title":{"type":"string"},"description":{"type":"string"},"inputSchema":{"type":"object","properties":{"type":{"type":"string","const":"object"},"properties":{"type":"object","propertyNames":{"type":"string","pattern":"^[a-z][a-z_]{0,39}$"},"additionalProperties":{"type":"object","properties":{"type":{"type":"string","enum":["string","integer","number","boolean"]},"description":{"type":"string"},"enum":{"readOnly":true,"type":"array","items":{"type":"string"}},"minimum":{"type":"number"},"maximum":{"type":"number"},"maxLength":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["type"],"additionalProperties":false}},"required":{"type":"array","items":{"type":"string"}},"additionalProperties":{"type":"boolean"}},"required":["type","properties","required","additionalProperties"],"additionalProperties":false},"annotations":{"type":"object","properties":{"title":{"type":"string"},"readOnlyHint":{"type":"boolean"},"destructiveHint":{"type":"boolean"},"idempotentHint":{"type":"boolean"},"openWorldHint":{"type":"boolean"}},"required":["title","readOnlyHint","destructiveHint","idempotentHint","openWorldHint"],"additionalProperties":false}},"required":["name","title","description","inputSchema","annotations"],"additionalProperties":false}},"content":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","const":"text"},"text":{"type":"string"}},"required":["type","text"],"additionalProperties":false}},"isError":{"type":"boolean"},"resources":{"type":"array","items":{"type":"object","properties":{"uri":{"type":"string"},"name":{"type":"string"},"title":{"type":"string"},"mimeType":{"type":"string"},"description":{"type":"string"}},"required":["uri","name","title","mimeType"],"additionalProperties":false}},"resourceTemplates":{"type":"array","items":{"type":"object","properties":{"uriTemplate":{"type":"string"},"name":{"type":"string"},"title":{"type":"string"},"mimeType":{"type":"string"},"description":{"type":"string"}},"required":["uriTemplate","name","title","mimeType","description"],"additionalProperties":false}},"contents":{"type":"array","items":{"type":"object","properties":{"uri":{"type":"string"},"mimeType":{"type":"string"},"text":{"type":"string"}},"required":["uri","mimeType","text"],"additionalProperties":false}},"prompts":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"title":{"type":"string"},"description":{"type":"string"},"arguments":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string"},"required":{"type":"boolean"}},"required":["name","description","required"],"additionalProperties":false}}},"required":["name","title","description","arguments"],"additionalProperties":false}},"description":{"type":"string"},"messages":{"type":"array","items":{"type":"object","properties":{"role":{"type":"string","const":"user"},"content":{"type":"object","properties":{"type":{"type":"string","const":"text"},"text":{"type":"string"}},"required":["type","text"],"additionalProperties":false}},"required":["role","content"],"additionalProperties":false}}},"additionalProperties":false},"error":{"type":"object","properties":{"code":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false}},"additionalProperties":false}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"},"500":{"$ref":"#/components/responses/Error"}},"x-required-permissions":["mcp.agent"],"x-rate-limit":{"requests":120,"seconds":60}},"get":{"operationId":"mcp.getV1McpAgentsAgent","summary":"No server-sent stream is offered; MCP clients read the 405 as that.","tags":["mcp"],"security":[{"apiKey":[]}],"parameters":[{"name":"agent","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":80}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{},"additionalProperties":false}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"},"500":{"$ref":"#/components/responses/Error"}},"x-required-permissions":["mcp.agent"],"x-rate-limit":{"requests":60,"seconds":60}},"delete":{"operationId":"mcp.deleteV1McpAgentsAgent","summary":"Ends the MCP session named by Mcp-Session-Id.","tags":["mcp"],"security":[{"apiKey":[]}],"parameters":[{"name":"agent","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":80}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"},"500":{"$ref":"#/components/responses/Error"}},"x-required-permissions":["mcp.agent"],"x-rate-limit":{"requests":60,"seconds":60}}}},"components":{"securitySchemes":{"apiKey":{"type":"http","scheme":"bearer","description":"A secret (sk_live_) or restricted (rk_live_) key."}},"responses":{"Error":{"description":"Refused: the code says why, the message how to fix it.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["status","code","message"],"properties":{"status":{"type":"integer"},"code":{"type":"string"},"message":{"type":"string"},"fields":{"type":"object","additionalProperties":{"type":"string"}}}}}}}}}}}}