> For the complete documentation index, see [llms.txt](https://docs.eesel.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.eesel.ai/apis-and-developer-resources/api-access.md).

# API access

API access to your eesel AI agent: get a workspace token, then use it from your own code, a script or CI through the eesel CLI or eesel's MCP endpoint, with no browser sign-in.

API access lets your own code, a script or a CI job use your eesel agent without a browser sign-in. It works with one workspace token.

eesel doesn't have a separate REST API. Your code uses the same two ways in that AI assistants use:

* **The eesel CLI**, with the token set as an environment variable. Easiest for scripts and CI.
* **eesel's MCP endpoint**, called over plain HTTP. Easiest from your own backend code.

Both give you the same things: chat with your agent, check what's connected, connect integrations, manage automations, read files and decide approvals.

<details>

<summary>For AI agents and scripts</summary>

To get a token, an editor adds one in Settings > Developers in the dashboard. It lasts until someone revokes it. The agent id is in the agent's dashboard address, `/platform/<agent id>/`. Or run `npx @eesel/cli login` once on a machine with a browser, then `npx @eesel/cli mcp token`, which prints the API URL, a 30-day token and the agent id. Then either:

1. Set `EESEL_API_URL`, `EESEL_API_TOKEN` and `EESEL_AGENT_ID` and run any `eesel` command. No login is needed where those are set.
2. Or POST JSON-RPC `tools/call` requests to `<api_url>/mcp` with `Authorization: Bearer <token>` and `X-Eesel-Agent-Id: <agent id>`.

</details>

## Get a token

### From the dashboard

1. Go to **Settings > Developers** and click **Add API token**.
2. Name it after the script or tool that will use it, for example "Nightly import script", and click **Create token**.
3. Copy the token. It's shown once, so put it in your secrets store before you close the popup.

A token from the dashboard lasts until someone revokes it. It acts with your access, and stops working if you stop being an editor of the workspace. Make one per script or tool, so you can revoke one without breaking the rest.

Your code also needs the agent id. It's in the agent's dashboard address: `/platform/<agent id>/`.

Only editors can add or revoke tokens. Everyone in the workspace can see the list. Workspaces under a HIPAA agreement can't make API tokens.

### From the eesel CLI

Sign in once from a machine with a browser, then ask the CLI for the token:

```bash
npx @eesel/cli login
npx @eesel/cli mcp token
```

`mcp token` prints three things your code needs:

* the API URL (`https://oracle.eesel.app`)
* the token, which lasts 30 days
* the id of the agent to use

Keep the token in your secrets store or `.env` file, never in your code. Anyone holding it can act in your workspace until it expires.

If you set up eesel with the CLI without signing in (an anonymous workspace), `mcp token` still works, but the token ends when that workspace does, after 7 days. Run `eesel login` first for a 30-day token. Signing in keeps everything you set up.

For a token that doesn't expire, make one in Settings > Developers instead.

### Revoke a token

In **Settings > Developers**, open the token's **...** menu and choose **Revoke token**, then confirm. It stops working on its next request. A CLI token can't be revoked on its own; it expires after 30 days.

## Use it from a script or CI

Set three environment variables and the CLI runs without a sign-in:

```bash
export EESEL_API_URL=https://oracle.eesel.app
export EESEL_API_TOKEN=<token>
export EESEL_AGENT_ID=<agent id>

npx @eesel/cli status
npx @eesel/cli chat "What's our refund policy?"
```

Every command on [The eesel CLI](/apis-and-developer-resources/cli.md) page works this way, and every command prints JSON your code can read.

## Use it from your own code

Send a `POST` to the MCP endpoint. This asks your agent a question:

```bash
curl https://oracle.eesel.app/mcp \
  -H "Authorization: Bearer $EESEL_API_TOKEN" \
  -H "X-Eesel-Agent-Id: $EESEL_AGENT_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": { "name": "chat", "arguments": { "message": "What is our refund policy?" } }
  }'
```

The reply comes back as JSON. If your agent is still working on it, the reply includes a `task_id`. Send `chat` again with just that `task_id` to collect the answer, or with a `task_id` and a new `message` to continue the conversation.

To see everything you can call, send `"method": "tools/list"` instead. The tools are the same ones listed on [Claude Code & MCP clients](/apis-and-developer-resources/claude-code-and-mcp-clients.md#what-you-can-do).

## Let your code wake the agent instead

If your code only needs to hand the agent some data and let it act on its own, such as "a new order came in, check it", a [webhook automation](/automations-and-schedules/webhooks.md) is simpler. It gives you a URL, and your code sends a plain HTTP POST with no API token.

## Good to know

* A token covers the whole workspace. The `X-Eesel-Agent-Id` header, or `EESEL_AGENT_ID`, picks which agent it acts as.
* A CLI token carries your role from when you made it: a viewer's changes wait for an editor to approve them, and if your role changes, make a new one. A dashboard token always acts as an editor, and stops working if its maker stops being one.
* To change the agent's instructions or memory, ask it in `chat`. There's no direct write for those, from the API or anywhere else.
* When a CLI token expires, run `eesel mcp token` again and update your secret. Dashboard tokens don't expire.

## FAQ

<details>

<summary>Does eesel have a REST API?</summary>

Not a separate one. Your code uses the eesel CLI with a token, or calls eesel's MCP endpoint over HTTP. Both reach the same features. See [Use it from your own code](#use-it-from-your-own-code).

</details>

<details>

<summary>How do I get an eesel API token?</summary>

Add one in **Settings > Developers**: it lasts until it's revoked. Or run `npx @eesel/cli login`, then `npx @eesel/cli mcp token`, for a token that lasts 30 days.

</details>

<details>

<summary>Can I use the eesel CLI in CI without a browser?</summary>

Yes. Set `EESEL_API_URL`, `EESEL_API_TOKEN` and `EESEL_AGENT_ID` as secrets in your CI, and every `eesel` command runs without a sign-in.

</details>

## Related

* [The eesel CLI](/apis-and-developer-resources/cli.md) for every command
* [Claude Code & MCP clients](/apis-and-developer-resources/claude-code-and-mcp-clients.md) to use the same token from an AI coding tool
* [Webhooks](/automations-and-schedules/webhooks.md) to wake your agent from another service


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.eesel.ai/apis-and-developer-resources/api-access.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.