Chat API

The Chat API allows you to send queries to your agents and receive responses with citations from your documents.

Query Endpoint

Alternative: POST /v1/chat/query (legacy)

Request Body

| Field | Type | Required | Description | |-------|------|----------|-------------| | agent_id | string | Yes | The agent to query | | message | string | Yes | The user's question | | conversation_id | string | No | Continue an existing conversation | | include_citations | boolean | No | Include source citations (default: true) |

Example Request

1curl -X POST https://api.orka.ai/v1/chat/query \
2  -H "Authorization: Bearer sk_your_api_key" \
3  -H "Content-Type: application/json" \
4  -d '{
5    "agent_id": "agt_abc123",
6    "message": "What are the key features of the product?"
7  }'

Response

1{
2  "id": "msg_xyz789",
3  "conversation_id": "conv_abc123",
4  "content": "The key features of the product include:\n\n1. **Real-time sync** - Data synchronizes across all devices instantly [1]\n2. **Advanced security** - End-to-end encryption for all data [2]\n3. **Team collaboration** - Share and collaborate with unlimited team members [1]",
5  "citations": [
6    {
7      "id": 1,
8      "document_id": "doc_feat123",
9      "document_name": "Product Features.pdf",
10      "page_number": 3,
11      "excerpt": "Real-time synchronization ensures your data is always up-to-date across all connected devices...",
12      "score": 0.95
13    },
14    {
15      "id": 2,
16      "document_id": "doc_sec456",
17      "document_name": "Security Whitepaper.pdf",
18      "page_number": 7,
19      "excerpt": "All data is protected with AES-256 end-to-end encryption...",
20      "score": 0.89
21    }
22  ],
23  "applied_definitions": [
24    {
25      "id": "def_abc123",
26      "name": "Enterprise feature",
27      "type": "term",
28      "definition": "A feature available only on Enterprise plans"
29    }
30  ],
31  "usage": {
32    "prompt_tokens": 150,
33    "completion_tokens": 85,
34    "total_tokens": 235
35  },
36  "created_at": "2024-01-15T12:00:00Z"
37}

Response Fields

| Field | Type | Description | |-------|------|-------------| | id | string | Message identifier | | conversation_id | string | Conversation identifier for follow-ups | | content | string | The generated response | | citations | array | Source document citations | | applied_definitions | array | Logic definitions used in the response | | usage | object | Token usage statistics | | created_at | string | Response timestamp |

Applied Definitions

When logic definitions are used to answer a query, they appear in applied_definitions:

1{
2  "applied_definitions": [
3    {
4      "id": "def_abc123",
5      "name": "High-risk contract",
6      "type": "rule",
7      "definition": "Liability > $1M OR termination amendment"
8    },
9    {
10      "id": "def_xyz789",
11      "name": "Enterprise customer",
12      "type": "term",
13      "definition": "Organization with >500 employees"
14    }
15  ]
16}

Streaming Endpoint

Set stream: true in the request body to receive a streaming response.

Alternative: POST /v1/chat/stream (legacy)

Streaming allows you to display responses as they're generated, providing a better user experience for longer responses.

Request Body

Same as the query endpoint.

Example Request

1curl -X POST https://api.orka.ai/v1/chat/stream \
2  -H "Authorization: Bearer sk_your_api_key" \
3  -H "Content-Type: application/json" \
4  -H "Accept: text/event-stream" \
5  -d '{
6    "agent_id": "agt_abc123",
7    "message": "Explain the installation process"
8  }'

Response Format

The response is a stream of Server-Sent Events (SSE):

Event Types

| Event | Description | |-------|-------------| | message_start | Initial message metadata | | content_delta | Incremental content update | | citations | Citation data (sent once, near the end) | | message_end | Final metadata including token usage | | error | Error occurred during generation |

JavaScript Example

1const response = await fetch('https://api.orka.ai/v1/chat/stream', {
2  method: 'POST',
3  headers: {
4    'Authorization': `Bearer ${apiKey}`,
5    'Content-Type': 'application/json',
6  },
7  body: JSON.stringify({
8    agent_id: 'agt_abc123',
9    message: 'How do I get started?',
10  }),
11});
12
13const reader = response.body.getReader();
14const decoder = new TextDecoder();
15
16while (true) {
17  const { done, value } = await reader.read();
18  if (done) break;
19
20  const chunk = decoder.decode(value);
21  const lines = chunk.split('\n');
22
23  for (const line of lines) {
24    if (line.startsWith('data: ')) {
25      const data = JSON.parse(line.slice(6));
26      if (data.delta) {
27        // Append content to your UI
28        appendContent(data.delta);
29      }
30    }
31  }
32}

Citations

Citations link response content to source documents, allowing users to verify information.

Citation Object

| Field | Type | Description | |-------|------|-------------| | id | integer | Reference number in the response | | document_id | string | Source document ID | | document_name | string | Source document name | | page_number | integer | Page number (for PDFs) | | excerpt | string | Relevant text excerpt | | score | number | Relevance score (0-1) |

Citation Format in Content

Citations appear in the response content as bracketed numbers:

Conversations

Conversations maintain context across multiple messages, enabling follow-up questions.

Creating a Conversation

The first message automatically creates a new conversation:

1{
2  "agent_id": "agt_abc123",
3  "message": "What is the pricing?"
4}

Response includes a conversation_id:

1{
2  "conversation_id": "conv_xyz789",
3  "content": "Our pricing starts at..."
4}

Continuing a Conversation

Include the conversation_id in subsequent messages:

1{
2  "agent_id": "agt_abc123",
3  "conversation_id": "conv_xyz789",
4  "message": "What about the enterprise plan?"
5}

The agent will have context from previous messages in the conversation.

Error Handling

Common Errors

| Error Code | Description | Solution | |------------|-------------|----------| | agent_not_found | Agent ID doesn't exist | Verify the agent ID | | no_datastores | Agent has no connected datastores | Connect a datastore to the agent | | rate_limit | Too many requests | Wait and retry | | context_too_long | Conversation history is too long | Start a new conversation |

Example Error Response

1{
2  "error": {
3    "code": "no_datastores",
4    "message": "This agent has no connected datastores. Please connect at least one datastore before querying."
5  }
6}

Best Practices

Query Optimization

1. Be specific: More specific questions get better results
2. Use context: Include relevant context in your questions
3. Iterate: Use follow-up questions to refine answers

Performance

1. Use streaming for long responses to improve perceived performance
2. Reuse conversations for related questions
3. Limit concurrent requests to stay within rate limits

Citation Handling

1. Always display citations to users for transparency
2. Make citations clickable to show source documents
3. Show confidence scores when available