> ## Documentation Index
> Fetch the complete documentation index at: https://docs.evolvingmachines.ai/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Evolve has two products behind one API key. Edith answers questions about an agent trajectory over HTTP: `POST https://api.evolvingmachines.ai/v1/decisions`. Evaluations run coding agents on tasks in cloud sandboxes, through the `evolve` CLI, the Python and TypeScript SDKs, or HTTP.
> A person creates the key at https://dashboard.evolvingmachines.ai/api-keys. Read it from `EVOLVE_API_KEY`; never ask for it in chat or write it to a file.
> Install the CLI with `npm install -g @evolvingmachines/evolve`, then confirm the connection with `evolve auth status`.
> The CLI carries the manual for its own version. `evolve skills get evals` prints the index and `evolve skills get evals <page>` prints one page, for example `evolve skills get evals cli-reference/run`. When the installed CLI is older than this site, follow the installed manual.
> Commands take `--help` for their options and `--json` for machine-readable output. Evaluations spend credits: start with one task and set `--max-trial-spend`.

# API reference

> Call Edith or run evaluations from your application.

Use Edith to ask questions about agent runs. Use the evaluation API to run tasks and inspect their results.

> [card] [Edith API](https://docs.evolvingmachines.ai/edith/api.md)
>
> Questions, image inputs, probabilities, and errors.

> [card] [Evaluation API](https://docs.evolvingmachines.ai/sdk/http.md)
>
> Make your first request and follow a job to its result.

## Connect

For evaluations, get an [API key](https://docs.evolvingmachines.ai/getting-started/installation.md#connect-your-account), set `EVOLVE_API_KEY`, and reuse this origin in the examples:

```bash theme={"dark"}
API=https://dashboard.evolvingmachines.ai

curl -sS "$API/api/auth/status" \
  -H "Authorization: Bearer $EVOLVE_API_KEY"
```

A successful request returns `200` with your identity and account status. Writes require a full-access key. [Authentication](https://docs.evolvingmachines.ai/api-reference/auth.md) documents account and team operations.

## Resources

| Resource | Operations |
| - | - |
| [Jobs](https://docs.evolvingmachines.ai/api-reference/jobs.md) | Start, follow, compare, retry, import, share, and delete evaluations |
| [Trials](https://docs.evolvingmachines.ai/api-reference/trials.md) | Read attempts, traces, files, sandbox state, and logs |
| [Datasets](https://docs.evolvingmachines.ai/api-reference/datasets.md) | Browse, publish, inspect builds, and read task packages |
| [Checks](https://docs.evolvingmachines.ai/api-reference/checks.md) | Run task quality checks and read reports |
| [Analyses](https://docs.evolvingmachines.ai/api-reference/analyses.md) | Configure trace analysis and inspect analyzer runs |
| [Agents](https://docs.evolvingmachines.ai/api-reference/agents.md) | Register and manage your own agents |
| [Skills](https://docs.evolvingmachines.ai/api-reference/skills.md) | Upload skill folders and read their identifiers |
| [Authentication](https://docs.evolvingmachines.ai/api-reference/auth.md) | Read account capabilities and manage supported team operations |
| [Secrets](https://docs.evolvingmachines.ai/api-reference/secrets.md) | Store credentials and attach them to jobs by name |

These pages cover the hosted operations used by the public clients. They are a resource guide, not a complete endpoint or schema catalog. The linked [SDK methods](https://docs.evolvingmachines.ai/sdk-reference/index.md) and [returned objects](https://docs.evolvingmachines.ai/sdk-reference/types.md) provide the detailed input and result models.

## Request conventions

Paths are relative to `API`. Replace path variables such as `{jobId}` with the id returned by an earlier request; URL-encode names and paths. JSON writes use `Content-Type: application/json`. Let `curl -F` set the multipart content type for uploads.

Most JSON fields use `snake_case`. Preserve the documented exceptions, including `nextCursor`, `hasMore`, `trials.byStatus`, and `taskMatrix`. The HTTP field names remain the same whichever language sends the request.

### Pagination

Catalog collections return `items`, `nextCursor`, and `hasMore`. Unless a resource says otherwise, `limit` defaults to 50 and has a maximum of 200. Pass the returned cursor unchanged with the same filters and sort direction.

```bash theme={"dark"}
curl -sS --get "$API/api/jobs" \
  -H "Authorization: Bearer $EVOLVE_API_KEY" \
  --data-urlencode "limit=20" \
  --data-urlencode "cursor=$NEXT_CURSOR"
```

Set `NEXT_CURSOR` from the previous page. An empty catalog page has this shape:

```json theme={"dark"}
{
  "items": [],
  "nextCursor": null,
  "hasMore": false
}
```

Filesystem and organization results use their own documented shapes; do not apply the catalog envelope to them.

### Idempotent job submissions

Send `Idempotency-Key` on job creation, resume, and retry requests, including trial retry. The key is a caller-chosen string of at most 200 characters. Repeating the same resolved request returns `200` with `idempotent_replay: true`; a new job returns `202`. Reusing the key for a different request returns `409 idempotency_key_reused`.

Keys are shared across these routes. Retrying one trial through its trial route or its job route with that single `trial_ids` entry is the same request. Otherwise, reuse a key only to retry the original submission. Pin dataset and agent versions when a replay must survive changes to their defaults.

### Errors

Hosted evaluation refusals use a non-success HTTP status and an `error` object. Read `error.code` before deciding whether to retry.

| Field or header | Meaning |
| - | - |
| `error.code`, `error.message` | Machine-readable reason and explanation |
| `error.param`, `error.details` | Invalid field or additional context, when present |
| `error.request_id` | Request identifier; `requestId` is its legacy alias |
| `X-Request-Id` | Correlation id on success and error responses |
| `error.retryAfterSec`, `Retry-After` | Requested delay, when supplied |

`401` indicates an invalid or missing credential. `403 read_only_key` refuses a write. `402 insufficient_credits` requires credits. `429 rate_limited` may be retried after the supplied delay; `429 quota_exceeded` requires available organization capacity and has no promised retry delay. An unknown or inaccessible resource can return `404`.

See the [error-code catalog](https://docs.evolvingmachines.ai/sdk-reference/error-codes.md) for operation-specific meanings. A transport retry, a trial retry, and a new intended evaluation are different actions. [Secret storage](https://docs.evolvingmachines.ai/api-reference/secrets.md) has a separate response and error contract.

## Discover current capabilities

`GET /api/meta` requires no key:

```bash theme={"dark"}
curl -sS "$API/api/meta"
```

It returns `200` with the current harness/model catalog, analysis defaults, limits, and error codes. Use its advertised model and reasoning-effort choices when composing job arms; do not assume a model supported by one harness is supported by every harness.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.