REST API 42 ENDPOINTS

Public API Reference

Programmatic access to agents, workflows, knowledge bases, and more

The Orckai Public API lets you integrate AI orchestration into any application. Manage agents, execute workflows, search knowledge bases, and chat with LLMs — all through a simple REST interface with scoped API keys.

Endpoints

Scopes

100

Requests / Min

oak_

Key Prefix

Base URL

https://orckai.app/api/v1

All endpoints below are relative to this base URL.

Authentication

All endpoints (except /health) require an API key passed in the X-API-Key header. Create API keys in your dashboard under Settings → API Keys. Keys start with the oak_ prefix.

# Example request
curl -H "X-API-Key: oak_your_key_here" \
     https://orckai.app/api/v1/agents

Security

API keys are hashed with SHA-256 before storage. The full key is only shown once at creation time. Store it securely.

Available Scopes

Each API key has scoped permissions. Assign only the scopes your integration needs.

Scope	Description
`agents:read`	List and get agents and execution history
`agents:write`	Create, update, and delete agents
`agents:execute`	Execute agents
`workflows:read`	List and get workflows and executions
`workflows:write`	Create, update, and delete workflows
`workflows:execute`	Execute, cancel, and retry workflows
`kb:read`	Read knowledge bases, documents, and search
`kb:write`	Create, update, delete KBs and upload documents
`templates:read`	Read prompt templates
`templates:write`	Create, update, and delete templates
`mcp:read`	Read MCP servers and tools
`mcp:write`	Create and modify MCP servers
`mcp:deploy`	Deploy MCP servers
`chat:read`	Read chat conversations
`chat:write`	Create chat completions and streams
`org:read`	Read organization data
`org:write`	Modify organization settings
`*`	Full access (all scopes)

Rate Limiting

All API keys share a standard rate limit. Contact support@orckai.com to request higher limits for your organization.

Window	Limit
Per Minute	100
Per Hour	3,000
Per Day	50,000
Burst	20 concurrent

Response Headers

Header	Description
`X-RateLimit-Limit`	Total requests allowed per minute for this tier
`X-RateLimit-Remaining`	Requests remaining in the current window
`X-RateLimit-Reset`	Timestamp (epoch seconds) when the limit resets

429 Too Many Requests

When rate-limited, the response includes a Retry-After header with the number of seconds to wait before retrying.

Agents

Create and manage AI agents. Agents have system prompts, model configurations, and optional tool attachments.

Method	Endpoint	Scope	Description
`GET`	`/agents`	agents:read	List all agents
`POST`	`/agents`	agents:write	Create an agent
`GET`	`/agents/{id}`	agents:read	Get agent by ID
`PUT`	`/agents/{id}`	agents:write	Update an agent
`DELETE`	`/agents/{id}`	agents:write	Delete an agent
`POST`	`/agents/execute`	agents:execute	Execute an agent
`GET`	`/agents/{id}/executions`	agents:read	List agent executions

Create Agent

POST /api/v1/agents
Content-Type: application/json
X-API-Key: oak_your_key

{
  "name": "Sales Assistant",
  "agentType": "conversational",
  "executionMode": "standard",
  "systemPrompt": "You are a helpful sales assistant.",
  "goalTemplate": "Help the user with {{task}}"
}

Response

{
  "success": true,
  "data": {
    "id": "a1b2c3d4-...",
    "name": "Sales Assistant",
    "agentType": "conversational",
    "executionMode": "standard",
    "isActive": true,
    "createdAt": "2026-02-26T10:00:00.000Z"
  }
}

Workflows

Build and execute multi-step automation workflows with triggers, agents, code steps, conditions, and actions.

Method	Endpoint	Scope	Description
`GET`	`/workflows`	workflows:read	List all workflows
`POST`	`/workflows`	workflows:write	Create a workflow
`GET`	`/workflows/{id}`	workflows:read	Get workflow by ID
`PUT`	`/workflows/{id}`	workflows:write	Update a workflow
`DELETE`	`/workflows/{id}`	workflows:write	Delete a workflow
`POST`	`/workflows/{id}/execute`	workflows:execute	Execute a workflow
`GET`	`/workflows/executions`	workflows:read	List all executions
`GET`	`/workflows/executions/{id}`	workflows:read	Get execution details
`POST`	`/workflows/executions/{id}/cancel`	workflows:execute	Cancel a running execution
`POST`	`/workflows/executions/{id}/retry`	workflows:execute	Retry a failed execution

Execute Workflow

POST /api/v1/workflows/{id}/execute
Content-Type: application/json
X-API-Key: oak_your_key

{
  "input": {
    "customer_name": "Acme Corp",
    "report_type": "quarterly"
  }
}

Response

{
  "success": true,
  "executionId": "e5f6g7h8-...",
  "status": "queued"
}

Variable Interpolation

Input data is available to workflow steps via {{variable}} syntax. For example, {{customer_name}} resolves to "Acme Corp" in the example above.

