REST API reference

The Elnora core REST API is the programmatic surface behind the CLI, the MCP server, and the app. Everything you can do in the dashboard, you can do over HTTP.

• Base URL: https://platform.elnora.ai/api/v1
• Format: JSON request and response bodies. Resource ids are UUIDs.
• Auth: an API key in the X-API-Key header (see Authentication).

Authentication

Send your API key on every request:

curl https://platform.elnora.ai/api/v1/tasks \
  -H "X-API-Key: $ELNORA_API_KEY"

You can equivalently send Authorization: Bearer <your-key>. Interactive clients (including the MCP server) may use OAuth 2.1 instead. Requests act on your active organization; some endpoints accept an explicit organization id to target another org you belong to. Tasks are readable only by the account that created them, and file endpoints return a file only when your account has access to it — a key acts with its creator's access, so create a key under the account whose view of the data your integration needs.

Conventions

• Pagination — list endpoints take page and pageSize (max 100); message history uses cursor pagination (Cursor / Limit).
• Versioning — the API is versioned in the path (/api/v1).

Errors

Errors use standard HTTP status codes with a consistent JSON body:

{
  "errorCode": "NOT_FOUND",
  "messages": ["Task not found."],
  "correlationId": "b1f2…"
}

errorCode is a stable machine-readable string (e.g. BAD_REQUEST, UNAUTHORIZED, FORBIDDEN, NOT_FOUND, FILE_EXPIRED, VERSION_CONFLICT, INSUFFICIENT_SCOPE, ORGANIZATION_ACCESS_REVOKED, RATE_LIMIT_EXCEEDED); messages is safe to show a user; correlationId identifies the request in our logs — include it when contacting support. Common statuses: 400 an invalid or malformed request (including validation errors), 401 unauthenticated, 403 not permitted for your role, 404 not found, 409 a version conflict (re-read and retry).

Two 403s are worth handling on their own, because retrying will not help: INSUFFICIENT_SCOPE means the API key may not call that endpoint (see Authentication), and ORGANIZATION_ACCESS_REVOKED means the token's access to the organization has ended and an interactive client needs to authorize again. Both are written before a request reaches the endpoint, so they carry errorCode and messages but no correlationId.

When you create a task or send a message that references a file which has since been archived or expired, the 404 uses errorCode: "FILE_EXPIRED" and adds a missingFileIds array listing exactly which ids failed, so you can re-upload them and retry in one round-trip.

Rate limits

The API is rate limited per client. When you exceed a limit you get 429 Too Many Requests with a Retry-After header (seconds to wait) and the error body above with errorCode: "RATE_LIMIT_EXCEEDED". Back off and retry after the indicated delay; for bulk work, prefer batch endpoints and a modest concurrency.

A first request

Check connectivity and build provenance (no auth required):

curl https://platform.elnora.ai/api/v1/version

Create a task and send the agent a message:

# 1. Create a task
curl -X POST https://platform.elnora.ai/api/v1/tasks \
  -H "X-API-Key: $ELNORA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "title": "Optimize transfection" }'

# 2. Send a message; the agent works on it asynchronously
curl -X POST https://platform.elnora.ai/api/v1/tasks/<task-uuid>/messages \
  -H "X-API-Key: $ELNORA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "content": "Optimize a HEK293 transfection protocol for higher yield" }'

# 3. Read the reply — poll the task's messages until the agent responds.
#    Cursor pagination: pass ?Cursor=<nextCursor>&Limit=50 to page.
curl https://platform.elnora.ai/api/v1/tasks/<task-uuid>/messages \
  -H "X-API-Key: $ELNORA_API_KEY"

# Files you attached to the chat stay scoped to the task.
curl https://platform.elnora.ai/api/v1/tasks/<task-uuid>/attachments \
  -H "X-API-Key: $ELNORA_API_KEY"

# Files the agent produced land in your knowledge base — browse it from its roots.
curl https://platform.elnora.ai/api/v1/folders/roots \
  -H "X-API-Key: $ELNORA_API_KEY"

Resources