> ## 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`.

# Checks HTTP API

> Check task quality from an archive or a published dataset, and follow the reports.

Run an Evolve task quality check to review task files against a rubric. Submit an archive or a published dataset, then poll the returned check until its task checks settle.

Examples reuse [connection setup](https://docs.evolvingmachines.ai/api-reference/index.md#connect). This request checks one task from a published dataset:

```bash theme={"dark"}
curl -sS "$API/api/checks" \
  -H "Authorization: Bearer $EVOLVE_API_KEY" \
  -F 'dataset=deepswe@1.1' \
  -F 'config={"include_task_names":["anko-default-function-arguments"]}'
```

Success returns `202 Check`, including its `id` and one `results` entry per selected task. Set `CHECK_ID` to that id. This starts billable checker work; it does not run the evaluation agent on the task.

## Routes

| Method and path | Input | Success |
| - | - | - |
| `POST /api/checks` | Multipart fields below | `202 Check` |
| `GET /api/checks` | Collection filters below | `200 CheckPage` |
| `GET /api/checks/defaults` | Optional `agent` | `200 CheckDefaults` |
| `GET /api/checks/{checkId}` | Check id | `200 Check` |
| `GET /api/checks/{checkId}/download` | Check id or task-check id | `200`, `.tar.gz` archive |
| `DELETE /api/checks/{checkId}` | Creator's terminal check | `200 CheckDeleteResult` |
| `POST /api/checks/{checkId}/share` | Required JSON share request | `200 JobShares` |
| `POST /api/checks/{checkId}/unshare` | Required JSON share request | `200 JobShares` |
| `GET /api/checks/{checkId}/shares` | Creator's check | `200 JobShares` |

Result fields are in [analysis and check results](https://docs.evolvingmachines.ai/sdk-reference/types.md#analysis-and-check-results); language equivalents and full signatures are in [check methods](https://docs.evolvingmachines.ai/sdk-reference/methods/checks.md).

## Request fields

| Multipart field | Required | Meaning |
| - | - | - |
| `archive` | One source | Gzipped task directory, or directory of task directories |
| `dataset` | One source | Published `name` or `name@version`; bare name uses the active version |
| `config` | No | JSON text with the configuration below; omitted or `{}` uses defaults |

Supply exactly one of `archive` and `dataset`. For an archive, replace the dataset field with `-F 'archive=@tasks.tar.gz'`.

All configuration fields are optional:

| Config field | Meaning and constraints |
| - | - |
| `name` | 1–120 characters; omitted uses the UTC acceptance timestamp as the name |
| `agent`, `model_name` | Checker harness and supported model; omitted values use current defaults |
| `reasoning_effort` | Supported effort for the selected model |
| `sandbox_provider` | Supported sandbox provider |
| `rubric` | Object with nonempty `criteria`; each criterion has `name`, `description`, and `guidance` |
| `prompt` | Nonempty template text replacing the checker prompt |
| `n_concurrent` | Integer 1–150; also constrained by the organization's analysis quota |
| `include_task_names` | Array of nonempty glob patterns; keep matching tasks |
| `exclude_task_names` | Array of nonempty glob patterns; then remove matching tasks |
| `n_tasks` | Positive integer cap applied after the filters |

Read `GET /api/checks/defaults`, optionally with `agent`, for the current agent, model, rubric, prompt, reasoning effort, and provider. See [checker configuration](https://docs.evolvingmachines.ai/sdk-reference/checks.md#configuration) for template details. Omitting concurrency uses the organization ceiling; task checks and trace analyses share that ceiling.

## Read and download

```bash theme={"dark"}
curl -sS "$API/api/checks/$CHECK_ID" \
  -H "Authorization: Bearer $EVOLVE_API_KEY"
```

The check status is `queued`, `running`, or `completed`. A completed check means its task checks settled; inspect each result's status, `checks`, and `failure` before treating it as successful. A checker that produces an invalid result is retried at most once; a budget timeout is not retried.

List filters are optional `scope` (`my`, `shared`, `org`), repeatable `status` (`queued`, `running`, `completed`), `dataset`, `limit`, `cursor`, `sortField=created`, and `sortDirection=asc|desc`. Default scope is `my`; default order is newest first. See [pagination](https://docs.evolvingmachines.ai/api-reference/index.md#pagination).

```bash theme={"dark"}
curl --fail-with-body -sS "$API/api/checks/$CHECK_ID/download" \
  -H "Authorization: Bearer $EVOLVE_API_KEY" \
  -o check.tar.gz
```

A check id downloads the whole check report and task-check folders. A task-check id from `results[].id` downloads only that task-check folder. The run must be settled.

For sandbox files and logs, use the [shared filesystem routes](https://docs.evolvingmachines.ai/api-reference/trials.md#filesystem-and-logs) with resource prefix `/api/checks/{checkId}/tasks/{taskCheckId}`.

## Share or delete

Share requests use `link: true`, `emails: [...]`, or both. They follow the [job sharing rules](https://docs.evolvingmachines.ai/api-reference/jobs.md#share-and-delete), including creator-only management and a maximum of 50 email grants. New email shares send invitations.

```bash theme={"dark"}
curl -sS "$API/api/checks/$CHECK_ID/share" \
  -H "Authorization: Bearer $EVOLVE_API_KEY" \
  -H 'Content-Type: application/json' \
  --data '{"link":true}'
```

Send the same body to `/unshare` to revoke the link. `GET /shares` reads its current state. To permanently remove a check you created:

```bash theme={"dark"}
curl -sS -X DELETE "$API/api/checks/$CHECK_ID" \
  -H "Authorization: Bearer $EVOLVE_API_KEY"
```

This deletes its task checks and stored results. A dataset used as the source remains available.

## Errors

Empty selections return `400 no_checkable_tasks`. Invalid archives or configuration return `invalid_archive`, `invalid_input`, or `invalid_rubric`. Upload capacity can return `413 upload_too_large` or `429 too_many_concurrent_check_uploads`; the latter has no fixed retry delay.

Download and deletion refuse active checks with `409 check_not_terminal`; the same code can mean results are still being finalized. Deletion and share management require the creator. See [check error codes](https://docs.evolvingmachines.ai/sdk-reference/error-codes.md#analysis-and-task-checks).


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