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:

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:

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

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

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.

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:

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

Writes take a JSON body:

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:

Error responses include a message field describing the issue.

Available Resources

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:

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 on the Ellaworx platform
2. Generate an API key from your account settings
3. Explore the endpoints in the sidebar to start building