API

Authentication

Every API request requires an API key passed as a Bearer token.

Authorization: Bearer sk-orka-...

Create an API key

Open the Playground page from the sidebar and click Generate API Key. The full key is shown once — copy it and store it securely. Generating a new key revokes the previous one. Each workspace has one active key at a time.

Chat endpoint

POST /api/v1/agents/{agent_id}/chat

Send a message to an agent and get a response with citations and applied definitions.

Request

Field	Type	Required	Description
`message`	string	Yes	The query to send to the agent.
`conversation_id`	string	No	UUID of an existing conversation. Omit to start a new one.

Response

{
  "conversation_id": "uuid",
  "response": "The answer text...",
  "agent_id": "uuid",
  "timestamp": "2025-01-15T10:30:00Z",
  "processing_time_ms": 1200,
  "citations": [
    {
      "id": 1,
      "document_id": "uuid",
      "document_name": "report.pdf",
      "page_number": 12,
      "chunk_text": "Relevant passage from the document...",
      "similarity_score": 0.92
    }
  ],
  "applied_definitions": [
    {
      "id": "uuid",
      "definition_name": "Revenue",
      "definition_type": "metric",
      "definition_text": "Total income before deductions...",
      "source": "workspace"
    }
  ]
}

Errors

Status	Meaning
`401`	Missing or invalid API key.
`400`	Empty message.
`404`	Agent not found or not in this workspace.
`500`	Server error.

Examples

curl -X POST https://orka.sh/api/v1/agents/AGENT_ID/chat \
  -H "Authorization: Bearer sk-orka-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"message": "What was Q4 revenue?"}'

import requests

response = requests.post(
    "https://orka.sh/api/v1/agents/AGENT_ID/chat",
    headers={
        "Authorization": "Bearer sk-orka-YOUR_KEY",
        "Content-Type": "application/json",
    },
    json={"message": "What was Q4 revenue?"},
)

data = response.json()
print(data["response"])

const response = await fetch(
  "https://orka.sh/api/v1/agents/AGENT_ID/chat",
  {
    method: "POST",
    headers: {
      "Authorization": "Bearer sk-orka-YOUR_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ message: "What was Q4 revenue?" }),
  }
);

const data = await response.json();
console.log(data.response);

Multi-turn conversations

Pass the conversation_id from a previous response to continue the conversation. The agent retains the full message history for that conversation.

curl -X POST https://orka.sh/api/v1/agents/AGENT_ID/chat \
  -H "Authorization: Bearer sk-orka-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"message": "Break that down by quarter", "conversation_id": "CONVERSATION_ID"}'

Playground

The Playground page in the sidebar lets you test the chat endpoint directly from the browser. Select an agent, type a message, and see the full response with citations and definitions. The page also shows ready-to-use code snippets in cURL, Python, and JavaScript with your actual API key and agent ID filled in.

Getting Started

Core Features

Developers

Authentication

Create an API key

Chat endpoint

Request

Response

Errors

Examples

Multi-turn conversations

Playground

​Authentication

​Create an API key

​Chat endpoint

​Request

​Response

​Errors

​Examples

​Multi-turn conversations

​Playground

Authentication

Create an API key

Chat endpoint

Request

Response

Errors

Examples

Multi-turn conversations

Playground