> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.ellaworks.ai/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.ellaworks.ai/_mcp/server.

# API Reference

The Ellaworks API lets you manage registries, agents, environments, deployments, and more from your own tooling, CI/CD pipelines, or custom integrations.

## Base URL

All API endpoints are available at:

```
https://app.ellaworks.ai/api
```

## Authentication

Include your API key on each request using one of these headers:

| Header          | Example                              |
| --------------- | ------------------------------------ |
| `X-API-Key`     | `X-API-Key: YOUR_API_KEY`            |
| `Authorization` | `Authorization: Bearer YOUR_API_KEY` |

```bash
curl -H "X-API-Key: YOUR_API_KEY" \
  "https://app.ellaworks.ai/api/environments?orgSlug=your-org"
```

SDKs that default to Bearer auth can pass the same key without a custom header:

```bash
curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://app.ellaworks.ai/api/environments?orgSlug=your-org"
```

If both headers are sent, `X-API-Key` takes precedence. See [API Keys](/api-keys) for setup and security guidance.

API keys are scoped to your organization. To create one, see [API Keys](/api-keys).

> **Note**
>
> Public prompt registries can be accessed without authentication. Private registries require a valid API key belonging to the same organization.

### Endpoints that require a browser session

A small number of endpoints accept only a signed-in browser session, not an
API key. Each endpoint's reference page lists the authentication it accepts —
check there rather than assuming a key works everywhere.

| Routes                                                                | Why                                                                                   |
| --------------------------------------------------------------------- | ------------------------------------------------------------------------------------- |
| `/api-keys` (all methods)                                             | A key that could mint or revoke keys would weaken revocation.                         |
| `/audit-logs`, `/audit-logs/{eventId}`                                | Not yet available to API keys.                                                        |
| `/deployments`, `/deployments/heatmap`, `/deployments/{deploymentId}` | Not yet available to API keys.                                                        |
| `/fleets` and `/fleets/{fleetId}` (all methods)                       | Not yet available to API keys.                                                        |
| `/knowledge-bases` and its sub-resources (all methods)                | Not yet available to API keys.                                                        |
| `POST`, `PATCH`, `DELETE /registries`                                 | Not yet available to API keys. Registry reads and artifact operations do accept keys. |

Note that `/deployments*` is the deployment **history** resource. The agent
deployment routes — `POST /agents/deployments`, `POST /agents/tool-deployments`,
and `GET /agents/{stableKey}/deployment-history` — all accept API keys.

Calling one of these with a key returns `401`.

## Request Format

The API is REST-shaped: `GET` reads, `POST` creates, `PATCH` updates, `DELETE`
removes. Reads take their arguments as query parameters:

```bash
curl "https://app.ellaworks.ai/api/agents?orgSlug=your-org" \
  -H "X-API-Key: YOUR_API_KEY"
```

Writes take a JSON body:

```bash
curl -X POST https://app.ellaworks.ai/api/tools \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"orgSlug": "your-org", "name": "my-tool", "type": "function", "version": "1.0.0", "providerConfig": {"vapi": {}}}'
```

## Error Handling

The API returns standard HTTP status codes:

| Status | Meaning                                            |
| ------ | -------------------------------------------------- |
| `200`  | Success                                            |
| `400`  | Bad request — check your input parameters          |
| `401`  | Unauthorized — missing or invalid API key          |
| `403`  | Forbidden — valid key but insufficient permissions |
| `404`  | Not found — resource does not exist                |
| `429`  | Rate limited — slow down and retry                 |
| `500`  | Internal error — contact support if persistent     |

Error responses include a `message` field describing the issue.

## Available Resources

#### Registry

Publish, list, and retrieve versioned prompt artifacts from registries.

#### Agents

Create, configure, and deploy AI agents with provider settings and tool references.

#### Environments

Manage deployment environments, provider credentials, and secrets.

#### Deployments

View deployment history, status, and heatmaps across your infrastructure.

#### Fleets

Group and manage agent configurations across environments.

#### LLM Providers

Configure connections to OpenAI, Anthropic, Google, OpenRouter, and custom providers.

## Getting Started

If you haven't set up API access yet:

1. [Create an account](/creating-an-account) on the Ellaworks platform
2. [Generate an API key](/api-keys) from your account settings
3. Explore the endpoints in the sidebar to start building