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

# Agents HTTP API

> Register your own agent and select it in evaluation jobs.

Register an Evolve agent when your evaluation needs your own executable or installation script. Built-in harnesses are listed by `GET /api/meta`; they do not need registration.

Examples reuse `API` and `EVOLVE_API_KEY` from [connection setup](https://docs.evolvingmachines.ai/api-reference/index.md#connect). Save your installer as `install.sh` before sending this request:

```bash theme={"dark"}
curl -sS "$API/api/agents" \
  -H "Authorization: Bearer $EVOLVE_API_KEY" \
  -F 'name=my-agent' \
  -F 'run_command=my-agent' \
  -F 'install_script=<install.sh'
```

Success returns `201` with an `Agent`. Use its `name` as a job arm's `name`, alongside a required `model_name`.

## Routes

| Method and path | Input | Success |
| - | - | - |
| `POST /api/agents` | Multipart registration below | `201 Agent` |
| `GET /api/agents` | Optional `scope`, `limit`, `cursor` | `200 AgentPage` |
| `GET /api/agents/{name}` | Registered name | `200 Agent` |
| `PUT /api/agents/{name}` | Multipart replacement below; name comes from the URL | `201 Agent` when created; `200 Agent` when replaced |
| `DELETE /api/agents/{name}` | Registered name | `204`, no body |

`scope` is `my` (default), `shared`, or `org`. See [pagination](https://docs.evolvingmachines.ai/api-reference/index.md#pagination) and [agent methods](https://docs.evolvingmachines.ai/sdk-reference/methods/agents.md) for field-level results and SDK equivalents.

## Registration fields

| Multipart field | Required | Meaning |
| - | - | - |
| `name` | POST only | Registration name; PUT takes its name from the URL and ignores a multipart `name` |
| `run_command` | Yes | Command used to run the agent |
| `install_script` | One source | Script text, not a path on your computer |
| `archive` | One source | Gzipped tarball of the agent directory |
| `org` | No | Owning organization slug or id; defaults to personal on creation; replacement preserves the existing organization and refuses a different one |
| `env` | No | JSON object of string values encoded as a multipart text field |

Provide exactly one of `install_script` or `archive`. Registration validates the input without running the installer. The first trial that names the agent builds it with internet access and no secrets; install executables under `$PREFIX/bin`. Read [custom agent packaging](https://docs.evolvingmachines.ai/core-concepts/agents.md) before creating the installer.

To read the registration:

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

To create or replace it by name, reuse the registration request with `-X PUT` and `/api/agents/my-agent`, omitting the multipart `name`. PUT fully replaces the command, source, and environment; an omitted `env` becomes empty. It returns `201` with a `Location` header for a new registration, or `200` for a replacement.

Only the owner can edit or delete a registration. Members of its organization can read it and select it in a job. To remove it:

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

## Errors

Malformed registration fields or an invalid archive refuse registration. An installer failure instead settles the first trial as an infrastructure error, with builder output in its stdout/stderr artifacts. Creating an existing name returns `409 agent_name_taken`; use `PUT` for an intended replacement. A missing registration returns `404 agent_not_found`. See [registered-agent error codes](https://docs.evolvingmachines.ai/sdk-reference/error-codes.md#registered-agents).


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