Skip to main content

​
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

FieldTypeRequiredDescription
messagestringYesThe query to send to the agent.
conversation_idstringNoUUID 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

StatusMeaning
401Missing or invalid API key.
400Empty message.
404Agent not found or not in this workspace.
500Server 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?"}'

​
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.