Programmatic access to everything in Orckai. Manage agents, trigger workflows, search knowledge bases, stream chat responses, and deploy MCP servers through a RESTful interface with 42 endpoints, 18 permission scopes, and full OpenAPI 3.0 documentation.
Every capability in the Orckai platform is exposed through a consistent REST interface. CRUD operations, execution triggers, search, and streaming are all available via API.
List, create, update, and delete AI agents. Execute agents with custom inputs and retrieve conversation history. Configure model selection, system prompts, tools, and runtime mode per agent.
Build multi-step workflows with up to 7 step types. Trigger executions via API, retrieve run history with step-level output, and manage schedules, webhooks, and file-drop triggers programmatically.
Upload documents in 50+ formats. Perform vector similarity search with configurable top-k and threshold. Manage embeddings, list indexed files, and delete individual documents from a knowledge base.
Send messages to any configured agent and receive streaming or synchronous responses. Resume conversations with full history context. Attach knowledge base context for RAG-powered responses with inline citations.
Generate Model Context Protocol servers from database connections or API specifications. Deploy as Docker containers, discover available tools, and invoke them through the API. Manage lifecycle and networking.
Manage prompt templates with variable interpolation. List, create, update, and delete templates. Associate templates with widgets for consistent, branded AI interactions across your applications.
Every API key in Orckai is scoped to your organization and carries only the permissions you assign. Keys use the oak_ prefix for easy identification and are hashed with SHA-256 before storage, so the full key is only visible at creation time.
Choose from 18 permission scopes to follow the principle of least privilege. A CI/CD pipeline that only triggers workflows needs workflows:execute and nothing else. A dashboard that reads agent metrics needs agents:read only.
# Create a scoped API key via the dashboard, # then authenticate every request: curl -X GET https://orckai.app/api/v1/agents \ -H "X-API-Key: oak_your_key_here" # Response { "success": true, "data": [ { "id": "a1b2c3d4-...", "name": "Customer Support Agent", "model": "claude-sonnet-4-20250514", "runtime": "super", "tools": ["search_kb", "create_ticket"] } ] }
Chat and agent execution endpoints support Server-Sent Events (SSE) for token-by-token streaming. Your application receives each token as it is generated, enabling responsive interfaces with sub-second time-to-first-token.
SSE works over standard HTTP, so there are no WebSocket upgrades or special client libraries required. Set Accept: text/event-stream and read the stream. Each event carries a chunk of the response, and the final event includes token usage and cost metadata.
# Stream a chat response in real time curl -N -X POST https://orckai.app/api/v1/chat \ -H "X-API-Key: oak_your_key_here" \ -H "Accept: text/event-stream" \ -H "Content-Type: application/json" \ -d '{ "agentId": "a1b2c3d4-...", "message": "Summarize last week sales", "knowledgeBaseId": "kb-9f8e7d..." }' # SSE stream output data: {"type":"token","content":"Last"} data: {"type":"token","content":" week"} data: {"type":"token","content":" total"} data: {"type":"token","content":" revenue..."} data: {"type":"done","tokens":247,"cost":0.0031}
Every API key is subject to configurable rate limits that protect your infrastructure and prevent runaway costs. Default limits are set at 100 requests per minute per key, with higher tiers available on Team and Enterprise plans.
When a key exceeds its limit, the API returns a 429 Too Many Requests response with a Retry-After header indicating how many seconds to wait. Rate limit state is tracked per key with sub-millisecond lookup, with no impact on request latency.
Retry-After headerX-RateLimit-Remaining in every response# Rate limit headers in every response HTTP/1.1 200 OK X-RateLimit-Limit: 100 X-RateLimit-Remaining: 87 X-RateLimit-Reset: 1709234567 # When limit is exceeded HTTP/1.1 429 Too Many Requests Retry-After: 12 Content-Type: application/json { "success": false, "error": "Rate limit exceeded", "retryAfter": 12 }
The full API is documented in an OpenAPI 3.0 specification, so you can generate clients, validate requests, and explore endpoints interactively.
Every endpoint, request body, response schema, and error code is documented in a machine-readable OpenAPI 3.0 YAML file. Download it from the docs or fetch it from the /api/v1/openapi.json endpoint.
Browse the API interactively with auto-generated documentation. Try endpoints directly from the browser, inspect request and response shapes, and copy curl commands for quick local testing.
Use the OpenAPI spec with tools like openapi-generator to produce typed clients in Python, TypeScript, Go, Java, C#, and 40+ other languages. Keep your integration type-safe and auto-updated.