Use the Zeus API from your server to create intents, submit incoming chat messages, and retrieve conversation history. The base URL is:
https://api.openfi.tech
Overview
All current endpoints use API version v1. Requests and responses use JSON,
except that GET query parameters are URL encoded.
Keep API calls on your server. For a complete chat integration, combine the API with webhooks and follow the server-to-server messaging guide.
Authentication
Send your account-scoped API key in the x-api-key header. API keys can be
managed in the Zeus Dashboard.
x-api-key: YOUR_API_KEY
Keep the key in a secret manager or server environment variable. Never
expose it in browser or mobile application code. Missing or invalid keys
return 401 Unauthorized.
Conversation identity
A conversation thread for the message endpoints is identified by two account-scoped values:
| Field | Description |
|---|---|
agentChannelId | The Zeus-issued ID of the configured API agent channel handling the conversation. |
contactChannelExternalId | Your stable identifier for the end user or chat session. |
predefinedAgentChannelId on POST /v1/intents refers to the same
configured channel as agentChannelId on the message endpoints. For an API
conversation, supply your stable external identifier in
contact.communicationChannels[].id, then use that same value as
contactChannelExternalId. Despite its request-field name, this is your
external identifier, not a Zeus internal channel ID.
Endpoints
| Endpoint | Purpose | Success |
|---|---|---|
POST /v1/intents | Create or reuse an applicable intent, optionally with contact and intent attributes. | 201 Created |
POST /v1/messages | Durably accept an incoming message for asynchronous processing. | 202 Accepted |
GET /v1/messages | Retrieve paginated history for an API conversation thread. | 200 OK |
Rate limits
Rate limits are scoped to the Zeus account and counted independently for each endpoint. Traffic to one endpoint does not consume another endpoint's allowance.
| Endpoint | Limit | Block after exceeding the limit |
|---|---|---|
POST /v1/intents | 5,000 per hour | 1 hour |
POST /v1/messages | 1,200 per hour | 1 hour |
GET /v1/messages | 10,000 per 24 hours | 24 hours |
Authenticated attempts count toward the applicable allowance, including
requests rejected by validation. Responses include X-RateLimit-Limit,
X-RateLimit-Remaining, and X-RateLimit-Reset. A blocked request returns
429 Too Many Requests; use Retry-After to decide when to retry.
Errors
| Status | Meaning |
|---|---|
400 Bad Request | The request contains missing or invalid fields. |
401 Unauthorized | The x-api-key header is missing or invalid. |
404 Not Found | The requested API agent channel is unavailable to the account. This applies to message endpoints. |
409 Conflict | The request conflicts with current state. See the endpoint page for the specific condition. |
429 Too Many Requests | The account exceeded the endpoint rate limit. |
500 Internal Server Error | An unexpected error occurred. Follow the endpoint-specific retry guidance before repeating a write. |