API reference

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

Edith API

Questions, image inputs, probabilities, and errors.

Evaluation API

Make your first request and follow a job to its result.

Connect

For evaluations, get an API key, set EVOLVE_API_KEY, and reuse this origin in the examples:

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 documents account and team operations.

Resources

Resource	Operations
Jobs	Start, follow, compare, retry, import, share, and delete evaluations
Trials	Read attempts, traces, files, sandbox state, and logs
Datasets	Browse, publish, inspect builds, and read task packages
Checks	Run task quality checks and read reports
Analyses	Configure trace analysis and inspect analyzer runs
Agents	Register and manage your own agents
Skills	Upload skill folders and read their identifiers
Authentication	Read account capabilities and manage supported team operations
Secrets	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 and returned objects 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.

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:

{
  "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 for operation-specific meanings. A transport retry, a trial retry, and a new intended evaluation are different actions. Secret storage has a separate response and error contract.

Discover current capabilities

GET /api/meta requires no key:

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.

HTTP API

Python and TypeScript

Run agents

Shared behavior

SDK workflows

SDK resources

SDK methods