Unified API: Requirements & Usage

Basic Requirements

• Content-Type: application/json header when sending JSON bodies.
• Include your api_key or auth_token in the request body according to the endpoint requirements.

Example Body with Auth Token

JSON
Copy
{
  "auth_token": "USERID:TIMESTAMP:RANDOM",
  "action": "get_credits"
}

Example Body with API Key

JSON
Copy
{
  "operation": "message",
  "params": { "message": "Hello!" },
  "api_key": "YOUR_API_KEY",
  "agent_id": "YOUR_AGENT_ID"
}

The API provides two types of WebSocket connections for each request:

1. Session-specific WebSocket URL: Receives responses only for a specific request

Copy
ws://broker-url/ws/user?session_id=SESSION_ID&api_key=BROKER_API_KEY

1. Persistent WebSocket URL: Receives all events for an agent

Copy
ws://broker-url/ws/agent_stream?agent_id=AGENT_ID&broker_key=BROKER_API_KEY&agent_key=YOUR_API_KEY

Both URLs are returned in the API response for /operation and /upload_file endpoints. For HTTPS, use wss:// instead of ws://.

Different endpoints require different authentication methods:

• Auth Token Required: /info, /createapikey, /delete_agent, /agent_history
• API Key Required: /operation, /upload_file, WebSocket connections

Incorrect authentication will result in a 401 Unauthorized response. API keys must be valid and associated with sufficient credits.

Operations have specific agent status requirements:

• Message Operations: Require agent status to be "running". Cannot send messages to agents with status "thinking" or any other status.
• Other Operations: Allow both "running" and "thinking" statuses.

Attempting an operation on an agent with the wrong status will result in a 409 Conflict response.