> ## Documentation Index
> Fetch the complete documentation index at: https://docs.orka.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# API

> Send queries to your agents programmatically using the REST 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

```json theme={null}
{
  "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

<CodeGroup>
  ```bash cURL theme={null}
  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?"}'
  ```

  ```python Python theme={null}
  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"])
  ```

  ```javascript JavaScript theme={null}
  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);
  ```
</CodeGroup>

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

```bash theme={null}
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.