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

# Secrets HTTP API

> Store environment secrets, read their metadata, and attach them to jobs.

Store Evolve environment secrets once and refer to them by name in jobs. Hosted evaluations support `delivery: "direct"`, which places the value in the sandbox environment. Reads return metadata, never the stored value.

Examples reuse [connection setup](https://docs.evolvingmachines.ai/api-reference/index.md#connect). List metadata before choosing a name and label:

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

## Routes

| Method and path | Input | Success |
| - | - | - |
| `GET /api/managed-secrets` | None | `200`, metadata under `secrets` |
| `POST /api/managed-secrets` | JSON fields below | `201 { status: "created", secret }` or `200 { status: "updated", secret }` |
| `DELETE /api/managed-secrets` | Required `name`; optional `label` | `200 { ok, name, label }` |

## Store a value

Save the request in a local `secret.json` file, replacing `YOUR_VALUE` with the credential. Keep this file out of source control.

```json secret.json theme={"dark"}
{
  "name": "SERVICE_TOKEN",
  "label": "default",
  "value": "YOUR_VALUE",
  "delivery": "direct"
}
```

```bash theme={"dark"}
curl -sS "$API/api/managed-secrets" \
  -H "Authorization: Bearer $EVOLVE_API_KEY" \
  -H 'Content-Type: application/json' \
  --data-binary @secret.json
```

| Field | Required | Rules |
| - | - | - |
| `name` | Yes | Uppercased environment-variable name, matching `[A-Z_][A-Z0-9_]{0,127}`; `EVOLVE_` prefix is reserved |
| `value` | Yes | At most 190 UTF-8 bytes |
| `delivery` | Yes | `direct` for hosted evaluations; storage also accepts `brokered` |
| `label` | No | Defaults to `default`; 1–80 letters, digits, `.`, `_`, or `-` |
| `allowed_hosts` | For brokered delivery | Array of allowed hosts |
| `allowed_path_prefixes` | For brokered delivery | Array of allowed path prefixes |
| `allowed_methods` | For brokered delivery | Array of allowed HTTP methods |

Direct delivery refuses the three scope fields. Brokered secrets cannot be attached to hosted evaluation jobs. LLM provider keys are managed separately in the signed-in dashboard, not through this environment-secret endpoint.

An existing `(name, label)` with the same value returns `updated`; delivery and scope can change on that request. A different value returns `409 secret_exists`. To rotate, use a new label or delete and recreate the existing identity.

## Attach and delete

Add this fragment to a [job request](https://docs.evolvingmachines.ai/api-reference/jobs.md#create-a-job):

```json theme={"dark"}
{
  "secrets": [
    {
      "name": "SERVICE_TOKEN",
      "label": "default",
      "as": "APP_TOKEN"
    }
  ]
}
```

`as` is optional and defaults to `name`. Without `label`, resolution chooses the `default` row, then the only row if exactly one exists. Multiple other labels produce `secret_ambiguous`.

To delete the labeled value:

```bash theme={"dark"}
curl -sS -X DELETE "$API/api/managed-secrets" \
  -H "Authorization: Bearer $EVOLVE_API_KEY" \
  -H 'Content-Type: application/json' \
  --data '{"name":"SERVICE_TOKEN","label":"default"}'
```

Deletion also revokes access grants attached to that row. Omitting the label uses the same resolution rule as attachment.

## Responses and errors

Write responses use metadata fields such as `allowed_hosts`, `allowed_path_prefixes`, `allowed_methods`, `created_at`, `updated_at`, and `last_used_at`. The list response retains the earlier camelCase spellings: `allowedHosts`, `allowedPathPrefixes`, `allowedMethods`, `createdAt`, `updatedAt`, and `lastUsedAt`. The [secret method reference](https://docs.evolvingmachines.ai/sdk-reference/methods/secrets.md) describes their SDK representations.

These endpoints use their own error shape: an `error` message, with a top-level `code` on typed write refusals. Do not parse them as the nested hosted `error.code` envelope. Write codes include `invalid_input` (400), `secret_ambiguous` (400), `read_only_key` (403), `secret_not_found` (404), and `secret_exists` (409).


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