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

# API Reference

The Ellaworx 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://platform.ellaworx.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://platform.ellaworx.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://platform.ellaworx.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                                                                                                                                                                            |
| --------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `GET`, `POST /api-keys`                                               | A key that could mint or list keys would weaken revocation. `DELETE /api-keys/{apiKeyId}` does accept a key, for that key's own id only (see below).                           |
| `/onboarding/*`                                                       | Onboarding belongs to a signed-in person, and a proposal is accepted only by a human in a browser session.                                                                     |
| `PATCH /decisions/settings`                                           | What the decision log keeps of customers' inputs is an administrator's choice, made in a browser session; a key cannot change it. `GET /decisions/settings` does accept a key. |
| `/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.                                                                                                                                                 |
| `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`.

### Revoking a key with the key itself

`DELETE /api-keys/{apiKeyId}` accepts an API key so that a client can log out:
a key may delete **itself and nothing else**. Any other id, including another
key of the same owner, returns `403` with `data.code: "API_KEY_SELF_REVOKE_ONLY"`.
A signed-in browser session may delete any key its user owns; a key owned by
someone else returns `404`. The key stops working on the next request, which
gets `401` with `data.code: "API_KEY_INVALID"`.

## 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://platform.ellaworx.ai/api/agents?orgSlug=your-org" \
  -H "X-API-Key: YOUR_API_KEY"
```

Writes take a JSON body:

```bash
curl -X POST https://platform.ellaworx.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.

#### Decisions

Run published decision schemas for typed yes/no, pick and score answers, and read the execution log and statistics.

## Running a decision

A decision is a typed answer (`true` or `false`, one of your options, or a number on a scale) from a published decision schema. Customer code runs one through the gateway endpoint, which is a proxy route and so is not in the generated reference:

```bash
curl -X POST "https://platform.ellaworx.ai/api/proxy/your-org/prod/decisions" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "schema": "support/duplicate-charge@1",
    "inputs": { "ticket": "I was charged twice for my order." }
  }'
```

`schema` is `registry/name@version`; the version defaults to the latest and accepts ranges such as `^1`. The answer carries the `decision`, the `probabilities` and `confidence`, the schema version that ran, and every provider attempt. The environment (`prod` here) decides the variables the instructions can use and which providers run first and which follow a failure: a run falls back to the next provider when one fails, unless the request names a `provider` or `model`.

The endpoint takes an unscoped organization API key; a key issued by `agx login` is refused with `401`. The same decision runs from the API as `POST /decisions/executions`, and every run is recorded: see `GET /decisions/executions` and `GET /decisions/statistics` in this reference.

## Getting Started

If you haven't set up API access yet:

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