API overview

REST over HTTPS, JSON in and out, one base URL: https://api.oryksa.com/v1

Try the API in the browser: API console.

OpenAPI and Postman

The full API is described in an OpenAPI 3.1 file. Import it into Postman, Insomnia or any code generator, or use the ready-made Postman collection (set the apiKey variable to your key).

OpenAPI 3.1 (JSON) Postman collection updated 2026-09-28

Endpoints

Method	Endpoint	Description
GET	`/v1/account`	Plan, usage and agent summary
PATCH	`/v1/agent`	Business profile of the AI employee
PATCH	`/v1/agent/appearance`	Name, photo, greeting, suggestions
GET	`/v1/knowledge`	What the agent knows
PUT	`/v1/knowledge/pages`	Replace the site content
POST	`/v1/knowledge/crawl`	Read a live site
POST	`/v1/knowledge/faq`	Add or update FAQs
POST	`/v1/chat`	Customer message in, AI reply out
GET	`/v1/conversations`	API conversations
GET	`/v1/conversations/{id}`	Messages of one conversation
POST	`/v1/sessions`	Short-lived token for an app user
GET/POST	`/v1/client/*`	In-app chat with the session token
GET	`/v1/widget`	Website chat snippet
PUT	`/v1/widget/domains`	Lock the chat to your domains
GET/POST	`/v1/webhooks`	List or create webhooks
DELETE	`/v1/webhooks/{id}`	Delete a webhook
POST	`/v1/webhooks/{id}/test`	Send a test event

Errors

Errors always come with a machine-readable code and a human-readable message:

{
  "error": {
    "code": "interaction_limit_reached",
    "message": "The plan's interaction limit for this period is used up.",
    "upgrade_url": "https://app.oryksa.com/billing"
  }
}

HTTP	Code	Meaning
400	`invalid_request`	A field is missing or invalid.
401	`unauthorized`	Missing, wrong or revoked API key.
402	`plan_required`	The channel is not included in the plan (see upgrade_url).
402	`interaction_limit_reached`	The plan's interactions for this period are used up.
403	`account_inactive`	The account that owns the key is not active.
404	`not_found`	The resource does not exist.
409	`agent_not_configured`	Set up the agent first with PATCH /v1/agent.
422	`crawl_failed`	The site could not be read (for example it only renders in the browser).
429	`rate_limited`	Too many requests. Wait retry_after seconds.
503	`agent_unavailable`	The owner turned the AI off for this channel.

Rate limits

Per API key: 120 requests per minute. Chat: 30 messages per minute per account. Reading pages: 20 per hour. Reading a live site: 10 per hour. Above the limit the API answers 429 rate_limited.

Plans and interactions

The API is a channel like the website chat: it needs a plan with web channels (the developer bonus of accounts connected through the MCP also includes it). Each AI reply counts as one interaction of the plan, with the same limits as WhatsApp. Knowledge, agent and conversation endpoints do not use interactions.