Getting Started

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 Ergon 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.

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": "eyJhbGciOiJIUzI1NiIs...",
  "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 eyJhbGciOiJIUzI1NiIs..."

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

Common Headers

Error Handling

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

{
  "detail": "Not found"
}

Pagination

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

Paginated responses include a total count:

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

WebSockets

Several services provide real-time updates via WebSocket connections. Authenticate by passing your access token as a query parameter.

# Agent conversation streaming
wscat -c "wss://platform.ergondata.ai/api/v1/conversations/ws/conversations/{conversation_id}/stream?token={access_token}"

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

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

# Worksheet collaboration
wscat -c "wss://platform.ergondata.ai/api/v1/worksheets/ws/worksheets/{worksheet_id}/live?token={access_token}"