{ "openapi": "3.1.0", "info": { "title": "Yekar.AI public API", "version": "1.0.0", "description": "The routes your own software calls with a personal API key: fire a trigger, run a published agent and follow it live, reach your agents from an MCP client, and build agents, pick integrations and write knowledge from code.\n\nEvery route here also answers at its former address under `/api/v1` (for example `/api/v1/triggers/fire`), so an integration written against the old base URL keeps working. New integrations should use the base URL below.\n\nThis document is generated from the same definitions the server validates requests with and is published at `/openapi/public-v1.json` in the manual and at `/api/public/v1/openapi.json` on the API." }, "servers": [ { "url": "https://api.yekar.ai/api/public/v1", "description": "Replace the origin with your deployment's API address if you are not on the hosted service." } ], "tags": [ { "name": "Specification" }, { "name": "Triggers" }, { "name": "Agents" }, { "name": "MCP" }, { "name": "Agent authoring" }, { "name": "Integrations" }, { "name": "Knowledge" } ], "paths": { "/openapi.json": { "get": { "operationId": "getOpenApiDocument", "tags": [ "Specification" ], "summary": "Read this API's OpenAPI document", "description": "The machine-readable description of every public route, generated from the same definitions the server validates requests with. Needs no key.", "responses": { "200": { "description": "The OpenAPI 3.1 document." } }, "security": [] } }, "/triggers/fire": { "post": { "operationId": "fireTrigger", "tags": [ "Triggers" ], "summary": "Fire a trigger", "description": "Fire an active API trigger. One request fans out to every subscribed agent and flow, starting one session for each successful start. `202` means the request was accepted, not that the work finished - register a webhook or read the sessions to follow it.\n\nSend `Idempotency-Key` (or `idempotencyKey` in the body) to retry safely: a replay returns the original result with `Idempotency-Replayed: true` and never starts another run.\n\nA missing or invalid key, a key without the required scope, an unknown id or an id in another organization all return the same `404 NOT_FOUND`.\n\n**Key scope:** `triggers:fire` (Fire triggers).", "x-yekar-key-scope": "triggers:fire", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "idempotencyKey": { "type": "string", "pattern": "^[A-Za-z0-9._:-]{1,128}$" }, "triggerId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "input": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "callerCredentials": { "type": "object", "properties": { "integrations": { "type": "object", "propertyNames": { "type": "string", "minLength": 1, "maxLength": 64 }, "additionalProperties": { "type": "object", "properties": { "token": { "type": "string", "minLength": 1, "maxLength": 8192, "pattern": "^[^\\r\\n]+$" }, "fields": { "type": "object", "propertyNames": { "type": "string", "pattern": "^[A-Za-z0-9_]{1,64}$" }, "additionalProperties": { "type": "string", "minLength": 1, "maxLength": 8192, "pattern": "^[^\\r\\n]+$" } }, "refresh": { "type": "object", "properties": { "refreshToken": { "type": "string", "minLength": 1, "maxLength": 8192, "pattern": "^[^\\r\\n]+$" }, "clientId": { "type": "string", "minLength": 1, "maxLength": 512 }, "clientSecret": { "type": "string", "minLength": 1, "maxLength": 8192, "pattern": "^[^\\r\\n]+$" }, "tokenUrl": { "type": "string", "maxLength": 2048, "format": "uri" }, "authMethod": { "type": "string", "enum": [ "client_secret_basic", "client_secret_post" ] } }, "required": [ "refreshToken" ], "additionalProperties": false }, "fallbackAllowed": { "type": "boolean" } }, "additionalProperties": false } } }, "required": [ "integrations" ], "additionalProperties": false }, "callerCredentialExpiresAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" } }, "required": [ "triggerId" ], "additionalProperties": false } } } }, "responses": { "202": { "description": "Accepted. One entry per agent or flow that started, and the subscribers that were skipped with the reason.", "content": { "application/json": { "schema": { "type": "object", "properties": { "sessions": { "type": "array", "items": { "type": "object", "properties": { "automationId": { "type": "string" }, "sessionId": { "type": "string" } }, "required": [ "automationId", "sessionId" ], "additionalProperties": false } }, "skipped": { "type": "array", "items": { "type": "object", "properties": { "automationId": { "type": "string" }, "automationName": { "type": "string" }, "reason": { "type": "string", "enum": [ "unpublished", "inactive", "integration_not_unattended", "person_unavailable", "worker_paused", "cost_cap_reached", "event_input_unpublished", "procedure_off", "entitlement_disabled", "missing" ] } }, "required": [ "automationId", "automationName", "reason" ], "additionalProperties": false } } }, "required": [ "sessions", "skipped" ], "additionalProperties": false } } } }, "400": { "description": "The body is invalid - an unknown field, a missing one or a bad value (`VALIDATION`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found: the key is missing, invalid or lacks the scope, or the target does not exist or is in another organization.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Too many requests from this key or address (`RATE_LIMITED`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "personalApiKey": [] } ] } }, "/agents/{automationId}/sessions": { "post": { "operationId": "startAgentSession", "tags": [ "Agents" ], "summary": "Start a conversation with an agent", "description": "Open a session on a published agent and queue its first turn. The agent must be published and the key's owner must be allowed to run it. Include `callerCredentials` when the agent should act on your end user's own account for a bound integration.\n\n`202` means the first turn was accepted. Follow it on the session's event stream.\n\nA missing or invalid key, a key without the required scope, an unknown id or an id in another organization all return the same `404 NOT_FOUND`.\n\n**Key scope:** `agents:run` (Run agents).", "x-yekar-key-scope": "agents:run", "parameters": [ { "name": "automationId", "in": "path", "required": true, "description": "The agent's id, from its page URL in the product.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "minLength": 1, "maxLength": 8000 }, "callerCredentials": { "type": "object", "properties": { "integrations": { "type": "object", "propertyNames": { "type": "string", "minLength": 1, "maxLength": 64 }, "additionalProperties": { "type": "object", "properties": { "token": { "type": "string", "minLength": 1, "maxLength": 8192, "pattern": "^[^\\r\\n]+$" }, "fields": { "type": "object", "propertyNames": { "type": "string", "pattern": "^[A-Za-z0-9_]{1,64}$" }, "additionalProperties": { "type": "string", "minLength": 1, "maxLength": 8192, "pattern": "^[^\\r\\n]+$" } }, "refresh": { "type": "object", "properties": { "refreshToken": { "type": "string", "minLength": 1, "maxLength": 8192, "pattern": "^[^\\r\\n]+$" }, "clientId": { "type": "string", "minLength": 1, "maxLength": 512 }, "clientSecret": { "type": "string", "minLength": 1, "maxLength": 8192, "pattern": "^[^\\r\\n]+$" }, "tokenUrl": { "type": "string", "maxLength": 2048, "format": "uri" }, "authMethod": { "type": "string", "enum": [ "client_secret_basic", "client_secret_post" ] } }, "required": [ "refreshToken" ], "additionalProperties": false }, "fallbackAllowed": { "type": "boolean" } }, "additionalProperties": false } } }, "required": [ "integrations" ], "additionalProperties": false } }, "required": [ "message" ], "additionalProperties": false } } } }, "responses": { "202": { "description": "Accepted. The new session and its first execution.", "content": { "application/json": { "schema": { "type": "object", "properties": { "sessionId": { "type": "string" }, "executionId": { "type": "string" } }, "required": [ "sessionId", "executionId" ], "additionalProperties": false } } } }, "400": { "description": "The body is invalid - an unknown field, a missing one or a bad value (`VALIDATION`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found: the key is missing, invalid or lacks the scope, or the target does not exist or is in another organization.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Too many requests from this key or address (`RATE_LIMITED`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "personalApiKey": [] } ] } }, "/agents/sessions": { "get": { "operationId": "listAgentSessions", "tags": [ "Agents" ], "summary": "List conversations", "description": "The agent conversations the key's owner can see, newest activity first. Narrow to one agent with `agentId`; `q` searches titles and agent names, never message content.\n\n**Key scope:** `agents:run` (Run agents).", "x-yekar-key-scope": "agents:run", "parameters": [ { "name": "q", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 200 } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, { "name": "agentId", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } } ], "responses": { "200": { "description": "One page of conversations and the total.", "content": { "application/json": { "schema": { "type": "object", "properties": { "conversations": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "string" }, "agentId": { "type": [ "string", "null" ] }, "agentName": { "type": "string" }, "createdAt": { "type": "string" }, "lastMessageAt": { "type": [ "string", "null" ] } }, "required": [ "id", "title", "status", "agentId", "agentName", "createdAt", "lastMessageAt" ], "additionalProperties": false } }, "total": { "type": "number" } }, "required": [ "conversations", "total" ], "additionalProperties": false } } } }, "404": { "description": "Not found: the key is missing, invalid or lacks the scope, or the target does not exist or is in another organization.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Too many requests from this key or address (`RATE_LIMITED`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "personalApiKey": [] } ] } }, "/agents/sessions/{sessionId}": { "get": { "operationId": "readAgentSession", "tags": [ "Agents" ], "summary": "Read a conversation", "description": "The session's transcript and state as the key's owner may see it: status, the latest 100 messages with `messagesTotal`, pending approval, and `canParticipate` / `canManage` / `readOnlyReason` for this caller.\n\nA missing or invalid key, a key without the required scope, an unknown id or an id in another organization all return the same `404 NOT_FOUND`.\n\n**Key scope:** `agents:run` (Run agents).", "x-yekar-key-scope": "agents:run", "parameters": [ { "name": "sessionId", "in": "path", "required": true, "description": "The session id returned when the conversation started.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The session detail. The full shape is documented on the API reference page (Personal-key Agent conversations)." }, "404": { "description": "Not found: the key is missing, invalid or lacks the scope, or the target does not exist or is in another organization.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Too many requests from this key or address (`RATE_LIMITED`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "personalApiKey": [] } ] } }, "/agents/sessions/{sessionId}/messages": { "post": { "operationId": "postAgentMessage", "tags": [ "Agents" ], "summary": "Send a message", "description": "Append a message to a conversation the key's owner may take part in and queue the next turn. Caller credentials sent here belong to this turn only.\n\nA visible conversation the owner cannot drive returns `403 SESSION_NOT_DRIVABLE`. A missing or invalid key, a key without the required scope, an unknown id or an id in another organization all return the same `404 NOT_FOUND`.\n\n**Key scope:** `agents:run` (Run agents).", "x-yekar-key-scope": "agents:run", "parameters": [ { "name": "sessionId", "in": "path", "required": true, "description": "The session id.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "minLength": 1, "maxLength": 8000 }, "callerCredentials": { "type": "object", "properties": { "integrations": { "type": "object", "propertyNames": { "type": "string", "minLength": 1, "maxLength": 64 }, "additionalProperties": { "type": "object", "properties": { "token": { "type": "string", "minLength": 1, "maxLength": 8192, "pattern": "^[^\\r\\n]+$" }, "fields": { "type": "object", "propertyNames": { "type": "string", "pattern": "^[A-Za-z0-9_]{1,64}$" }, "additionalProperties": { "type": "string", "minLength": 1, "maxLength": 8192, "pattern": "^[^\\r\\n]+$" } }, "refresh": { "type": "object", "properties": { "refreshToken": { "type": "string", "minLength": 1, "maxLength": 8192, "pattern": "^[^\\r\\n]+$" }, "clientId": { "type": "string", "minLength": 1, "maxLength": 512 }, "clientSecret": { "type": "string", "minLength": 1, "maxLength": 8192, "pattern": "^[^\\r\\n]+$" }, "tokenUrl": { "type": "string", "maxLength": 2048, "format": "uri" }, "authMethod": { "type": "string", "enum": [ "client_secret_basic", "client_secret_post" ] } }, "required": [ "refreshToken" ], "additionalProperties": false }, "fallbackAllowed": { "type": "boolean" } }, "additionalProperties": false } } }, "required": [ "integrations" ], "additionalProperties": false } }, "required": [ "message" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "The execution queued for this turn.", "content": { "application/json": { "schema": { "type": "object", "properties": { "executionId": { "type": "string" } }, "additionalProperties": false } } } }, "400": { "description": "The body is invalid - an unknown field, a missing one or a bad value (`VALIDATION`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found: the key is missing, invalid or lacks the scope, or the target does not exist or is in another organization.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Too many requests from this key or address (`RATE_LIMITED`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "personalApiKey": [] } ] } }, "/agents/sessions/{sessionId}/turn-approval": { "post": { "operationId": "approveAgentTurn", "tags": [ "Agents" ], "summary": "Approve or reject a paused action", "description": "Resolve an approval the event stream reported (`turn.suspended`). The key's owner must be allowed to decide it: the credential owner for a call on someone's own account, otherwise an approver under the domain's approval policy; a confirmation the agent asked for is answered only by the person who started the turn.\n\n`editedArgs` amends the pending call before approving it; `rememberForSession` approves the tool for the rest of the conversation (confirmations only). An approved decision queues the turn to resume; it does not wait for the call to finish.\n\nA visible conversation the owner cannot decide returns `403 FORBIDDEN`. A missing or invalid key, a key without the required scope, an unknown id or an id in another organization all return the same `404 NOT_FOUND`.\n\n**Key scope:** `agents:run` (Run agents).", "x-yekar-key-scope": "agents:run", "parameters": [ { "name": "sessionId", "in": "path", "required": true, "description": "The session id.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "approvalId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "decision": { "type": "string", "enum": [ "approved", "rejected" ] }, "comment": { "type": "string", "maxLength": 2000 }, "callerCredentials": { "type": "object", "properties": { "integrations": { "type": "object", "propertyNames": { "type": "string", "minLength": 1, "maxLength": 64 }, "additionalProperties": { "type": "object", "properties": { "token": { "type": "string", "minLength": 1, "maxLength": 8192, "pattern": "^[^\\r\\n]+$" }, "fields": { "type": "object", "propertyNames": { "type": "string", "pattern": "^[A-Za-z0-9_]{1,64}$" }, "additionalProperties": { "type": "string", "minLength": 1, "maxLength": 8192, "pattern": "^[^\\r\\n]+$" } }, "refresh": { "type": "object", "properties": { "refreshToken": { "type": "string", "minLength": 1, "maxLength": 8192, "pattern": "^[^\\r\\n]+$" }, "clientId": { "type": "string", "minLength": 1, "maxLength": 512 }, "clientSecret": { "type": "string", "minLength": 1, "maxLength": 8192, "pattern": "^[^\\r\\n]+$" }, "tokenUrl": { "type": "string", "maxLength": 2048, "format": "uri" }, "authMethod": { "type": "string", "enum": [ "client_secret_basic", "client_secret_post" ] } }, "required": [ "refreshToken" ], "additionalProperties": false }, "fallbackAllowed": { "type": "boolean" } }, "additionalProperties": false } } }, "required": [ "integrations" ], "additionalProperties": false }, "rememberForSession": { "type": "boolean" }, "editedArgs": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "decision" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "`{ ok: true, approvalId, decision }`." }, "400": { "description": "The body is invalid - an unknown field, a missing one or a bad value (`VALIDATION`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found: the key is missing, invalid or lacks the scope, or the target does not exist or is in another organization.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Too many requests from this key or address (`RATE_LIMITED`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "personalApiKey": [] } ] } }, "/agents/sessions/{sessionId}/stream": { "get": { "operationId": "streamAgentSession", "tags": [ "Agents" ], "summary": "Follow a conversation live", "description": "Server-Sent Events for one conversation: a `snapshot` first, then `turn.started`, `message.delta`, `tool_call.started`, `tool_call.finished`, `turn.suspended` (carrying the approval to decide), `turn.completed`, `session.changed` and the rest, with a heartbeat comment every 25 seconds. Reading the stream needs visibility, not participation.\n\nA missing or invalid key, a key without the required scope, an unknown id or an id in another organization all return the same `404 NOT_FOUND`.\n\n**Key scope:** `agents:run` (Run agents).", "x-yekar-key-scope": "agents:run", "parameters": [ { "name": "sessionId", "in": "path", "required": true, "description": "The session id.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "An event stream. Each `data:` frame is a JSON envelope with `sessionId`, `seq`, `ts` and `event`.", "content": { "text/event-stream": { "schema": { "type": "string" } } } }, "404": { "description": "Not found: the key is missing, invalid or lacks the scope, or the target does not exist or is in another organization.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Too many requests from this key or address (`RATE_LIMITED`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "personalApiKey": [] } ] } }, "/mcp": { "post": { "operationId": "mcpRpc", "tags": [ "MCP" ], "summary": "MCP server (Streamable HTTP)", "description": "Your published agents as tools for any assistant that speaks the Model Context Protocol. One endpoint carries every JSON-RPC method in its body (`initialize`, `tools/list`, `tools/call`, …). A notification gets `202` with no body.\n\nA missing or invalid key, a key without the required scope, an unknown id or an id in another organization all return the same `404 NOT_FOUND`.\n\n**Key scope:** `mcp` (MCP server).", "x-yekar-key-scope": "mcp", "requestBody": { "required": true, "description": "A JSON-RPC 2.0 request or notification.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "responses": { "200": { "description": "The JSON-RPC response object." }, "400": { "description": "The body is invalid - an unknown field, a missing one or a bad value (`VALIDATION`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found: the key is missing, invalid or lacks the scope, or the target does not exist or is in another organization.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Too many requests from this key or address (`RATE_LIMITED`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "personalApiKey": [] } ] } }, "/authoring/domains": { "get": { "operationId": "listDomains", "tags": [ "Agent authoring" ], "summary": "List domains", "description": "The domains the caller belongs to - every domain for an organization admin. A domain owns agents, knowledge and connections; creating an agent needs one.\n\n**Key scope:** `authoring` (Build agents, integrations and knowledge).", "x-yekar-key-scope": "authoring", "parameters": [ { "name": "q", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 200 } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } } ], "responses": { "200": { "description": "One page of domains and the total.", "content": { "application/json": { "schema": { "type": "object", "properties": { "domains": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "description": { "type": [ "string", "null" ] } }, "required": [ "id", "name", "description" ], "additionalProperties": false } }, "total": { "type": "number" } }, "required": [ "domains", "total" ], "additionalProperties": false } } } }, "404": { "description": "Not found: the key is missing, invalid or lacks the scope, or the target does not exist or is in another organization.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Too many requests from this key or address (`RATE_LIMITED`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "personalApiKey": [] }, { "userAccessToken": [] } ] } }, "/authoring/automations": { "get": { "operationId": "listAgents", "tags": [ "Agent authoring" ], "summary": "List agents", "description": "The agents in the caller's domains, published or not. `status: active` keeps only agents that can run; `domainId` narrows to one domain.\n\n**Key scope:** `authoring` (Build agents, integrations and knowledge).", "x-yekar-key-scope": "authoring", "parameters": [ { "name": "q", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 200 } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, { "name": "domainId", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "draft", "active", "archived" ] } } ], "responses": { "200": { "description": "One page of agents and the total.", "content": { "application/json": { "schema": { "type": "object", "properties": { "agents": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "domainId": { "type": "string" }, "domainName": { "type": "string" }, "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "published": { "type": "boolean" }, "publishedRevision": { "type": [ "number", "null" ] }, "archived": { "type": "boolean" } }, "required": [ "id", "domainId", "domainName", "name", "description", "published", "publishedRevision", "archived" ], "additionalProperties": false } }, "total": { "type": "number" } }, "required": [ "agents", "total" ], "additionalProperties": false } } } }, "404": { "description": "Not found: the key is missing, invalid or lacks the scope, or the target does not exist or is in another organization.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Too many requests from this key or address (`RATE_LIMITED`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "personalApiKey": [] }, { "userAccessToken": [] } ] }, "post": { "operationId": "createAgent", "tags": [ "Agent authoring" ], "summary": "Create an agent", "description": "Create a draft agent in a domain the caller may edit agents in, optionally with its first Setup. The agent is not published until you publish it.\n\n**Key scope:** `authoring` (Build agents, integrations and knowledge).", "x-yekar-key-scope": "authoring", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "domainId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "description": { "type": "string", "maxLength": 2000 }, "initialSetup": { "type": "object", "properties": { "principles": { "type": "string", "maxLength": 100000 }, "procedure": { "type": "string", "maxLength": 100000 }, "model": { "type": "string", "minLength": 1 }, "confirmTools": { "maxItems": 50, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 100 } } }, "additionalProperties": false } }, "required": [ "domainId", "name" ], "additionalProperties": false } } } }, "responses": { "201": { "description": "Created. The new agent.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "domainId": { "type": "string" }, "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "kind": { "type": "string", "const": "agent" } }, "required": [ "id", "domainId", "name", "description", "kind" ], "additionalProperties": false } } } }, "400": { "description": "The body is invalid - an unknown field, a missing one or a bad value (`VALIDATION`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found: the key is missing, invalid or lacks the scope, or the target does not exist or is in another organization.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Too many requests from this key or address (`RATE_LIMITED`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "personalApiKey": [] }, { "userAccessToken": [] } ] } }, "/authoring/automations/{id}/setup": { "patch": { "operationId": "updateAgentSetup", "tags": [ "Agent authoring" ], "summary": "Edit an agent's draft Setup", "description": "Change the draft's principles, procedure, model or the tools that ask for confirmation. Edits land on the draft only; publish to make them run.\n\n**Key scope:** `authoring` (Build agents, integrations and knowledge).", "x-yekar-key-scope": "authoring", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The agent's id.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "principles": { "type": "string", "maxLength": 100000 }, "procedure": { "type": "string", "maxLength": 100000 }, "model": { "type": "string", "minLength": 1 }, "confirmTools": { "maxItems": 50, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 100 } } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "`{ setup }` - the draft after the edit." }, "400": { "description": "The body is invalid - an unknown field, a missing one or a bad value (`VALIDATION`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found: the key is missing, invalid or lacks the scope, or the target does not exist or is in another organization.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Too many requests from this key or address (`RATE_LIMITED`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "personalApiKey": [] }, { "userAccessToken": [] } ] } }, "/authoring/automations/{id}/verify": { "get": { "operationId": "verifyAgentSetup", "tags": [ "Agent authoring" ], "summary": "Check a draft before publishing", "description": "The findings publishing would raise for the current draft - unknown tool references, missing integrations and the like.\n\n**Key scope:** `authoring` (Build agents, integrations and knowledge).", "x-yekar-key-scope": "authoring", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The agent's id.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The verification findings for the draft." }, "404": { "description": "Not found: the key is missing, invalid or lacks the scope, or the target does not exist or is in another organization.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Too many requests from this key or address (`RATE_LIMITED`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "personalApiKey": [] }, { "userAccessToken": [] } ] } }, "/authoring/automations/{id}/publish": { "post": { "operationId": "publishAgentSetup", "tags": [ "Agent authoring" ], "summary": "Publish an agent's draft", "description": "Make the draft the version that runs. Refused with `422` while the draft has blocking findings; the response names the new revision and the tools it will run with. `procedureMode` chooses how the Procedure runs - `free_text` or `structured` - and omitting it keeps the mode the draft already has.\n\n**Key scope:** `authoring` (Build agents, integrations and knowledge).", "x-yekar-key-scope": "authoring", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The agent's id.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "changeNote": { "type": "string", "maxLength": 2000 }, "procedureMode": { "type": "string", "enum": [ "free_text", "structured" ] } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "`{ revision, belt }` - the published revision number and the integrations it is bound to." }, "400": { "description": "The body is invalid - an unknown field, a missing one or a bad value (`VALIDATION`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found: the key is missing, invalid or lacks the scope, or the target does not exist or is in another organization.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Too many requests from this key or address (`RATE_LIMITED`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "personalApiKey": [] }, { "userAccessToken": [] } ] } }, "/authoring/automations/{id}/knowledge-selection": { "put": { "operationId": "setAgentKnowledgeSelection", "tags": [ "Agent authoring" ], "summary": "Choose what knowledge an agent reads", "description": "Nothing, the whole organization library, the agent's domain, or named knowledge modules. Applies on the agent's next turn.\n\n**Key scope:** `authoring` (Build agents, integrations and knowledge).", "x-yekar-key-scope": "authoring", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The agent's id.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "none", "org", "domain", "modules" ] }, "moduleIds": { "maxItems": 100, "type": "array", "items": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } } }, "required": [ "mode" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "The selection as saved." }, "400": { "description": "The body is invalid - an unknown field, a missing one or a bad value (`VALIDATION`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found: the key is missing, invalid or lacks the scope, or the target does not exist or is in another organization.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Too many requests from this key or address (`RATE_LIMITED`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "personalApiKey": [] }, { "userAccessToken": [] } ] } }, "/authoring/automations/{id}/triggers": { "get": { "operationId": "listAgentTriggers", "tags": [ "Agent authoring" ], "summary": "List an agent's triggers", "description": "The schedules, API triggers and event triggers subscribed to this agent.\n\n**Key scope:** `authoring` (Build agents, integrations and knowledge).", "x-yekar-key-scope": "authoring", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The agent's id.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The agent's triggers.", "content": { "application/json": { "schema": { "type": "object", "properties": { "triggers": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "type": { "type": "string", "enum": [ "schedule", "api", "event" ] }, "status": { "type": "string", "enum": [ "active", "disabled" ] }, "cron": { "type": [ "string", "null" ] }, "timezone": { "type": [ "string", "null" ] }, "input": { "anyOf": [ { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, { "type": "null" } ] }, "event": {}, "eventFilter": { "anyOf": [ { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, { "type": "null" } ] } }, "required": [ "id", "name", "type", "status", "cron", "timezone", "input", "eventFilter" ], "additionalProperties": false } } }, "required": [ "triggers" ], "additionalProperties": false } } } }, "404": { "description": "Not found: the key is missing, invalid or lacks the scope, or the target does not exist or is in another organization.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Too many requests from this key or address (`RATE_LIMITED`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "personalApiKey": [] }, { "userAccessToken": [] } ] }, "post": { "operationId": "createAgentTrigger", "tags": [ "Agent authoring" ], "summary": "Add a trigger to an agent", "description": "Create a schedule, API or event trigger subscribed to this agent. New triggers start switched off; switch one on from the product once the agent is published.\n\n**Key scope:** `authoring` (Build agents, integrations and knowledge).", "x-yekar-key-scope": "authoring", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The agent's id.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "schedule" }, "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "cron": { "type": "string", "minLength": 1 }, "timezone": { "type": "string", "minLength": 1 }, "input": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "type", "name", "cron" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "api" }, "name": { "type": "string", "minLength": 1, "maxLength": 120 } }, "required": [ "type", "name" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "event" }, "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "sourceIntegrationId": { "type": "string", "minLength": 1, "maxLength": 200 }, "connectionId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "eventType": { "type": "string", "minLength": 1, "maxLength": 200 }, "endpointSecret": { "type": "string", "minLength": 16, "maxLength": 500 }, "registerWithProvider": { "type": "boolean" }, "eventFilter": { "type": "object", "properties": { "field": { "type": "string", "minLength": 1 }, "operator": { "type": "string", "enum": [ "equals", "not-equals", ">", "<", "contains", "in" ] }, "value": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "maxItems": 50, "type": "array", "items": { "type": [ "string", "number", "boolean" ] } } ] } }, "required": [ "field", "operator", "value" ], "additionalProperties": false } }, "required": [ "type", "name", "sourceIntegrationId", "eventType" ], "additionalProperties": false } ] } } } }, "responses": { "201": { "description": "Created. The new trigger.", "content": { "application/json": { "schema": { "type": "object", "properties": { "trigger": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "type": { "type": "string", "enum": [ "schedule", "api", "event" ] }, "status": { "type": "string", "enum": [ "active", "disabled" ] }, "cron": { "type": [ "string", "null" ] }, "timezone": { "type": [ "string", "null" ] }, "input": { "anyOf": [ { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, { "type": "null" } ] }, "event": {}, "eventFilter": { "anyOf": [ { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, { "type": "null" } ] } }, "required": [ "id", "name", "type", "status", "cron", "timezone", "input", "eventFilter" ], "additionalProperties": false } }, "required": [ "trigger" ], "additionalProperties": false } } } }, "400": { "description": "The body is invalid - an unknown field, a missing one or a bad value (`VALIDATION`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found: the key is missing, invalid or lacks the scope, or the target does not exist or is in another organization.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Too many requests from this key or address (`RATE_LIMITED`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "personalApiKey": [] }, { "userAccessToken": [] } ] } }, "/authoring/automations/{id}/triggers/{triggerId}": { "patch": { "operationId": "updateAgentTrigger", "tags": [ "Agent authoring" ], "summary": "Edit one of an agent's triggers", "description": "Change a trigger's name and the fields of its kind (schedule: cron, timezone, input; event: connection, event type, filter). The body must match the trigger's kind; a field of another kind is a `400`.\n\n**Key scope:** `authoring` (Build agents, integrations and knowledge).", "x-yekar-key-scope": "authoring", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The agent's id.", "schema": { "type": "string" } }, { "name": "triggerId", "in": "path", "required": true, "description": "The trigger's id.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "cron": { "type": "string", "minLength": 1 }, "timezone": { "type": "string", "minLength": 1 }, "input": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "additionalProperties": false }, { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 120 } }, "additionalProperties": false }, { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "connectionId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "eventType": { "type": "string", "minLength": 1, "maxLength": 200 }, "eventFilter": { "anyOf": [ { "type": "object", "properties": { "field": { "type": "string", "minLength": 1 }, "operator": { "type": "string", "enum": [ "equals", "not-equals", ">", "<", "contains", "in" ] }, "value": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "maxItems": 50, "type": "array", "items": { "type": [ "string", "number", "boolean" ] } } ] } }, "required": [ "field", "operator", "value" ], "additionalProperties": false }, { "type": "null" } ] } }, "additionalProperties": false } ] } } } }, "responses": { "200": { "description": "The trigger after the edit.", "content": { "application/json": { "schema": { "type": "object", "properties": { "trigger": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "type": { "type": "string", "enum": [ "schedule", "api", "event" ] }, "status": { "type": "string", "enum": [ "active", "disabled" ] }, "cron": { "type": [ "string", "null" ] }, "timezone": { "type": [ "string", "null" ] }, "input": { "anyOf": [ { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, { "type": "null" } ] }, "event": {}, "eventFilter": { "anyOf": [ { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, { "type": "null" } ] } }, "required": [ "id", "name", "type", "status", "cron", "timezone", "input", "eventFilter" ], "additionalProperties": false } }, "required": [ "trigger" ], "additionalProperties": false } } } }, "400": { "description": "The body is invalid - an unknown field, a missing one or a bad value (`VALIDATION`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found: the key is missing, invalid or lacks the scope, or the target does not exist or is in another organization.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Too many requests from this key or address (`RATE_LIMITED`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "personalApiKey": [] }, { "userAccessToken": [] } ] }, "delete": { "operationId": "deleteAgentTrigger", "tags": [ "Agent authoring" ], "summary": "Remove one of an agent's triggers", "description": "Delete a trigger subscribed to this agent.\n\n**Key scope:** `authoring` (Build agents, integrations and knowledge).", "x-yekar-key-scope": "authoring", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The agent's id.", "schema": { "type": "string" } }, { "name": "triggerId", "in": "path", "required": true, "description": "The trigger's id.", "schema": { "type": "string" } } ], "responses": { "204": { "description": "Deleted; no body." }, "404": { "description": "Not found: the key is missing, invalid or lacks the scope, or the target does not exist or is in another organization.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Too many requests from this key or address (`RATE_LIMITED`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "personalApiKey": [] }, { "userAccessToken": [] } ] } }, "/authoring/integrations": { "get": { "operationId": "searchIntegrations", "tags": [ "Integrations" ], "summary": "Search integrations", "description": "The integrations available to the caller's organization, with their tools. `q` matches ids, names and descriptions of integrations and tools; at most 50 are returned.\n\n**Key scope:** `authoring` (Build agents, integrations and knowledge).", "x-yekar-key-scope": "authoring", "parameters": [ { "name": "q", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 200 } } ], "responses": { "200": { "description": "The matching integrations.", "content": { "application/json": { "schema": { "type": "object", "properties": { "integrations": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "tools": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "reference": { "type": "string" }, "description": { "type": "string" }, "isReadonly": { "type": "boolean" } }, "required": [ "name", "reference", "description", "isReadonly" ], "additionalProperties": false } }, "eventTypes": { "type": "array", "items": { "type": "string" } } }, "required": [ "id", "name", "description", "tools", "eventTypes" ], "additionalProperties": false } } }, "required": [ "integrations" ], "additionalProperties": false } } } }, "404": { "description": "Not found: the key is missing, invalid or lacks the scope, or the target does not exist or is in another organization.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Too many requests from this key or address (`RATE_LIMITED`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "personalApiKey": [] }, { "userAccessToken": [] } ] } }, "/authoring/integrations/{id}/connections": { "get": { "operationId": "listIntegrationConnections", "tags": [ "Integrations" ], "summary": "List an integration's usable connections", "description": "The connections of this integration an event trigger may be created on.\n\n**Key scope:** `authoring` (Build agents, integrations and knowledge).", "x-yekar-key-scope": "authoring", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The integration id, such as `yekar.gmail`.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The connections.", "content": { "application/json": { "schema": { "type": "object", "properties": { "connections": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "name" ], "additionalProperties": false } } }, "required": [ "connections" ], "additionalProperties": false } } } }, "404": { "description": "Not found: the key is missing, invalid or lacks the scope, or the target does not exist or is in another organization.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Too many requests from this key or address (`RATE_LIMITED`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "personalApiKey": [] }, { "userAccessToken": [] } ] } }, "/authoring/integrations/{id}": { "get": { "operationId": "readIntegration", "tags": [ "Integrations" ], "summary": "Read an integration", "description": "One integration with each tool's input schema and the events it can fire a trigger on.\n\n**Key scope:** `authoring` (Build agents, integrations and knowledge).", "x-yekar-key-scope": "authoring", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The integration id, such as `yekar.gmail`.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The integration.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "tools": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "reference": { "type": "string" }, "description": { "type": "string" }, "isReadonly": { "type": "boolean" }, "inputSchema": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "name", "reference", "description", "isReadonly", "inputSchema" ], "additionalProperties": false } }, "events": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "schemaVersion": { "type": "number" }, "filterablePaths": { "type": "array", "items": { "type": "string" } } }, "required": [ "type", "name", "description", "schemaVersion", "filterablePaths" ], "additionalProperties": false } } }, "required": [ "id", "name", "description", "tools", "events" ], "additionalProperties": false } } } }, "404": { "description": "Not found: the key is missing, invalid or lacks the scope, or the target does not exist or is in another organization.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Too many requests from this key or address (`RATE_LIMITED`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "personalApiKey": [] }, { "userAccessToken": [] } ] } }, "/authoring/knowledge-bases": { "get": { "operationId": "listKnowledgeBases", "tags": [ "Knowledge" ], "summary": "List knowledge bases", "description": "The knowledge bases the caller can see: those of their domains and the organization-wide ones. New articles are written into a base.\n\n**Key scope:** `authoring` (Build agents, integrations and knowledge).", "x-yekar-key-scope": "authoring", "parameters": [ { "name": "q", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 200 } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, { "name": "domainId", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } } ], "responses": { "200": { "description": "One page of knowledge bases and the total.", "content": { "application/json": { "schema": { "type": "object", "properties": { "knowledgeBases": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "domainId": { "type": [ "string", "null" ] } }, "required": [ "id", "name", "description", "domainId" ], "additionalProperties": false } }, "total": { "type": "number" } }, "required": [ "knowledgeBases", "total" ], "additionalProperties": false } } } }, "404": { "description": "Not found: the key is missing, invalid or lacks the scope, or the target does not exist or is in another organization.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Too many requests from this key or address (`RATE_LIMITED`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "personalApiKey": [] }, { "userAccessToken": [] } ] } }, "/authoring/knowledge-modules": { "get": { "operationId": "listKnowledgeModules", "tags": [ "Knowledge" ], "summary": "List a domain's knowledge modules", "description": "The knowledge modules of one domain the caller may view.\n\n**Key scope:** `authoring` (Build agents, integrations and knowledge).", "x-yekar-key-scope": "authoring", "parameters": [ { "name": "domainId", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } } ], "responses": { "200": { "description": "The modules.", "content": { "application/json": { "schema": { "type": "object", "properties": { "modules": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "kind": { "type": "string", "enum": [ "domain", "org", "platform" ] } }, "required": [ "id", "name", "description", "kind" ], "additionalProperties": false } } }, "required": [ "modules" ], "additionalProperties": false } } } }, "404": { "description": "Not found: the key is missing, invalid or lacks the scope, or the target does not exist or is in another organization.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Too many requests from this key or address (`RATE_LIMITED`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "personalApiKey": [] }, { "userAccessToken": [] } ] }, "post": { "operationId": "createKnowledgeModule", "tags": [ "Knowledge" ], "summary": "Create a knowledge module", "description": "A named set of articles an agent can be pointed at. A domain module needs `domainId`.\n\n**Key scope:** `authoring` (Build agents, integrations and knowledge).", "x-yekar-key-scope": "authoring", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "domain", "org" ] }, "domainId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": { "type": "string", "maxLength": 10000 } }, "required": [ "kind", "name" ], "additionalProperties": false } } } }, "responses": { "201": { "description": "Created. The module." }, "400": { "description": "The body is invalid - an unknown field, a missing one or a bad value (`VALIDATION`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found: the key is missing, invalid or lacks the scope, or the target does not exist or is in another organization.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Too many requests from this key or address (`RATE_LIMITED`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "personalApiKey": [] }, { "userAccessToken": [] } ] } }, "/authoring/knowledge-bases/{baseId}/articles": { "post": { "operationId": "createKnowledgeArticle", "tags": [ "Knowledge" ], "summary": "Create a draft article", "description": "A new article in a knowledge base, as a draft. Publish it from the product when it is ready.\n\n**Key scope:** `authoring` (Build agents, integrations and knowledge).", "x-yekar-key-scope": "authoring", "parameters": [ { "name": "baseId", "in": "path", "required": true, "description": "The knowledge base's id.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 240 }, "draftBody": { "anyOf": [ { "type": "string", "maxLength": 2000000 }, { "type": "null" } ] } }, "required": [ "title" ], "additionalProperties": false } } } }, "responses": { "201": { "description": "Created. The article." }, "400": { "description": "The body is invalid - an unknown field, a missing one or a bad value (`VALIDATION`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found: the key is missing, invalid or lacks the scope, or the target does not exist or is in another organization.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Too many requests from this key or address (`RATE_LIMITED`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "personalApiKey": [] }, { "userAccessToken": [] } ] } }, "/authoring/knowledge-modules/{moduleId}/articles": { "post": { "operationId": "addKnowledgeModuleArticle", "tags": [ "Knowledge" ], "summary": "Add an article to a module", "description": "Reference an existing article from a knowledge module.\n\n**Key scope:** `authoring` (Build agents, integrations and knowledge).", "x-yekar-key-scope": "authoring", "parameters": [ { "name": "moduleId", "in": "path", "required": true, "description": "The module's id.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "articleId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "articleId" ], "additionalProperties": false } } } }, "responses": { "201": { "description": "Created. The module membership." }, "400": { "description": "The body is invalid - an unknown field, a missing one or a bad value (`VALIDATION`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found: the key is missing, invalid or lacks the scope, or the target does not exist or is in another organization.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Too many requests from this key or address (`RATE_LIMITED`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "personalApiKey": [] }, { "userAccessToken": [] } ] } }, "/authoring/automations/{id}/eval-cases": { "post": { "operationId": "createAgentEvalCase", "tags": [ "Agent authoring" ], "summary": "Add a simulated test to an agent", "description": "A conversation the agent will be tested on, with the tool results it will receive and the checks that decide it. Nothing it tests ever runs for real: every tool call is answered from the script, and a call the script does not cover is refused unexecuted.\n\n**Key scope:** `authoring` (Build agents, integrations and knowledge).", "x-yekar-key-scope": "authoring", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The agent's id.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "note": { "type": "string", "maxLength": 2000 }, "turns": { "type": "array", "minItems": 1, "maxItems": 10, "items": { "type": "string", "minLength": 1, "maxLength": 20000 }, "description": "What the person says, turn by turn." }, "script": { "type": "array", "maxItems": 50, "items": { "type": "object", "properties": { "tool": { "type": "string", "minLength": 1, "maxLength": 200, "description": "The tool's name as the agent calls it." }, "response": { "description": "What the tool answers with." }, "failed": { "type": "boolean", "description": "Answer as a failure - an expired sign-in, a rate limit." } }, "required": [ "tool", "response" ], "additionalProperties": false }, "description": "What each tool answers, consumed in order per tool." }, "holdout": { "type": "boolean", "description": "Keep the case's contents out of what this API returns, so a fix cannot be fitted to it." }, "assertions": { "type": "array", "minItems": 1, "maxItems": 20, "items": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "reply_contains", "reply_omits", "tool_called", "tool_not_called", "tool_precedes", "no_divergence", "token_ceiling", "round_budget", "tool_called_with", "tool_call_count" ] }, "value": { "type": "string", "maxLength": 2000, "description": "Kind-specific: a literal, a tool name, `a|b` for tool_precedes, `tool|/json/pointer|expected` for tool_called_with, `tool|n` for tool_call_count, or a number." }, "label": { "type": "string", "minLength": 1, "maxLength": 200, "description": "The success criterion in the person's words; what the pass/fail line says." } }, "required": [ "kind", "label" ], "additionalProperties": false } } }, "required": [ "name", "turns", "assertions" ], "additionalProperties": false } } } }, "responses": { "201": { "description": "The new case's id.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" } }, "required": [ "id" ], "additionalProperties": false } } } }, "400": { "description": "The body is invalid - an unknown field, a missing one or a bad value (`VALIDATION`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found: the key is missing, invalid or lacks the scope, or the target does not exist or is in another organization.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Too many requests from this key or address (`RATE_LIMITED`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "personalApiKey": [] }, { "userAccessToken": [] } ] }, "get": { "operationId": "listAgentEvalCases", "tags": [ "Agent authoring" ], "summary": "List an agent's tests", "description": "Every case the agent is tested on, with its turns, script and checks. A held-out case is listed by name only.\n\n**Key scope:** `authoring` (Build agents, integrations and knowledge).", "x-yekar-key-scope": "authoring", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The agent's id.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The agent's cases." }, "404": { "description": "Not found: the key is missing, invalid or lacks the scope, or the target does not exist or is in another organization.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Too many requests from this key or address (`RATE_LIMITED`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "personalApiKey": [] }, { "userAccessToken": [] } ] } }, "/authoring/automations/{id}/eval-cases/{caseId}": { "delete": { "operationId": "deleteAgentEvalCase", "tags": [ "Agent authoring" ], "summary": "Remove a test the Builder wrote", "description": "Delete a case this API created. A case a person wrote cannot be removed here.\n\n**Key scope:** `authoring` (Build agents, integrations and knowledge).", "x-yekar-key-scope": "authoring", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The agent's id.", "schema": { "type": "string" } }, { "name": "caseId", "in": "path", "required": true, "description": "The case's id.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Deleted." }, "404": { "description": "Not found: the key is missing, invalid or lacks the scope, or the target does not exist or is in another organization.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Too many requests from this key or address (`RATE_LIMITED`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "personalApiKey": [] }, { "userAccessToken": [] } ] } }, "/authoring/automations/{id}/eval-suites": { "post": { "operationId": "startAgentEvalSuite", "tags": [ "Agent authoring" ], "summary": "Test an agent's draft", "description": "Run every case against the agent's saved draft. Each case runs `repeat` times (1-5); a case passes only when every run passes. Runs spend model tokens like any turn.\n\n**Key scope:** `authoring` (Build agents, integrations and knowledge).", "x-yekar-key-scope": "authoring", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The agent's id.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "repeat": { "type": "integer", "minimum": 1, "maximum": 5 } }, "additionalProperties": false } } } }, "responses": { "202": { "description": "The suite's id and how many runs it started.", "content": { "application/json": { "schema": { "type": "object", "properties": { "suiteRunId": { "type": "string" }, "runs": { "type": "integer" } }, "required": [ "suiteRunId", "runs" ], "additionalProperties": false } } } }, "400": { "description": "The body is invalid - an unknown field, a missing one or a bad value (`VALIDATION`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found: the key is missing, invalid or lacks the scope, or the target does not exist or is in another organization.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Too many requests from this key or address (`RATE_LIMITED`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "personalApiKey": [] }, { "userAccessToken": [] } ] } }, "/authoring/automations/{id}/eval-suites/{suiteId}": { "get": { "operationId": "readAgentEvalSuite", "tags": [ "Agent authoring" ], "summary": "Read a test run's results", "description": "Each case's standing - pass, fail, error, unscored or still running - with the failed checks and the failing conversation. A held-out case reports its standing only. Waits up to `waitSeconds` (at most 45) for the suite to finish.\n\n**Key scope:** `authoring` (Build agents, integrations and knowledge).", "x-yekar-key-scope": "authoring", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The agent's id.", "schema": { "type": "string" } }, { "name": "suiteId", "in": "path", "required": true, "description": "The suite's id, from startAgentEvalSuite.", "schema": { "type": "string" } }, { "name": "waitSeconds", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "maximum": 45 } } ], "responses": { "200": { "description": "The suite's results by case." }, "404": { "description": "Not found: the key is missing, invalid or lacks the scope, or the target does not exist or is in another organization.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Too many requests from this key or address (`RATE_LIMITED`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "personalApiKey": [] }, { "userAccessToken": [] } ] } } }, "components": { "securitySchemes": { "personalApiKey": { "type": "http", "scheme": "bearer", "description": "A personal API key (`yk_…`) from Settings → API keys. It acts with its owner's authority and only through the scopes it was created with." }, "userAccessToken": { "type": "http", "scheme": "bearer", "description": "A short-lived user access token (`yku_…`) minted from a signed-in session with `POST /api/v1/auth/token`; accepted by the authoring routes only." } }, "schemas": { "ErrorEnvelope": { "type": "object", "description": "Every error answers this one envelope. `code` is stable and documented on the Errors page; `message` is for people; `details` is present only for validation errors.", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }