OpenAPI document

Everything your own software can call with a personal API key is described in one OpenAPI 3.1 document. It is produced from the same definitions the API validates requests with, so a field it lists is a field the server accepts, and a field it rejects is one the server rejects too.

• Download: /openapi/public-v1.json - import it into Postman, Insomnia, Stoplight or any client generator.
• From the API itself: GET https://api.yekar.ai/api/public/v1/openapi.json - the same document, with no key needed, so a self-hosted deployment serves its own.

Request bodies are strict: a field the document does not list is refused with 400 VALIDATION rather than ignored. Responses may gain fields over time, so a client should tolerate ones it does not know. Each route names the key scope that opens it; a key without that scope receives the same 404 as an unknown key.

The reference below is rendered from that document. The API reference page carries the longer explanations, event lists and examples.

Yekar.AI public API · version 1.0.0 · base URL https://api.yekar.ai/api/public/v1 · download the OpenAPI document

Specification

Read this API's OpenAPI document #

GET /openapi.json

The machine-readable description of every public route, generated from the same definitions the server validates requests with. Needs no key.

Responses

Status	Meaning
200	The OpenAPI 3.1 document.

Triggers

Fire a trigger #

POST /triggers/fire · key scope triggers:fire

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.

Send `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.

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`.

**Key scope:** `triggers:fire` (Fire triggers).

Request body

Field	Type	Required	Notes
idempotencyKey	string (pattern)	No
triggerId	string (uuid, pattern)	Yes
input	object	No
callerCredentials	object	No	Field Type Required Notes integrations object Yes
callerCredentialExpiresAt	string (date-time, pattern)	No

Responses

Status	Meaning
202	Accepted. One entry per agent or flow that started, and the subscribers that were skipped with the reason. Field Type Required Notes sessions object[] Yes Field Type Required Notes automationId string Yes sessionId string Yes skipped object[] Yes Field Type Required Notes automationId string Yes automationName string Yes reason "unpublished" | "inactive" | "integration_not_unattended" | "person_unavailable" | "worker_paused" | "cost_cap_reached" | "event_input_unpublished" | "procedure_off" | "entitlement_disabled" | "missing" Yes
400	The body is invalid - an unknown field, a missing one or a bad value (`VALIDATION`).
404	Not found: the key is missing, invalid or lacks the scope, or the target does not exist or is in another organization.
429	Too many requests from this key or address (`RATE_LIMITED`).

Agents

Start a conversation with an agent #

POST /agents/{automationId}/sessions · key scope agents:run

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.

`202` means the first turn was accepted. Follow it on the session's event stream.

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`.

**Key scope:** `agents:run` (Run agents).

Parameters

Name	In	Type	Required	Notes
automationId	path	string	Yes	The agent's id, from its page URL in the product.

Request body

Field	Type	Required	Notes
message	string	Yes
callerCredentials	object	No	Field Type Required Notes integrations object Yes

Responses

Status	Meaning
202	Accepted. The new session and its first execution. Field Type Required Notes sessionId string Yes executionId string Yes
400	The body is invalid - an unknown field, a missing one or a bad value (`VALIDATION`).
404	Not found: the key is missing, invalid or lacks the scope, or the target does not exist or is in another organization.
429	Too many requests from this key or address (`RATE_LIMITED`).

List conversations #

GET /agents/sessions · key scope agents:run

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.

**Key scope:** `agents:run` (Run agents).

Parameters

Name	In	Type	Required	Notes
q	query	string	No
limit	query	integer	No
offset	query	integer	No
agentId	query	string (uuid, pattern)	No

Responses

Status	Meaning
200	One page of conversations and the total. Field Type Required Notes conversations object[] Yes Field Type Required Notes id string Yes title string Yes status string Yes agentId string | null Yes agentName string Yes createdAt string Yes lastMessageAt string | null Yes total number Yes
404	Not found: the key is missing, invalid or lacks the scope, or the target does not exist or is in another organization.
429	Too many requests from this key or address (`RATE_LIMITED`).

Read a conversation #

GET /agents/sessions/{sessionId} · key scope agents:run

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.

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`.

**Key scope:** `agents:run` (Run agents).

Parameters

Name	In	Type	Required	Notes
sessionId	path	string	Yes	The session id returned when the conversation started.

Responses

Status	Meaning
200	The session detail. The full shape is documented on the API reference page (Personal-key Agent conversations).
404	Not found: the key is missing, invalid or lacks the scope, or the target does not exist or is in another organization.
429	Too many requests from this key or address (`RATE_LIMITED`).

Send a message #

POST /agents/sessions/{sessionId}/messages · key scope agents:run

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.

A 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`.

**Key scope:** `agents:run` (Run agents).

Parameters

Name	In	Type	Required	Notes
sessionId	path	string	Yes	The session id.

Request body

Field	Type	Required	Notes
message	string	Yes
callerCredentials	object	No	Field Type Required Notes integrations object Yes

Responses

Status	Meaning
200	The execution queued for this turn. Field Type Required Notes executionId string No
400	The body is invalid - an unknown field, a missing one or a bad value (`VALIDATION`).
404	Not found: the key is missing, invalid or lacks the scope, or the target does not exist or is in another organization.
429	Too many requests from this key or address (`RATE_LIMITED`).

Approve or reject a paused action #

POST /agents/sessions/{sessionId}/turn-approval · key scope agents:run

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.

`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.

A 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`.

**Key scope:** `agents:run` (Run agents).

Parameters

Name	In	Type	Required	Notes
sessionId	path	string	Yes	The session id.

Request body

Field	Type	Required	Notes
approvalId	string (uuid, pattern)	No
decision	"approved" | "rejected"	Yes
comment	string	No
callerCredentials	object	No	Field Type Required Notes integrations object Yes
rememberForSession	boolean	No
editedArgs	object	No

Responses

Status	Meaning
200	`{ ok: true, approvalId, decision }`.
400	The body is invalid - an unknown field, a missing one or a bad value (`VALIDATION`).
404	Not found: the key is missing, invalid or lacks the scope, or the target does not exist or is in another organization.
429	Too many requests from this key or address (`RATE_LIMITED`).

Follow a conversation live #

GET /agents/sessions/{sessionId}/stream · key scope agents:run

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.

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`.

**Key scope:** `agents:run` (Run agents).

Parameters

Name	In	Type	Required	Notes
sessionId	path	string	Yes	The session id.

Responses

Status	Meaning
200	An event stream. Each `data:` frame is a JSON envelope with `sessionId`, `seq`, `ts` and `event`.
404	Not found: the key is missing, invalid or lacks the scope, or the target does not exist or is in another organization.
429	Too many requests from this key or address (`RATE_LIMITED`).

MCP

MCP server (Streamable HTTP) #

POST /mcp · key scope mcp

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.

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`.

**Key scope:** `mcp` (MCP server).

Request body

A JSON-RPC 2.0 request or notification.

object

Responses

Status	Meaning
200	The JSON-RPC response object.
400	The body is invalid - an unknown field, a missing one or a bad value (`VALIDATION`).
404	Not found: the key is missing, invalid or lacks the scope, or the target does not exist or is in another organization.
429	Too many requests from this key or address (`RATE_LIMITED`).

Agent authoring

List domains #

GET /authoring/domains · key scope authoring

The domains the caller belongs to - every domain for an organization admin. A domain owns agents, knowledge and connections; creating an agent needs one.

**Key scope:** `authoring` (Build agents, integrations and knowledge).

Parameters

Name	In	Type	Required	Notes
q	query	string	No
limit	query	integer	No
offset	query	integer	No

Responses

Status	Meaning
200	One page of domains and the total. Field Type Required Notes domains object[] Yes Field Type Required Notes id string Yes name string Yes description string | null Yes total number Yes
404	Not found: the key is missing, invalid or lacks the scope, or the target does not exist or is in another organization.
429	Too many requests from this key or address (`RATE_LIMITED`).

List agents #

GET /authoring/automations · key scope authoring

The agents in the caller's domains, published or not. `status: active` keeps only agents that can run; `domainId` narrows to one domain.

**Key scope:** `authoring` (Build agents, integrations and knowledge).

Parameters

Name	In	Type	Required	Notes
q	query	string	No
limit	query	integer	No
offset	query	integer	No
domainId	query	string (uuid, pattern)	No
status	query	"draft" | "active" | "archived"	No

Responses

Status	Meaning
200	One page of agents and the total. Field Type Required Notes agents object[] Yes Field Type Required Notes id string Yes domainId string Yes domainName string Yes name string Yes description string | null Yes published boolean Yes publishedRevision number | null Yes archived boolean Yes total number Yes
404	Not found: the key is missing, invalid or lacks the scope, or the target does not exist or is in another organization.
429	Too many requests from this key or address (`RATE_LIMITED`).

Create an agent #

POST /authoring/automations · key scope authoring

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.

**Key scope:** `authoring` (Build agents, integrations and knowledge).

Request body

Field	Type	Required	Notes
domainId	string (uuid, pattern)	Yes
name	string	Yes
description	string	No
initialSetup	object	No	Field Type Required Notes principles string No procedure string No model string No confirmTools string[] No

Responses

Status	Meaning
201	Created. The new agent. Field Type Required Notes id string Yes domainId string Yes name string Yes description string | null Yes kind "agent" Yes
400	The body is invalid - an unknown field, a missing one or a bad value (`VALIDATION`).
404	Not found: the key is missing, invalid or lacks the scope, or the target does not exist or is in another organization.
429	Too many requests from this key or address (`RATE_LIMITED`).

Edit an agent's draft Setup #

PATCH /authoring/automations/{id}/setup · key scope authoring

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.

**Key scope:** `authoring` (Build agents, integrations and knowledge).

Parameters

Name	In	Type	Required	Notes
id	path	string	Yes	The agent's id.

Request body

Field	Type	Required	Notes
principles	string	No
procedure	string	No
model	string	No
confirmTools	string[]	No

Responses

Status	Meaning
200	`{ setup }` - the draft after the edit.
400	The body is invalid - an unknown field, a missing one or a bad value (`VALIDATION`).
404	Not found: the key is missing, invalid or lacks the scope, or the target does not exist or is in another organization.
429	Too many requests from this key or address (`RATE_LIMITED`).

Check a draft before publishing #

GET /authoring/automations/{id}/verify · key scope authoring

The findings publishing would raise for the current draft - unknown tool references, missing integrations and the like.

**Key scope:** `authoring` (Build agents, integrations and knowledge).

Parameters

Name	In	Type	Required	Notes
id	path	string	Yes	The agent's id.

Responses

Status	Meaning
200	The verification findings for the draft.
404	Not found: the key is missing, invalid or lacks the scope, or the target does not exist or is in another organization.
429	Too many requests from this key or address (`RATE_LIMITED`).

Publish an agent's draft #

POST /authoring/automations/{id}/publish · key scope authoring

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.

**Key scope:** `authoring` (Build agents, integrations and knowledge).

Parameters

Name	In	Type	Required	Notes
id	path	string	Yes	The agent's id.

Request body

Field	Type	Required	Notes
changeNote	string	No
procedureMode	"free_text" | "structured"	No

Responses

Status	Meaning
200	`{ revision, belt }` - the published revision number and the integrations it is bound to.
400	The body is invalid - an unknown field, a missing one or a bad value (`VALIDATION`).
404	Not found: the key is missing, invalid or lacks the scope, or the target does not exist or is in another organization.
429	Too many requests from this key or address (`RATE_LIMITED`).

Choose what knowledge an agent reads #

PUT /authoring/automations/{id}/knowledge-selection · key scope authoring

Nothing, the whole organization library, the agent's domain, or named knowledge modules. Applies on the agent's next turn.

**Key scope:** `authoring` (Build agents, integrations and knowledge).

Parameters

Name	In	Type	Required	Notes
id	path	string	Yes	The agent's id.

Request body

Field	Type	Required	Notes
mode	"none" | "org" | "domain" | "modules"	Yes
moduleIds	string (uuid, pattern)[]	No

Responses

Status	Meaning
200	The selection as saved.
400	The body is invalid - an unknown field, a missing one or a bad value (`VALIDATION`).
404	Not found: the key is missing, invalid or lacks the scope, or the target does not exist or is in another organization.
429	Too many requests from this key or address (`RATE_LIMITED`).

List an agent's triggers #

GET /authoring/automations/{id}/triggers · key scope authoring

The schedules, API triggers and event triggers subscribed to this agent.

**Key scope:** `authoring` (Build agents, integrations and knowledge).

Parameters

Name	In	Type	Required	Notes
id	path	string	Yes	The agent's id.

Responses

Status	Meaning
200	The agent's triggers. Field Type Required Notes triggers object[] Yes Field Type Required Notes id string Yes name string Yes type "schedule" | "api" | "event" Yes status "active" | "disabled" Yes cron string | null Yes timezone string | null Yes input object | null Yes event any No eventFilter object | null Yes
404	Not found: the key is missing, invalid or lacks the scope, or the target does not exist or is in another organization.
429	Too many requests from this key or address (`RATE_LIMITED`).

Add a trigger to an agent #

POST /authoring/automations/{id}/triggers · key scope authoring

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.

**Key scope:** `authoring` (Build agents, integrations and knowledge).

Parameters

Name	In	Type	Required	Notes
id	path	string	Yes	The agent's id.

Request body

any

Responses

Status	Meaning
201	Created. The new trigger. Field Type Required Notes trigger object Yes Field Type Required Notes id string Yes name string Yes type "schedule" | "api" | "event" Yes status "active" | "disabled" Yes cron string | null Yes timezone string | null Yes input object | null Yes event any No eventFilter object | null Yes
400	The body is invalid - an unknown field, a missing one or a bad value (`VALIDATION`).
404	Not found: the key is missing, invalid or lacks the scope, or the target does not exist or is in another organization.
429	Too many requests from this key or address (`RATE_LIMITED`).

Edit one of an agent's triggers #

PATCH /authoring/automations/{id}/triggers/{triggerId} · key scope authoring

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`.

**Key scope:** `authoring` (Build agents, integrations and knowledge).

Parameters

Name	In	Type	Required	Notes
id	path	string	Yes	The agent's id.
triggerId	path	string	Yes	The trigger's id.

Request body

Option 1

Field	Type	Required	Notes
name	string	No
cron	string	No
timezone	string	No
input	object	No

Option 2

Field	Type	Required	Notes
name	string	No

Option 3

Field	Type	Required	Notes
name	string	No
connectionId	string (uuid, pattern)	No
eventType	string	No
eventFilter	object | null	No

Responses

Status	Meaning
200	The trigger after the edit. Field Type Required Notes trigger object Yes Field Type Required Notes id string Yes name string Yes type "schedule" | "api" | "event" Yes status "active" | "disabled" Yes cron string | null Yes timezone string | null Yes input object | null Yes event any No eventFilter object | null Yes
400	The body is invalid - an unknown field, a missing one or a bad value (`VALIDATION`).
404	Not found: the key is missing, invalid or lacks the scope, or the target does not exist or is in another organization.
429	Too many requests from this key or address (`RATE_LIMITED`).

Remove one of an agent's triggers #

DELETE /authoring/automations/{id}/triggers/{triggerId} · key scope authoring

Delete a trigger subscribed to this agent.

**Key scope:** `authoring` (Build agents, integrations and knowledge).

Parameters

Name	In	Type	Required	Notes
id	path	string	Yes	The agent's id.
triggerId	path	string	Yes	The trigger's id.

Responses

Status	Meaning
204	Deleted; no body.
404	Not found: the key is missing, invalid or lacks the scope, or the target does not exist or is in another organization.
429	Too many requests from this key or address (`RATE_LIMITED`).

Add a simulated test to an agent #

POST /authoring/automations/{id}/eval-cases · key scope authoring

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.

**Key scope:** `authoring` (Build agents, integrations and knowledge).

Parameters

Name	In	Type	Required	Notes
id	path	string	Yes	The agent's id.

Request body

Field	Type	Required	Notes
name	string	Yes
note	string	No
turns	string[]	Yes	What the person says, turn by turn.
script	object[]	No	What each tool answers, consumed in order per tool. Field Type Required Notes tool string Yes The tool's name as the agent calls it. response any Yes What the tool answers with. failed boolean No Answer as a failure - an expired sign-in, a rate limit.
holdout	boolean	No	Keep the case's contents out of what this API returns, so a fix cannot be fitted to it.
assertions	object[]	Yes	Field Type Required Notes kind "reply_contains" | "reply_omits" | "tool_called" | "tool_not_called" | "tool_precedes" | "no_divergence" | "token_ceiling" | "round_budget" | "tool_called_with" | "tool_call_count" Yes value string No 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 string Yes The success criterion in the person's words; what the pass/fail line says.

Responses

Status	Meaning
201	The new case's id. Field Type Required Notes id string Yes
400	The body is invalid - an unknown field, a missing one or a bad value (`VALIDATION`).
404	Not found: the key is missing, invalid or lacks the scope, or the target does not exist or is in another organization.
429	Too many requests from this key or address (`RATE_LIMITED`).

List an agent's tests #

GET /authoring/automations/{id}/eval-cases · key scope authoring

Every case the agent is tested on, with its turns, script and checks. A held-out case is listed by name only.

**Key scope:** `authoring` (Build agents, integrations and knowledge).

Parameters

Name	In	Type	Required	Notes
id	path	string	Yes	The agent's id.

Responses

Status	Meaning
200	The agent's cases.
404	Not found: the key is missing, invalid or lacks the scope, or the target does not exist or is in another organization.
429	Too many requests from this key or address (`RATE_LIMITED`).

Remove a test the Builder wrote #

DELETE /authoring/automations/{id}/eval-cases/{caseId} · key scope authoring

Delete a case this API created. A case a person wrote cannot be removed here.

**Key scope:** `authoring` (Build agents, integrations and knowledge).

Parameters

Name	In	Type	Required	Notes
id	path	string	Yes	The agent's id.
caseId	path	string	Yes	The case's id.

Responses

Status	Meaning
200	Deleted.
404	Not found: the key is missing, invalid or lacks the scope, or the target does not exist or is in another organization.
429	Too many requests from this key or address (`RATE_LIMITED`).

Test an agent's draft #

POST /authoring/automations/{id}/eval-suites · key scope authoring

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.

**Key scope:** `authoring` (Build agents, integrations and knowledge).

Parameters

Name	In	Type	Required	Notes
id	path	string	Yes	The agent's id.

Request body

Field	Type	Required	Notes
repeat	integer	No

Responses

Status	Meaning
202	The suite's id and how many runs it started. Field Type Required Notes suiteRunId string Yes runs integer Yes
400	The body is invalid - an unknown field, a missing one or a bad value (`VALIDATION`).
404	Not found: the key is missing, invalid or lacks the scope, or the target does not exist or is in another organization.
429	Too many requests from this key or address (`RATE_LIMITED`).

Read a test run's results #

GET /authoring/automations/{id}/eval-suites/{suiteId} · key scope authoring

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.

**Key scope:** `authoring` (Build agents, integrations and knowledge).

Parameters

Name	In	Type	Required	Notes
id	path	string	Yes	The agent's id.
suiteId	path	string	Yes	The suite's id, from startAgentEvalSuite.
waitSeconds	query	integer	No

Responses

Status	Meaning
200	The suite's results by case.
404	Not found: the key is missing, invalid or lacks the scope, or the target does not exist or is in another organization.
429	Too many requests from this key or address (`RATE_LIMITED`).

Integrations

Search integrations #

GET /authoring/integrations · key scope authoring

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.

**Key scope:** `authoring` (Build agents, integrations and knowledge).

Parameters

Name	In	Type	Required	Notes
q	query	string	No

Responses

Status	Meaning
200	The matching integrations. Field Type Required Notes integrations object[] Yes Field Type Required Notes id string Yes name string Yes description string Yes tools object[] Yes Field Type Required Notes name string Yes reference string Yes description string Yes isReadonly boolean Yes eventTypes string[] Yes
404	Not found: the key is missing, invalid or lacks the scope, or the target does not exist or is in another organization.
429	Too many requests from this key or address (`RATE_LIMITED`).

List an integration's usable connections #

GET /authoring/integrations/{id}/connections · key scope authoring

The connections of this integration an event trigger may be created on.

**Key scope:** `authoring` (Build agents, integrations and knowledge).

Parameters

Name	In	Type	Required	Notes
id	path	string	Yes	The integration id, such as `yekar.gmail`.

Responses

Status	Meaning
200	The connections. Field Type Required Notes connections object[] Yes Field Type Required Notes id string Yes name string Yes
404	Not found: the key is missing, invalid or lacks the scope, or the target does not exist or is in another organization.
429	Too many requests from this key or address (`RATE_LIMITED`).

Read an integration #

GET /authoring/integrations/{id} · key scope authoring

One integration with each tool's input schema and the events it can fire a trigger on.

**Key scope:** `authoring` (Build agents, integrations and knowledge).

Parameters

Name	In	Type	Required	Notes
id	path	string	Yes	The integration id, such as `yekar.gmail`.

Responses

Status	Meaning
200	The integration. Field Type Required Notes id string Yes name string Yes description string Yes tools object[] Yes Field Type Required Notes name string Yes reference string Yes description string Yes isReadonly boolean Yes inputSchema object Yes events object[] Yes Field Type Required Notes type string Yes name string Yes description string Yes schemaVersion number Yes filterablePaths string[] Yes
404	Not found: the key is missing, invalid or lacks the scope, or the target does not exist or is in another organization.
429	Too many requests from this key or address (`RATE_LIMITED`).

Knowledge

List knowledge bases #

GET /authoring/knowledge-bases · key scope authoring

The knowledge bases the caller can see: those of their domains and the organization-wide ones. New articles are written into a base.

**Key scope:** `authoring` (Build agents, integrations and knowledge).

Parameters

Name	In	Type	Required	Notes
q	query	string	No
limit	query	integer	No
offset	query	integer	No
domainId	query	string (uuid, pattern)	No

Responses

Status	Meaning
200	One page of knowledge bases and the total. Field Type Required Notes knowledgeBases object[] Yes Field Type Required Notes id string Yes name string Yes description string | null Yes domainId string | null Yes total number Yes
404	Not found: the key is missing, invalid or lacks the scope, or the target does not exist or is in another organization.
429	Too many requests from this key or address (`RATE_LIMITED`).

List a domain's knowledge modules #

GET /authoring/knowledge-modules · key scope authoring

The knowledge modules of one domain the caller may view.

**Key scope:** `authoring` (Build agents, integrations and knowledge).

Parameters

Name	In	Type	Required	Notes
domainId	query	string (uuid, pattern)	Yes

Responses

Status	Meaning
200	The modules. Field Type Required Notes modules object[] Yes Field Type Required Notes id string Yes name string Yes description string | null Yes kind "domain" | "org" | "platform" Yes
404	Not found: the key is missing, invalid or lacks the scope, or the target does not exist or is in another organization.
429	Too many requests from this key or address (`RATE_LIMITED`).

Create a knowledge module #

POST /authoring/knowledge-modules · key scope authoring

A named set of articles an agent can be pointed at. A domain module needs `domainId`.

**Key scope:** `authoring` (Build agents, integrations and knowledge).

Request body

Field	Type	Required	Notes
kind	"domain" | "org"	Yes
domainId	string (uuid, pattern)	No
name	string	Yes
description	string	No

Responses

Status	Meaning
201	Created. The module.
400	The body is invalid - an unknown field, a missing one or a bad value (`VALIDATION`).
404	Not found: the key is missing, invalid or lacks the scope, or the target does not exist or is in another organization.
429	Too many requests from this key or address (`RATE_LIMITED`).

Create a draft article #

POST /authoring/knowledge-bases/{baseId}/articles · key scope authoring

A new article in a knowledge base, as a draft. Publish it from the product when it is ready.

**Key scope:** `authoring` (Build agents, integrations and knowledge).

Parameters

Name	In	Type	Required	Notes
baseId	path	string	Yes	The knowledge base's id.

Request body

Field	Type	Required	Notes
title	string	Yes
draftBody	string | null	No

Responses

Status	Meaning
201	Created. The article.
400	The body is invalid - an unknown field, a missing one or a bad value (`VALIDATION`).
404	Not found: the key is missing, invalid or lacks the scope, or the target does not exist or is in another organization.
429	Too many requests from this key or address (`RATE_LIMITED`).

Add an article to a module #

POST /authoring/knowledge-modules/{moduleId}/articles · key scope authoring

Reference an existing article from a knowledge module.

**Key scope:** `authoring` (Build agents, integrations and knowledge).

Parameters

Name	In	Type	Required	Notes
moduleId	path	string	Yes	The module's id.

Request body

Field	Type	Required	Notes
articleId	string (uuid, pattern)	Yes

Responses

Status	Meaning
201	Created. The module membership.
400	The body is invalid - an unknown field, a missing one or a bad value (`VALIDATION`).
404	Not found: the key is missing, invalid or lacks the scope, or the target does not exist or is in another organization.
429	Too many requests from this key or address (`RATE_LIMITED`).