# Agenta API

The Agenta REST API: base URLs, authentication, an example request, and the OpenAPI specification.

Canonical HTML page: <https://agenta.ai/api>

## When to use Agenta

- Build an agent from a plain-language description, then improve it with feedback from real runs.
- Version prompts, skills, and tools like code, and roll back to any earlier revision.
- Evaluate a change against a test set before it ships, with LLM-as-a-judge or your own evaluators.
- Trace every run to see each step, its cost, and where it failed.
- Run an agent on a schedule, or when an event happens in a connected app.
- Put a human approval step in front of consequential actions.

## When not to use Agenta

- A single model call with no versioning, evaluation, or tracing: call the model provider directly.
- Hosting or serving a model. Agenta orchestrates and observes agents; it is not an inference provider.

## How to call it

- REST API: https://us.cloud.agenta.ai/api (US) or https://eu.cloud.agenta.ai/api (EU). Self-hosted: $AGENTA_HOST/api.
- Authenticate with `Authorization: ApiKey $AGENTA_API_KEY`. A key is scoped to one project, so no project_id parameter is needed.
- Full machine-readable surface: https://agenta.ai/openapi.json (OpenAPI 3.1).
- Python SDK: `pip install agenta`.
- Endpoint reference and guides: https://agenta.ai/api and https://docs.agenta.ai.

## Example request

```bash
curl -X POST "https://us.cloud.agenta.ai/api/simple/workflows/query" \
  -H "Content-Type: application/json" \
  -H "Authorization: ApiKey $AGENTA_API_KEY" \
  -d '{}'
```

An API key is scoped to a single project, so endpoints take no `project_id`.
Create one in your project settings on https://cloud.agenta.ai/.

---

## Machine-readable

- [Sitemap](https://agenta.ai/sitemap-index.xml)
- [llms.txt](https://agenta.ai/llms.txt)
- [OpenAPI specification](https://agenta.ai/openapi.json)
- [Documentation](https://docs.agenta.ai)

Every page on https://agenta.ai serves this representation when requested with
`Accept: text/markdown`.