Knowledge Bases

Upload documents and search them with RAG (Retrieval-Augmented Generation). Supports 50+ file types.

Method	Endpoint	Scope	Description
`GET`	`/knowledge-bases`	kb:read	List all knowledge bases
`POST`	`/knowledge-bases`	kb:write	Create a knowledge base
`GET`	`/knowledge-bases/{id}`	kb:read	Get knowledge base by ID
`PUT`	`/knowledge-bases/{id}`	kb:write	Update a knowledge base
`DELETE`	`/knowledge-bases/{id}`	kb:write	Delete a knowledge base
`GET`	`/knowledge-bases/{id}/documents`	kb:read	List documents
`POST`	`/knowledge-bases/{id}/documents`	kb:write	Upload a document
`POST`	`/knowledge-bases/{id}/search`	kb:read	Search with RAG

Search Knowledge Base

POST /api/v1/knowledge-bases/{id}/search
Content-Type: application/json
X-API-Key: oak_your_key

{
  "query": "What is the refund policy?",
  "limit": 5
}

Response

{
  "success": true,
  "data": [
    {
      "content": "Annual plans include a 30-day money-back guarantee...",
      "score": 0.94,
      "documentName": "refund-policy.pdf"
    }
  ]
}

Prompt Templates

Manage reusable prompt templates with variable placeholders.

Method	Endpoint	Scope	Description
`GET`	`/templates`	templates:read	List all templates
`POST`	`/templates`	templates:write	Create a template
`GET`	`/templates/{id}`	templates:read	Get template by ID
`PUT`	`/templates/{id}`	templates:write	Update a template
`DELETE`	`/templates/{id}`	templates:write	Delete a template

Filter by category

Use GET /templates?category=custom to filter. Valid categories: custom, chat, widget, agent.

MCP Servers

Manage MCP (Model Context Protocol) servers and discover their tools.

Method	Endpoint	Scope	Description
`GET`	`/mcp-servers`	mcp:read	List all MCP servers
`POST`	`/mcp-servers`	mcp:write	Create an MCP server
`GET`	`/mcp-servers/{id}`	mcp:read	Get MCP server by ID
`PUT`	`/mcp-servers/{id}`	mcp:write	Update an MCP server
`GET`	`/mcp-servers/{id}/tools`	mcp:read	List server tools

Chat

Send messages to LLMs and manage conversations. Supports both synchronous completions and SSE streaming.

Method	Endpoint	Scope	Description
`POST`	`/chat/completions`	chat:write	Send a chat message
`POST`	`/chat/stream`	chat:write	Stream a chat response (SSE)
`GET`	`/conversations`	chat:read	List conversations
`GET`	`/conversations/{id}`	chat:read	Get conversation with messages
`DELETE`	`/conversations/{id}`	chat:write	Delete a conversation

Chat Completion

POST /api/v1/chat/completions
Content-Type: application/json
X-API-Key: oak_your_key

{
  "message": "Summarize the latest sales report",
  "llmConfig": {
    "provider": "anthropic",
    "model": "claude-sonnet-4-20250514",
    "temperature": 0.7,
    "maxTokens": 1024
  },
  "systemPrompt": "You are a business analyst."
}

Response

{
  "success": true,
  "data": {
    "conversationId": "c9d0e1f2-...",
    "message": "Based on the Q4 sales data...",
    "usage": {
      "inputTokens": 142,
      "outputTokens": 387
    }
  }
}

Continuing Conversations

Pass conversationId in subsequent requests to continue an existing conversation with full message history.

SSE Streaming

POST /chat/stream returns a text/event-stream response for real-time token streaming.

POST /api/v1/chat/stream
Content-Type: application/json
X-API-Key: oak_your_key

{
  "message": "Explain quantum computing",
  "llmConfig": { "provider": "anthropic", "model": "claude-sonnet-4-20250514" }
}

Event Format

data: {"content": "Quantum ", "done": false}
data: {"content": "computing ", "done": false}
data: {"content": "uses...", "done": false}
...
data: {"content": "", "done": true, "conversationId": "c9d0e1f2-..."}

Organization

Method	Endpoint	Scope	Description
`GET`	`/organization`	org:read	Get organization info

Error Handling

All errors return a consistent JSON format:

{
  "success": false,
  "error": "Agent not found",
  "code": "NOT_FOUND"
}

Status	Code	Description
`400`	BAD_REQUEST	Invalid request body or parameters
`401`	API_KEY_MISSING / API_KEY_INVALID	Missing or invalid API key
`403`	SCOPE_REQUIRED	API key lacks the required scope
`404`	NOT_FOUND	Resource not found
`429`	RATE_LIMITED	Too many requests, check Retry-After header
`500`	INTERNAL_ERROR	Server error

Health Check

No authentication required.

GET /api/v1/health

{
  "status": "ok",
  "version": "v1"
}

Ready to Integrate?

Create your API key and start building integrations in minutes.

Open Dashboard Widget Documentation