everruns-api · v2.0 · 2026-11-10 · sha256 6bb115c6ecd1d1e4
everruns-api v2.0A
Immutable. This exact content never changes and is served at /api/v1/blob/6bb115c6ecd1d1e4.
No tool to install first
claude plugin marketplace add https://markdownregistry.com/mp/a/art_uvcw4xxsgn2mcedv/6bb115c6ecd1d1e4c7728f1d930d324df1a61f9aa750a4ed971e1cb064649fa9.json
Then /plugin install everruns-api@markdownregistry-uvcw4xxsgn2mcedv in Claude Code. It installs this exact version, the one graded A here, pinned to the commit it was graded at, and leaves it there.
---
name: everruns-api
description: Create agents, open sessions, and stream events over the Everruns REST API with a personal access token. Use for server-to-server automation where no browser or MCP client is available; use everruns-cli for shell work and everruns-mcp for MCP clients.
license: MIT
metadata:
category: platform
version: "2.0"
---
# Drive Everruns over the REST API
Everruns is API-first: everything the UI does is available over HTTP, with
server-sent events for streaming. Use the person's own Everruns unless they
name another one.
## Base URL
Set `EVERRUNS_URL` to the deployment's origin and use `$EVERRUNS_URL/api`:
- On their machine (`everruns docker up`, `everruns k8s port-forward`):
`http://localhost:9300`
- On their server or cluster: the public URL they chose, such as
`https://everruns.example.com`
- The demo instance, only when the person asks for it: `https://app.everruns.com`.
It is a demo, not a hosted service.
Check it first: `curl -fsS "$EVERRUNS_URL/health"`. The deployment's own
`$EVERRUNS_URL/auth.md` says which credentials it needs; a local install with
`--auth none` needs none.
## Credential
The person issues a personal access token in the UI under **Settings →
Personal access tokens** and puts it in their environment as
`EVERRUNS_TOKEN`. Tokens start with `evr_pat_` and carry the full authority of
the account. Never ask for the token in the conversation, print it, or commit
it. Send it as `Authorization: Bearer $EVERRUNS_TOKEN`.
## Create an agent
```bash
curl -fsS -X POST "$EVERRUNS_URL/api/v1/agents" \
-H "Authorization: Bearer $EVERRUNS_TOKEN" \
-H "Content-Type: application/json" \
-d '{"name":"Assistant","system_prompt":"You are helpful."}'
```
## Open a session
```bash
curl -fsS -X POST "$EVERRUNS_URL/api/v1/sessions" \
-H "Authorization: Bearer $EVERRUNS_TOKEN" \
-H "Content-Type: application/json" \
-d '{"agent_id":"<agent_id>"}'
```
## Send a message
```bash
curl -fsS -X POST "$EVERRUNS_URL/api/v1/sessions/<session_id>/messages" \
-H "Authorization: Bearer $EVERRUNS_TOKEN" \
-H "Content-Type: application/json" \
-d '{"message":{"role":"user","content":[{"type":"text","text":"Hello!"}]}}'
```
## Stream events
```bash
curl -N "$EVERRUNS_URL/api/v1/sessions/<session_id>/events" \
-H "Authorization: Bearer $EVERRUNS_TOKEN"
```
Sessions are durable: progress is persisted per step, so a session survives
restarts and worker loss. Disconnect, reconnect later, and resume the stream
instead of replaying from scratch.
## Reference
- OpenAPI description: <https://everruns.com/docs/api/>, or
`$EVERRUNS_URL/.well-known/api-catalog` on the deployment
- Streaming: <https://everruns.com/docs/how-to/stream-events/>