Agent API

The API section issues keys that let something outside Endue call this agent. It is the third way in, beside a conversation and a channel — this one is for programs.

When to use it

When the caller is code: a script that files a daily summary, a backend that asks an agent to classify something, a job that runs in CI. If the caller is a person, a channel is a better fit — it gives them a thread, questions, and approvals.

Issue a key

1. Open the API section in Agent Builder and create a key.

2. Copy it now. The key is shown once. If you lose it, revoke it and issue another.

3. Keep it somewhere a program can read and a person cannot — an environment variable or a secret store, never a repository.

A key created here is scoped to this agent: it cannot be used to call your other agents. Account-wide keys, which can, are issued from Settings → Account instead. Prefer the narrow one.

Open full size

Call the agent

Send the key as Authorization: Bearer sk_… (or X-API-Key), and post what you want the agent to do:

POST /api/public/v1/agents/{agent_id}/invoke
Authorization: Bearer sk_...
Content-Type: application/json

{ "input": "Summarize yesterday's support tickets" }

The response carries the agent’s answer along with a session id. Send that id back on the next call and the agent continues in the same context — the same conversation, with its history — instead of starting fresh:

{ "input": "Now group them by product area", "session_id": "..." }

Set "stream": true to receive the answer as it is produced rather than waiting for the whole run.

A session is a conversation

Sessions are not a separate thing to manage. Each one is a conversation you can open in Endue — under the agent’s API group in the sidebar — to read what the agent was asked and what it answered.

What an API call does not get

An API caller is not sitting in front of the conversation, so it is treated as an unattended run:

• Actions that send outward or delete are refused, not queued for someone to approve.
• Questions the agent needs answered have nobody to answer them.

Write the request precisely enough that the agent does not need a decision, and expect drafts rather than sends.

Limits

• One run at a time per session. Calling again while a run is in progress on that session is rejected rather than queued.
• Keys are shown once and cannot be recovered — revoke and reissue.
• A key scoped to an agent works only for that agent; the endpoint returns not-found for others.
• Revoking a key takes effect immediately.

Related

ChannelsThe way in for people rather than programs.

ApprovalsWhy an API call cannot send email on its own.

Security and permissionsWhat a key can reach, and how to withdraw it.