> For the complete documentation index, see [llms.txt](/llms.txt).
> A full single-fetch corpus is available at [llms-full.txt](/llms-full.txt).

# AGNT5 API reference

The AGNT5 REST API: authentication, projects, deployments, workers, runs, datasets, and experiments. JSON in and out, standard HTTP verbs and status codes.

## Base URL

Every endpoint's path is relative to `https://api.agnt5.com`.

## Authentication

Send a personal API key or a bearer token with every request, e.g. `X-API-KEY: your_api_key`. [Authentication](https://agnt5.com/docs/api-reference/authentication.md) covers both, plus rate limits and the error envelope.

## Resources and endpoints

- [Authentication](https://agnt5.com/docs/api-reference/authentication.md): Authenticate requests to the AGNT5 API with a personal API key or a bearer token, and understand the error envelope and rate limits every endpoint shares.
- [Projects](https://agnt5.com/docs/api-reference/projects.md): List the projects your credential can access and fetch a single project's metadata, workflow count, and production deployment.
  - [List projects (`GET /api/v1/projects`)](https://agnt5.com/docs/api-reference/projects/list-projects.md): List the projects visible to the authenticated user, across every workspace they belong to.
  - [Get a project (`GET /api/v1/projects/:id`)](https://agnt5.com/docs/api-reference/projects/get-a-project.md): Fetch a single project by its UUID, including its language, workflow and deployment counts, and production deployment.
- [Environments](https://agnt5.com/docs/api-reference/environments.md): List, fetch, and create the environments a project deploys into: local, preview, staging, and production.
  - [List environments (`GET /api/v1/environments`)](https://agnt5.com/docs/api-reference/environments/list-environments.md): List a project's environments by project_id. Every project gets local, preview, staging, and production, created the first time you list them.
  - [Get an environment (`GET /api/v1/environments/:id`)](https://agnt5.com/docs/api-reference/environments/get-an-environment.md): Fetch a single environment by its UUID. Pass the owning project's UUID as the required project_id query parameter.
  - [Create an environment (`POST /api/v1/environments`)](https://agnt5.com/docs/api-reference/environments/create-an-environment.md): Create a custom environment beyond the four defaults, for example a per-feature preview environment.
- [Secrets](https://agnt5.com/docs/api-reference/secrets.md): Store, list, and rotate the credentials your deployed workflows read at runtime, scoped to a project and environment.
  - [List secrets (`GET /api/v1/secrets`)](https://agnt5.com/docs/api-reference/secrets/list-secrets.md): List secrets visible to the authenticated user. Values are always masked; use the reveal endpoint to read a decrypted value.
  - [Create a secret (`POST /api/v1/secrets`)](https://agnt5.com/docs/api-reference/secrets/create-a-secret.md): Create a secret. The plaintext value is encrypted at rest and never returned by any endpoint — only its masked form.
  - [Get a secret (`GET /api/v1/secrets/:id`)](https://agnt5.com/docs/api-reference/secrets/get-a-secret.md): Fetch a single secret's metadata by its UUID: its name, type, project and environment scope, and masked value.
  - [Update a secret (`PUT /api/v1/secrets/:id`)](https://agnt5.com/docs/api-reference/secrets/update-a-secret.md): Update an existing secret's name, type, or value by its UUID. A secret is an encrypted credential your deployments read at runtime.
  - [Delete a secret (`DELETE /api/v1/secrets/:id`)](https://agnt5.com/docs/api-reference/secrets/delete-a-secret.md): Delete a secret. Deployments that reference it lose access to the value on their next restart.
- [Deployments](https://agnt5.com/docs/api-reference/deployments.md): List and inspect deployments, and read their logs, workers, components, and runs.
  - [List deployments (`GET /api/v1/deployments`)](https://agnt5.com/docs/api-reference/deployments/list-deployments.md): List deployments the authenticated user can access.
  - [Get a deployment (`GET /api/v1/deployments/:id`)](https://agnt5.com/docs/api-reference/deployments/get-a-deployment.md): Fetch a single deployment by its UUID: one version of a project's code running in one environment.
  - [Deployment logs (`GET /api/v1/deployments/:id/logs`)](https://agnt5.com/docs/api-reference/deployments/deployment-logs.md): Read application logs emitted by a deployment's workers.
  - [Deployment workers (`GET /api/v1/deployments/:id/workers`)](https://agnt5.com/docs/api-reference/deployments/deployment-workers.md): List the worker processes currently executing a deployment's workflows.
  - [Deployment components (`GET /api/v1/deployments/:id/components`)](https://agnt5.com/docs/api-reference/deployments/deployment-components.md): List the functions, workflows, and agents registered by a deployment's workers.
  - [Deployment runs (`GET /api/v1/deployments/:id/runs`)](https://agnt5.com/docs/api-reference/deployments/deployment-runs.md): List the workflow runs executed on a deployment, to see what one version of your project's code has run in its environment.
- [Workers](https://agnt5.com/docs/api-reference/workers.md): List and inspect the worker processes that execute your deployed workflows, agents, and functions.
  - [List workers (`GET /api/v1/workers`)](https://agnt5.com/docs/api-reference/workers/list-workers.md): List workers. Scope the query with either project_id or deployment_id.
  - [Get a worker (`GET /api/v1/workers/:id`)](https://agnt5.com/docs/api-reference/workers/get-a-worker.md): Fetch a single worker by its UUID: a process connected to AGNT5 that executes a deployment's functions, workflows, and agents.
- [Runs & Traces](https://agnt5.com/docs/api-reference/runs-and-traces.md): List workflow runs, read a run's logs, and fetch the distributed trace recorded for each run.
  - [List runs (`GET /api/v1/analytics/runs`)](https://agnt5.com/docs/api-reference/runs-and-traces/list-runs.md): List run summaries: status, timing, retries, and LLM cost for each run.
  - [Get a run (`GET /api/v1/analytics/runs/:run_id`)](https://agnt5.com/docs/api-reference/runs-and-traces/get-a-run.md): Fetch one run's summary by its run ID, scoped by the required project_id: the run's status, timing, retries, and LLM cost.
  - [Run logs (`GET /api/v1/runs/:runId/logs`)](https://agnt5.com/docs/api-reference/runs-and-traces/run-logs.md): Read structured logs emitted during a run, across every worker and step.
  - [List traces (`GET /api/v1/traces`)](https://agnt5.com/docs/api-reference/runs-and-traces/list-traces.md): List distributed traces recorded for a workspace, optionally scoped to a single deployment.
  - [Get a trace (`GET /api/v1/traces/:traceId`)](https://agnt5.com/docs/api-reference/runs-and-traces/get-a-trace.md): Fetch every span recorded for a single trace. A trace ID with no matching spans returns 200 with an empty spans array, not a 404.
  - [Run a component (`POST /v1/:type/:name/run`)](https://agnt5.com/docs/api-reference/runs-and-traces/run-a-component.md): Run a function, workflow, tool, or agent on the gateway and wait for its result.
  - [Start a run (`POST /v1/:type/:name/submit`)](https://agnt5.com/docs/api-reference/runs-and-traces/submit-a-run.md): Start a component run and return its run ID at once, without waiting for the result.
  - [Start and stream a run (`POST /v1/:type/:name/stream`)](https://agnt5.com/docs/api-reference/runs-and-traces/stream-a-run.md): Start a component run and receive its events as Server-Sent Events while it executes.
  - [Run a batch (`POST /v1/:type/:name/batch`)](https://agnt5.com/docs/api-reference/runs-and-traces/run-a-batch.md): Start one run per input item of a function, workflow, tool, or agent in a single request. Returns 202 with a batch ID and every run ID.
  - [List runs (gateway) (`GET /v1/runs`)](https://agnt5.com/docs/api-reference/runs-and-traces/list-gateway-runs.md): List runs with a service key, filtered by status, component, and time.
  - [Get a run (gateway) (`GET /v1/runs/:runId`)](https://agnt5.com/docs/api-reference/runs-and-traces/get-a-gateway-run.md): Fetch one run record with a service key: status, component, timing, and error.
  - [Get run output (`GET /v1/runs/:runId/output`)](https://agnt5.com/docs/api-reference/runs-and-traces/get-run-output.md): Fetch the final output of a completed run with a service key. A run that hasn't finished returns 409, so poll or follow its events first.
  - [Run events (`GET /v1/runs/:runId/events`)](https://agnt5.com/docs/api-reference/runs-and-traces/run-events.md): Follow a run as Server-Sent Events: its durable history first, then the live tail.
  - [Cancel a run (gateway) (`POST /v1/runs/:runId/cancel`)](https://agnt5.com/docs/api-reference/runs-and-traces/cancel-a-gateway-run.md): Cancel a run that is still in progress, using a service key on the gateway. The response returns the run ID with status cancelled.
  - [Resume a workflow (`POST /v1/workflows/resume/:runId`)](https://agnt5.com/docs/api-reference/runs-and-traces/resume-a-workflow.md): Answer a workflow that paused for human input, so it continues from the pause.
- [Datasets](https://agnt5.com/docs/api-reference/datasets.md): Create eval datasets, publish immutable versions, import examples from runs or CSV, and deduplicate items.
  - [List datasets (`GET /api/v1/projects/:projectId/datasets`)](https://agnt5.com/docs/api-reference/datasets/list-datasets.md): List a project's eval datasets, with each one's current published version, draft state, storage mode, and item counts.
  - [Create a dataset (`POST /api/v1/projects/:projectId/datasets`)](https://agnt5.com/docs/api-reference/datasets/create-a-dataset.md): Create an eval dataset in a project with a name and optional description and metadata. Items go into its draft until you publish a version.
  - [Get a dataset (`GET /api/v1/projects/:projectId/datasets/:id`)](https://agnt5.com/docs/api-reference/datasets/get-a-dataset.md): Fetch a single eval dataset by its UUID. A dataset holds a mutable draft of items and a history of immutable published versions.
  - [List versions (`GET /api/v1/projects/:projectId/datasets/:id/versions`)](https://agnt5.com/docs/api-reference/datasets/list-versions.md): List a dataset's immutable published versions, each with its version number, description, item count, and checksum.
  - [Publish a version (`POST /api/v1/projects/:projectId/datasets/:id/versions`)](https://agnt5.com/docs/api-reference/datasets/publish-a-version.md): Publish the current draft as a new immutable version.
  - [Compare versions (`POST /api/v1/projects/:projectId/datasets/:id/versions/compare`)](https://agnt5.com/docs/api-reference/datasets/compare-versions.md): Compare two published versions and see what items were added, removed, or changed.
  - [Restore the draft from a version (`POST /api/v1/projects/:projectId/datasets/:id/versions/:versionId/restore-draft`)](https://agnt5.com/docs/api-reference/datasets/restore-the-draft-from-a-version.md): Reset the mutable draft back to the contents of a published version.
  - [List draft items (`GET /api/v1/projects/:projectId/datasets/:id/examples`)](https://agnt5.com/docs/api-reference/datasets/list-draft-items.md): List the items currently in a dataset's draft: the mutable, unpublished set of input and expected-output pairs.
  - [Add an item (`POST /api/v1/projects/:projectId/datasets/:id/examples`)](https://agnt5.com/docs/api-reference/datasets/add-an-item.md): Add a single item to a dataset's draft by hand, with a required input payload and an optional expected output and metadata.
  - [Get an item (`GET /api/v1/projects/:projectId/datasets/:id/examples/:exampleId`)](https://agnt5.com/docs/api-reference/datasets/get-an-item.md): Fetch a single draft item, including its input/output payload and revision history.
  - [Import from a run (`POST /api/v1/projects/:projectId/datasets/:id/import/run`)](https://agnt5.com/docs/api-reference/datasets/import-from-a-run.md): Add an item to the draft from a completed workflow run, capturing its actual input and output.
  - [Import from CSV (`POST /api/v1/projects/:projectId/datasets/:id/import/csv`)](https://agnt5.com/docs/api-reference/datasets/import-from-csv.md): Bulk-import items from a CSV file, mapping columns to input/expected-output fields.
  - [Preview deduplication (`POST /api/v1/projects/:projectId/datasets/:id/dedup/preview`)](https://agnt5.com/docs/api-reference/datasets/preview-deduplication.md): Preview which draft items would be removed by deduplication, without changing anything.
  - [Apply deduplication (`POST /api/v1/projects/:projectId/datasets/:id/dedup/apply`)](https://agnt5.com/docs/api-reference/datasets/apply-deduplication.md): Remove duplicate draft items identified by a preview.
- [Experiments](https://agnt5.com/docs/api-reference/experiments.md): Create experiments, trigger runs against a dataset, and read run results, failures, and scores.
  - [List experiments (`GET /api/v1/projects/:projectId/experiments`)](https://agnt5.com/docs/api-reference/experiments/list-experiments.md): List a project's experiments, with each one's dataset, type, status, target under test, repetitions, and scorers.
  - [Create an experiment (`POST /api/v1/projects/:projectId/experiments`)](https://agnt5.com/docs/api-reference/experiments/create-an-experiment.md): Create an experiment that runs a component, deployment, or prompt against a dataset, with repetitions and custom or built-in scorers.
  - [Get an experiment (`GET /api/v1/projects/:projectId/experiments/:id`)](https://agnt5.com/docs/api-reference/experiments/get-an-experiment.md): Fetch a single experiment by its UUID. An experiment runs a component, deployment, or prompt against a dataset and scores each result.
  - [Cancel an experiment (`POST /api/v1/projects/:projectId/experiments/:id/cancel`)](https://agnt5.com/docs/api-reference/experiments/cancel-an-experiment.md): Cancel an experiment and every run currently in progress under it.
  - [List runs (`GET /api/v1/projects/:projectId/experiments/:experimentId/runs`)](https://agnt5.com/docs/api-reference/experiments/list-runs.md): List the runs triggered for an experiment. Each run executes the experiment against a dataset version and scores the results.
  - [Trigger a run (`POST /api/v1/projects/:projectId/experiments/:experimentId/runs`)](https://agnt5.com/docs/api-reference/experiments/trigger-a-run.md): Trigger a new run of an experiment against its current dataset version.
  - [Get a run (`GET /api/v1/projects/:projectId/experiments/:experimentId/runs/:runId`)](https://agnt5.com/docs/api-reference/experiments/get-a-run.md): Fetch a single experiment run by its UUID. A run is one execution of an experiment against a dataset version.
  - [Cancel a run (`POST /api/v1/projects/:projectId/experiments/:experimentId/runs/:runId/cancel`)](https://agnt5.com/docs/api-reference/experiments/cancel-a-run.md): Cancel an in-progress run of an experiment. To stop every run under an experiment at once, cancel the experiment instead.
  - [Get run results (`GET /api/v1/projects/:projectId/experiments/:experimentId/runs/:runId/results`)](https://agnt5.com/docs/api-reference/experiments/get-run-results.md): Fetch a run's aggregate results once it completes.
  - [Run summary (`GET /api/v1/projects/:projectId/eval/runs/:runId/summary`)](https://agnt5.com/docs/api-reference/experiments/run-summary.md): Fetch a run's pass/fail counts, average scores, and duration.
  - [Run failures (`GET /api/v1/projects/:projectId/eval/runs/:runId/failures`)](https://agnt5.com/docs/api-reference/experiments/run-failures.md): List the dataset items a run scored below threshold on.
  - [Get a run item (`GET /api/v1/projects/:projectId/eval/runs/:runId/items/:runItemId`)](https://agnt5.com/docs/api-reference/experiments/get-a-run-item.md): Fetch a single item's actual output, expected output, and per-scorer results.
  - [Run scorers (`GET /api/v1/projects/:projectId/eval/runs/:runId/scorers`)](https://agnt5.com/docs/api-reference/experiments/run-scorers.md): List the scorers applied to a run and their aggregate results.
  - [Run CI gate (`GET /api/v1/projects/:projectId/eval/runs/:runId/ci`)](https://agnt5.com/docs/api-reference/experiments/run-ci-gate.md): Fetch the pass/fail gate result for a run, for use in CI pipelines.
  - [List scores (`GET /api/v1/projects/:projectId/eval/scores`)](https://agnt5.com/docs/api-reference/experiments/list-scores.md): List individual scorer results across runs, for building custom dashboards.
  - [Get score evidence (`GET /api/v1/projects/:projectId/eval/scores/:scoreId/evidence`)](https://agnt5.com/docs/api-reference/experiments/get-score-evidence.md): Fetch the full evidence (prompt, model reasoning, or code output) behind a single score.
  - [Journal links (`GET /api/v1/projects/:projectId/eval/journal-links`)](https://agnt5.com/docs/api-reference/experiments/journal-links.md): Fetch links back to the durable execution journal entries behind a run's items, for step-by-step debugging.
  - [Rescore a run (`POST /api/v1/projects/:projectId/eval/runs/:runId/rescore`)](https://agnt5.com/docs/api-reference/experiments/rescore-a-run.md): Score a completed run again with the current scorers, without running the component again.
  - [Create an annotation (`POST /api/v1/projects/:projectId/eval/runs/:runId/items/:runItemId/annotations`)](https://agnt5.com/docs/api-reference/experiments/create-an-annotation.md): Record a human review label on a run item, stored next to the scorer results.
  - [List annotations (`GET /api/v1/projects/:projectId/eval/runs/:runId/items/:runItemId/annotations`)](https://agnt5.com/docs/api-reference/experiments/list-annotations.md): List the human annotations recorded on a run item, newest first.
- [Scorers](https://agnt5.com/docs/api-reference/scorers.md): List and fetch the scorers a project uses to grade experiment results.
  - [List scorers (`GET /api/v1/projects/:projectId/scorers`)](https://agnt5.com/docs/api-reference/scorers/list-scorers.md): List a project's code and LLM-as-judge scorers, with each one's type, version, and whether it is enabled.
  - [Get a scorer (`GET /api/v1/projects/:projectId/scorers/:id`)](https://agnt5.com/docs/api-reference/scorers/get-a-scorer.md): Fetch a single scorer by its UUID. A scorer grades experiment results with deterministic code, an LLM-as-judge prompt, or a built-in.
  - [Create a scorer (`POST /api/v1/projects/:projectId/scorers`)](https://agnt5.com/docs/api-reference/scorers/create-a-scorer.md): Create a scorer record for a custom scorer your worker deploys, so experiments can attach it by ID.
- [Quality Cases](https://agnt5.com/docs/api-reference/quality-cases.md): List, fetch, and open quality cases: tracked behavior regressions linked back to the runs, scores, and datasets that surfaced them.
  - [List quality cases (`GET /api/v1/projects/:projectId/quality/cases`)](https://agnt5.com/docs/api-reference/quality-cases/list-quality-cases.md): List a project's quality cases, with each regression's status, severity, category, source, and expected versus observed behavior.
  - [Create a quality case (`POST /api/v1/projects/:projectId/quality/cases`)](https://agnt5.com/docs/api-reference/quality-cases/create-a-quality-case.md): Open a quality case, optionally linked to the run or score that surfaced it.
  - [Get a quality case (`GET /api/v1/projects/:projectId/quality/cases/:caseId`)](https://agnt5.com/docs/api-reference/quality-cases/get-a-quality-case.md): Fetch a single quality case by its UUID. A quality case tracks one behavior regression from triage to resolution.

## Status codes

| Code | Name | Meaning |
| --- | --- | --- |
| 200 | OK | The request succeeded. |
| 201 | Created | The resource was created. |
| 204 | No Content | The resource was deleted. |
| 400 | Bad Request | A parameter is missing or invalid. |
| 401 | Unauthorized | The API key or token is missing or invalid. |
| 404 | Not Found | The resource doesn't exist. |
| 429 | Too Many Requests | You hit the rate limit. |
| 500 | Server Error | Something went wrong on our side. |