# Agent API

> Call an agent over HTTP with a key scoped to it — one request, or a session that keeps its context between calls.

The **API** section issues keys that let something outside Endue call this agent. It is the third way in, beside a [conversation](/docs/work/conversations/) and a [channel](/docs/automate/channels/) — 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

<Steps>

1. **Open the API section** in [Agent Builder](/docs/build/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.

</Steps>

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.

<Screenshot
  name="studio-api"
  alt="The API section: an issued key listed with its prefix and last use, above a ready-to-copy example request."
/>

## Call the agent

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

```http
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:

```json
{ "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.

<Aside type="note" title="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.
</Aside>

## 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](/docs/automate/routines/#nobody-is-there-to-approve):

- Actions that send outward or delete are **refused**, not queued for someone to approve.
- [Questions](/docs/work/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

<CardGrid>
  <LinkCard
    title="Channels"
    href="/docs/automate/channels/"
    description="The way in for people rather than programs."
  />
  <LinkCard
    title="Approvals"
    href="/docs/work/approvals/"
    description="Why an API call cannot send email on its own."
  />
  <LinkCard
    title="Security and permissions"
    href="/docs/account/security/"
    description="What a key can reach, and how to withdraw it."
  />
</CardGrid>