{ "openapi": "3.1.0", "info": { "title": "ORYKSA API", "version": "2026-09-24", "description": "Put the ORYKSA AI employee inside any site or app: chat, knowledge, widget and signed webhooks. Same brain, rules and interaction counting as WhatsApp and the website chat. Docs: https://developer.oryksa.com", "contact": { "name": "ORYKSA", "email": "info@oryksa.com", "url": "https://developer.oryksa.com" }, "termsOfService": "https://oryksa.com/en/terms/", "license": { "name": "Proprietary", "url": "https://oryksa.com/en/terms/" } }, "servers": [ { "url": "https://api.oryksa.com" } ], "tags": [ { "name": "Account", "description": "Plan, usage and account status." }, { "name": "Agent", "description": "Business details and look of the AI agent." }, { "name": "Knowledge", "description": "What the agent knows: pages, website and FAQ." }, { "name": "Chat", "description": "Talk to the agent and read conversations." }, { "name": "Client sessions", "description": "Short-lived tokens so apps can chat without the secret key." }, { "name": "Widget", "description": "Website chat code and allowed domains." }, { "name": "Webhooks", "description": "Signed events sent to your server." } ], "paths": { "/v1": { "get": { "tags": [ "Account" ], "summary": "API info", "operationId": "api_info", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "security": [] } }, "/v1/account": { "get": { "tags": [ "Account" ], "summary": "Get account", "operationId": "get_account", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "Plan, interaction usage, allowed domains and agent status.", "security": [ { "apiKey": [] } ] } }, "/v1/agent": { "patch": { "tags": [ "Agent" ], "summary": "Update agent", "operationId": "update_agent", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "Business details the AI agent uses to answer.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentUpdate" }, "example": { "business_name": "FitTrack", "languages": [ "en", "pt" ], "tone": "friendly" } } } }, "security": [ { "apiKey": [] } ] } }, "/v1/agent/appearance": { "patch": { "tags": [ "Agent" ], "summary": "Update appearance", "operationId": "update_appearance", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "Name, avatar and opening messages of the chat.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Appearance" }, "example": { "greeting": { "en": "Hi! How can I help?" } } } } }, "security": [ { "apiKey": [] } ] } }, "/v1/knowledge": { "get": { "tags": [ "Knowledge" ], "summary": "Get knowledge", "operationId": "get_knowledge", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "What the agent knows (pages, FAQ items, services).", "security": [ { "apiKey": [] } ] } }, "/v1/knowledge/pages": { "put": { "tags": [ "Knowledge" ], "summary": "Replace pages", "operationId": "replace_pages", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "Teach the agent your content. Replaces previous pages.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "pages": { "type": "array", "items": { "$ref": "#/components/schemas/Page" } }, "business_summary": { "type": "string" }, "site_url": { "type": "string" } }, "required": [ "pages" ] }, "example": { "pages": [ { "url": "https://example.com/pricing", "title": "Pricing", "content": "Basic plan 9 EUR per month." } ] } } } }, "security": [ { "apiKey": [] } ] } }, "/v1/knowledge/crawl": { "post": { "tags": [ "Knowledge" ], "summary": "Crawl website", "operationId": "crawl_website", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "Read a public website (up to 30 pages) and learn it.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string" }, "max_pages": { "type": "integer", "maximum": 30 } }, "required": [ "url" ] }, "example": { "url": "https://example.com", "max_pages": 20 } } } }, "security": [ { "apiKey": [] } ] } }, "/v1/knowledge/faq": { "post": { "tags": [ "Knowledge" ], "summary": "Add FAQ", "operationId": "add_faq", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "Add or update question and answer pairs (max 100 per call).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "question": { "type": "string" }, "answer": { "type": "string" } }, "required": [ "question", "answer" ] } } }, "required": [ "items" ] }, "example": { "items": [ { "question": "Do you ship to Spain?", "answer": "Yes, in 2 to 4 days." } ] } } } }, "security": [ { "apiKey": [] } ] } }, "/v1/chat": { "post": { "tags": [ "Chat" ], "summary": "Send message", "operationId": "send_message", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatReply" } } } }, "202": { "description": "Still generating", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatReply" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "Send a customer message and get the AI reply. Waits up to 40 s; returns 202 with status pending if the reply takes longer.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatRequest" }, "example": { "message": "Do you open on Saturdays?", "conversation_id": "user-42", "customer_name": "Ana" } } } }, "security": [ { "apiKey": [] } ] } }, "/v1/conversations": { "get": { "tags": [ "Chat" ], "summary": "List conversations", "operationId": "list_conversations", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 100 }, "description": "" } ], "security": [ { "apiKey": [] } ] } }, "/v1/conversations/{conversation_id}": { "get": { "tags": [ "Chat" ], "summary": "Get conversation", "operationId": "get_conversation", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Conversation" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "parameters": [ { "name": "conversation_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "security": [ { "apiKey": [] } ] } }, "/v1/sessions": { "post": { "tags": [ "Client sessions" ], "summary": "Create client session", "operationId": "create_client_session", "responses": { "201": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientSession" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "Server side only. Returns a short-lived oryk_cs_ token for ONE conversation, safe to give to an app.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "conversation_id": { "type": "string" }, "customer_name": { "type": "string" }, "ttl_minutes": { "type": "integer", "minimum": 5, "maximum": 1440 } } }, "example": { "conversation_id": "user-42", "customer_name": "Ana", "ttl_minutes": 60 } } } }, "security": [ { "apiKey": [] } ] } }, "/v1/client/chat": { "post": { "tags": [ "Client sessions" ], "summary": "Client send message", "operationId": "client_send_message", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatReply" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "Called from the app with the client token. CORS enabled.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "example": { "message": "Hello" } } } }, "security": [ { "clientToken": [] } ] } }, "/v1/client/messages": { "get": { "tags": [ "Client sessions" ], "summary": "Client get messages", "operationId": "client_get_messages", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Conversation" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "security": [ { "clientToken": [] } ] } }, "/v1/client/agent": { "get": { "tags": [ "Client sessions" ], "summary": "Client get agent", "operationId": "client_get_agent", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "Name, avatar, greeting and suggestions for the chat UI.", "security": [ { "clientToken": [] } ] } }, "/v1/conversions": { "post": { "tags": [ "Account" ], "summary": "Report conversion", "operationId": "report_conversion", "responses": { "201": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "Tell ORYKSA that a conversation turned into a sale, lead, signup or booking. The owner is notified and it counts in the owner reports.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "sale", "lead", "signup", "booking" ] }, "amount": { "type": "number" }, "currency": { "type": "string" }, "reference": { "type": "string" }, "conversation_id": { "type": "string" } } }, "example": { "kind": "sale", "amount": 129.9, "currency": "EUR", "reference": "order-4812", "conversation_id": "customer-4812" } } } }, "security": [ { "apiKey": [] } ] } }, "/v1/widget": { "get": { "tags": [ "Widget" ], "summary": "Get widget snippet", "operationId": "get_widget_snippet", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "Website chat code for your framework.", "parameters": [ { "name": "framework", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "html", "nextjs-app", "nextjs-pages", "react", "vue", "nuxt", "astro", "svelte", "angular", "wordpress" ] }, "description": "" }, { "name": "lang", "in": "query", "required": false, "schema": { "type": "string" }, "description": "" }, { "name": "position", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "left", "right" ] }, "description": "" } ], "security": [ { "apiKey": [] } ] } }, "/v1/widget/domains": { "put": { "tags": [ "Widget" ], "summary": "Set allowed domains", "operationId": "set_allowed_domains", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "Restrict the website chat to these domains (empty list = any).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "domains": { "type": "array", "items": { "type": "string" } } }, "required": [ "domains" ] }, "example": { "domains": [ "example.com" ] } } } }, "security": [ { "apiKey": [] } ] } }, "/v1/webhooks": { "get": { "tags": [ "Webhooks" ], "summary": "List webhooks", "operationId": "list_webhooks", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "security": [ { "apiKey": [] } ] }, "post": { "tags": [ "Webhooks" ], "summary": "Create webhook", "operationId": "create_webhook", "responses": { "201": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Webhook" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "The response includes the signing secret (shown once).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string" }, "events": { "type": "array", "items": { "type": "string" } } }, "required": [ "url" ] }, "example": { "url": "https://example.com/oryksa/webhook", "events": [ "message.replied", "booking.created" ] } } } }, "security": [ { "apiKey": [] } ] } }, "/v1/webhooks/{webhook_id}": { "delete": { "tags": [ "Webhooks" ], "summary": "Delete webhook", "operationId": "delete_webhook", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "parameters": [ { "name": "webhook_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "security": [ { "apiKey": [] } ] } }, "/v1/webhooks/{webhook_id}/test": { "post": { "tags": [ "Webhooks" ], "summary": "Test webhook", "operationId": "test_webhook", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "Sends a signed webhook.test event.", "parameters": [ { "name": "webhook_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "security": [ { "apiKey": [] } ] } } }, "webhooks": { "event": { "post": { "summary": "Event delivered to your endpoint", "description": "Header ORYKSA-Signature: t=,v1=.\")>.", "operationId": "webhook_event", "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Event" } } } }, "responses": { "200": { "description": "Acknowledged" } } } } }, "components": { "securitySchemes": { "apiKey": { "type": "http", "scheme": "bearer", "bearerFormat": "oryk_live_...", "description": "Secret key from Account > Developer. Server side only." }, "clientToken": { "type": "http", "scheme": "bearer", "bearerFormat": "oryk_cs_...", "description": "Short-lived token from POST /v1/sessions. Safe inside apps." } }, "schemas": { "Error": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "upgrade_url": { "type": "string" }, "retry_after": { "type": "integer" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] }, "AgentUpdate": { "type": "object", "properties": { "business_name": { "type": "string" }, "agent_name": { "type": "string" }, "business_description": { "type": "string" }, "services": { "type": "array", "items": { "type": "string" } }, "prices": { "type": "object", "additionalProperties": { "type": "string" } }, "languages": { "type": "array", "items": { "type": "string" } }, "tone": { "type": "string" }, "message_style": { "type": "string" }, "conversation_goal": { "type": "string" }, "restrictions": { "type": "string" }, "timezone": { "type": "string" }, "country": { "type": "string" } } }, "Appearance": { "type": "object", "properties": { "agent_name": { "type": "string" }, "gender": { "type": "string", "enum": [ "female", "male" ] }, "avatar_url": { "type": "string" }, "greeting": { "type": "object", "description": "Text per language, e.g. {\"en\": \"Hi!\", \"pt\": \"Olá!\"}", "additionalProperties": { "type": "string" } }, "subtitle": { "type": "object", "description": "Text per language, e.g. {\"en\": \"Hi!\", \"pt\": \"Olá!\"}", "additionalProperties": { "type": "string" } }, "suggestions": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } } }, "Page": { "type": "object", "properties": { "url": { "type": "string" }, "title": { "type": "string" }, "content": { "type": "string" } }, "required": [ "title", "content" ] }, "ChatRequest": { "type": "object", "properties": { "message": { "type": "string", "minLength": 1, "maxLength": 2000 }, "conversation_id": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,64}$" }, "customer_name": { "type": "string" } }, "required": [ "message" ] }, "ChatReply": { "type": "object", "properties": { "object": { "const": "chat_reply" }, "conversation_id": { "type": "string" }, "status": { "type": "string", "enum": [ "replied", "pending" ] }, "reply": { "type": [ "string", "null" ] }, "hint": { "type": "string" } } }, "Message": { "type": "object", "properties": { "role": { "type": "string", "enum": [ "user", "assistant" ] }, "content": { "type": "string" } } }, "Conversation": { "type": "object", "properties": { "object": { "const": "conversation" }, "id": { "type": "string" }, "messages": { "type": "array", "items": { "$ref": "#/components/schemas/Message" } } } }, "ClientSession": { "type": "object", "properties": { "object": { "const": "client_session" }, "client_token": { "type": "string" }, "conversation_id": { "type": "string" }, "expires_at": { "type": "string", "format": "date-time" } } }, "Webhook": { "type": "object", "properties": { "object": { "const": "webhook" }, "id": { "type": "string" }, "url": { "type": "string" }, "events": { "type": "array", "items": { "type": "string" } }, "active": { "type": "boolean" }, "secret": { "type": "string", "description": "Only returned when created." }, "created_at": { "type": "string" }, "last_delivery_at": { "type": "string" }, "last_status": { "type": "integer" }, "failures": { "type": "integer" } } }, "Event": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "message.replied", "booking.created", "limit.reached", "knowledge.updated", "webhook.test" ] }, "created_at": { "type": "string", "format": "date-time" }, "data": { "type": "object" } } } }, "responses": { "BadRequest": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Unauthorized": { "description": "Missing or invalid key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "PaymentRequired": { "description": "Plan limit or feature not in plan", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "RateLimited": { "description": "Too many requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }