Skip to main content

API overview

Everything you build in Yekar.AI is callable from your own product. Fire an agent from your backend, pass the credential of the customer you're acting for, and get the result back - with a full session behind it that you or your support team can open later.

The machine-to-machine API has two run entry points. Start a session directly on one published Agent when you are shipping its experience inside your product. Fire an API trigger when one event should fan out to subscribed agents and flows. Both paths create durable sessions. Base URL: https://api.yekar.ai/api/v1.

Concepts​

Everything you call over the API is something a person has already set up in Yekar.AI. This API does not create organizations, domains, agents, flows, connections, or triggers; it runs what is already there.

An organization is the tenant boundary. A domain is a permission boundary inside it, grouping agents and flows, connections, and the people allowed to use them. An agent or flow is the thing being invoked - the API's automationId fields address either kind: an Agent accepts a natural-language prompt, while a Flow accepts an input object matching its declared inputs. A session is the conversation and audit trail. A trigger is a stable subscription point that can fan one event out to several subscribed agents and flows. Connections are configured in the product, not through this API.

Agents are conversational: their written instructions guide a model that can choose among connected tools on each turn. Flows are deterministic, published, versioned step graphs whose input must match their declared fields. A connection supplies the external-system account used by an agent or flow; connection failures can therefore surface in a run even though this API does not create or manage connections.

Quickstart​

Choose the entry point that matches what your product is doing.

Ship an Agent inside your product​

Use the direct session route when one customer action should start one published Agent and your product will show its live response.

  1. Publish the Agent you intend to call.
  2. Create a personal key under Triggers → API keys and copy the Agent's automation id from its detail-page URL.
  3. Start the session with the customer's request. Include caller credentials when the Agent should use that customer's account for a bound integration.
curl -X POST "https://api.yekar.ai/api/v1/agents/$AGENT_ID/sessions" \
  -H "Authorization: Bearer $YEKAR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "message": "Triage support ticket T-4471" }'

The accepted response contains the session and first execution:

{ "sessionId": "0b1f3c9a-…", "executionId": "64ed2e3d-…" }
  1. Open GET /agents/sessions/:sessionId/stream to receive message, tool, approval, and completion events over Server-Sent Events.
  2. Append another customer message with POST /agents/sessions/:sessionId/messages, or resolve a suspended write with POST /agents/sessions/:sessionId/turn-approval.

A 202 response means the first turn was accepted, not that it completed. See Personal-key Agent conversations for the request fields, stream events, and approval contract.

Fan one event out through a trigger​

Use a trigger when one event should start several subscribed agents or flows, or when you want a stable subscription point independent of any one automation.

  1. Create an API trigger and a personal key under Triggers → API keys.
  2. Publish the agents or flows you intend to call, and subscribe them to that trigger.
  3. Copy the trigger id from its detail-page URL in the product.
  4. POST /triggers/fire with the key as a Bearer token.
  5. Use the returned session or run ids to follow the accepted work. A 202 response means the request was accepted, not that execution succeeded.
  6. Register a webhook to be told when that work finishes, rather than polling for it.

Continue with Authentication and the complete API reference.

Calling agents from an MCP client​

Assistants that speak the Model Context Protocol can reach your published agents as tools without any code at all: point one at POST /api/v1/mcp with the same personal key. Any client that lets you set an Authorization header - Claude Code, Cursor, VS Code, the Copilot and Codex CLIs - works today. See MCP server.