Getting Started

Everything you need to start building with the platform API.

Authentication

All API requests require a Bearer token in the Authorization header. Authenticate using API keys with the client credentials flow.

Obtaining API Keys

Create API keys in the console under IAM → API Keys. Each API key consists of a client_id and a client_secret. You can scope API keys to specific services and set expiration dates.

Your client_secret is only shown once at creation time. Store it securely — it cannot be retrieved later.

Getting an Access Token

Exchange your API key credentials for a short-lived access token:

curl -X POST https://platform.ergondata.ai/v1/auth/token \
  -H "Content-Type: application/json" \
  -d '{
    "client_id": "your-client-id",
    "client_secret": "your-client-secret"
  }'

Response:

{
  "access_token": "<access-token>",
  "token_type": "bearer",
  "expires_in": 3600
}

Using the Token

Include the access token as a Bearer token in the Authorization header of every request:

curl https://platform.ergondata.ai/api/v1/agents/companies/{company_id}/llm-configs \
  -H "Authorization: Bearer <access-token>"

Tokens expire after the duration specified in expires_in (seconds). Request a new token when the current one expires.

Base URL

All API requests are made to the following base URL. Each service is accessed via its own path prefix:

https://platform.ergondata.ai
ServiceAPI PrefixExample
IAM/v1/authhttps://platform.ergondata.ai/v1/auth/token
Agent Hub/api/v1/agentshttps://platform.ergondata.ai/api/v1/agents/llm-providers
Workflows/api/v1/workflowshttps://platform.ergondata.ai/api/v1/workflows/...
Automations/api/v1/automationshttps://platform.ergondata.ai/api/v1/automations/...
Channels/api/v1/channelshttps://platform.ergondata.ai/api/v1/channels/...
Buckets/api/v1/bucketshttps://platform.ergondata.ai/api/v1/buckets/...
Worksheets/api/v1/worksheetshttps://platform.ergondata.ai/api/v1/worksheets/...
Conversations/api/v1/conversationshttps://platform.ergondata.ai/api/v1/conversations/...
Event Streams/api/v1/event-streamshttps://platform.ergondata.ai/api/v1/event-streams/...

Common Headers

Required Headers

NameTypeDescription
Authorization*
stringBearer token from the client credentials endpoint. Format: "Bearer {token}"
Content-Type*
stringSet to application/json for all request bodies.Default: application/json
x-company-id
string (UUID)Required by some Channels endpoints. Specifies which organization context to operate in.

Error Handling

The API uses standard HTTP status codes. Errors return a JSON body with a detail field describing the issue.

{
  "detail": "Not found"
}
CodeStatusDescription
200OKRequest succeeded.
201CreatedResource was created successfully.
202AcceptedRequest accepted for asynchronous processing.
204No ContentSuccessful deletion, no response body.
400Bad RequestInvalid request parameters.
401UnauthorizedMissing or invalid authentication token, or a sign-in that has not selected a company (company_token_required).
403ForbiddenInsufficient permissions for this action.
404Not FoundThe requested resource does not exist.
422Unprocessable EntityRequest body failed validation.
500Internal Server ErrorAn unexpected error occurred.

A 403 with detail console_access_denied means the signed-in member does not have console access in that company: they may use the apps shared with them, but not call the API directly. Any service can return it. See Sign-in and access.

Pagination

List endpoints support offset-based pagination using limit and offset query parameters. Some endpoints use page and limit instead.

Pagination Parameters

NameTypeDescription
limit
integerMaximum number of results to return.Default: 50
offset
integerNumber of results to skip.Default: 0
page
integerPage number (1-based). Used by activity endpoints.Default: 1

Paginated responses include a total count:

{
  "items": [...],
  "total": 142,
  "limit": 50,
  "offset": 0
}

WebSockets

Several services provide real-time updates via WebSocket connections. Never put the access token in the URL. Workflows, buckets, worksheets and event streams take it in the Sec-WebSocket-Protocol header as access_token.<token>; conversation streams take it as the first message, {"token": "<token>"}.

# Workflow live updates
wscat -c "wss://platform.ergondata.ai/api/v1/workflows/ws/workflows/{workflow_id}/live" -s "access_token.{access_token}"

# Buckets live updates
wscat -c "wss://platform.ergondata.ai/api/v1/buckets/ws/buckets/{bucket_id}/live" -s "access_token.{access_token}"

# Worksheet row changes
wscat -c "wss://platform.ergondata.ai/api/v1/worksheets/ws/worksheets/{worksheet_id}/live" -s "access_token.{access_token}"

# Agent conversation streaming: once connected, send {"token": "{access_token}"} as the first message
wscat -c "wss://platform.ergondata.ai/api/v1/conversations/ws/conversations/{conversation_id}/stream"
ServiceWebSocket PathPurpose
Conversations/api/v1/conversations/ws/conversations/{id}/streamStream conversation messages in real-time
Workflows/api/v1/workflows/ws/workflows/{id}/liveItem changes on a workflow board (phases you can view)
Workflows/api/v1/workflows/ws/workflow-views/{id}/liveItem changes in a saved workflow view
Buckets/api/v1/buckets/ws/buckets/{id}/liveFile and folder changes in a bucket, including processing status
Worksheets/api/v1/worksheets/ws/worksheets/{id}/liveRow changes in a worksheet
Worksheets/api/v1/worksheets/ws/worksheet-views/{id}/liveRow changes in a saved worksheet view
Event Streams/api/v1/event-streams/ws/companies/{id}/liveCentralized event stream for a company