Skip to navigation
Overview

API Reference

Programmatic access to the Ellaworks platform
View as Markdown

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:

HeaderExample
X-API-KeyX-API-Key: YOUR_API_KEY
AuthorizationAuthorization: Bearer YOUR_API_KEY
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:

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 for setup and security guidance.

API keys are scoped to your organization. To create one, see API Keys.

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.

RoutesWhy
/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 /registriesNot 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:

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

Writes take a JSON body:

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:

StatusMeaning
200Success
400Bad request — check your input parameters
401Unauthorized — missing or invalid API key
403Forbidden — valid key but insufficient permissions
404Not found — resource does not exist
429Rate limited — slow down and retry
500Internal 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 on the Ellaworks platform
  2. Generate an API key from your account settings
  3. Explore the endpoints in the sidebar to start building