Agents API

Agents are the AI-powered interfaces that answer questions about your documents. This page documents all agent-related endpoints.

The Agent Object

json

1{
2  "id": "agt_abc123def456",
3  "name": "Customer Support Agent",
4  "description": "Answers customer questions about our products",
5  "system_prompt": "You are a helpful customer support agent...",
6  "datastores": ["ds_xyz789"],
7  "settings": {
8    "temperature": 0.7,
9    "max_tokens": 1024,
10    "retrieval_count": 5
11  },
12  "created_at": "2024-01-15T10:30:00Z",
13  "updated_at": "2024-01-15T10:30:00Z"
14}

Attributes

| Field | Type | Description | |-------|------|-------------| | id | string | Unique identifier for the agent | | name | string | Display name of the agent | | description | string | Optional description of the agent's purpose | | system_prompt | string | Instructions that define the agent's behavior | | datastores | array | List of connected datastore IDs | | settings | object | Configuration options for generation | | created_at | string | ISO 8601 timestamp of creation | | updated_at | string | ISO 8601 timestamp of last update |

List Agents

GET/v1/agents

Returns a list of all agents in your workspace

Query Parameters

| Parameter | Type | Description | |-----------|------|-------------| | limit | integer | Number of agents to return (1-100, default 20) | | cursor | string | Pagination cursor from previous response |

Response

json

1{
2  "data": [
3    {
4      "id": "agt_abc123",
5      "name": "Customer Support Agent",
6      "description": "Answers customer questions",
7      "created_at": "2024-01-15T10:30:00Z"
8    }
9  ],
10  "has_more": false,
11  "next_cursor": null
12}

Example

bash

1curl https://api.orka.ai/v1/agents \
2  -H "Authorization: Bearer sk_your_api_key"

Create Agent

POST/v1/agents

Creates a new agent

Request Body

| Field | Type | Required | Description | |-------|------|----------|-------------| | name | string | Yes | Display name (1-100 characters) | | description | string | No | Optional description | | system_prompt | string | No | Instructions for the agent | | settings | object | No | Configuration options |

Settings Object

| Field | Type | Default | Description | |-------|------|---------|-------------| | temperature | number | 0.7 | Creativity level (0-2) | | max_tokens | integer | 1024 | Maximum response length | | retrieval_count | integer | 5 | Documents to retrieve per query |

Example Request

bash

1curl -X POST https://api.orka.ai/v1/agents \
2  -H "Authorization: Bearer sk_your_api_key" \
3  -H "Content-Type: application/json" \
4  -d '{
5    "name": "Research Assistant",
6    "description": "Helps answer research questions",
7    "system_prompt": "You are a research assistant. Answer questions accurately and cite your sources.",
8    "settings": {
9      "temperature": 0.5,
10      "retrieval_count": 10
11    }
12  }'

Response

json

1{
2  "id": "agt_new123",
3  "name": "Research Assistant",
4  "description": "Helps answer research questions",
5  "system_prompt": "You are a research assistant...",
6  "datastores": [],
7  "settings": {
8    "temperature": 0.5,
9    "max_tokens": 1024,
10    "retrieval_count": 10
11  },
12  "created_at": "2024-01-15T12:00:00Z",
13  "updated_at": "2024-01-15T12:00:00Z"
14}

Get Agent

GET/v1/agents/:id

Retrieves a specific agent by ID

Path Parameters

| Parameter | Description | |-----------|-------------| | id | The agent ID (e.g., agt_abc123) |

Example

bash

1curl https://api.orka.ai/v1/agents/agt_abc123 \
2  -H "Authorization: Bearer sk_your_api_key"

Response

Returns the full agent object (see The Agent Object).

Update Agent

PATCH/v1/agents/:id

Updates an existing agent

Path Parameters

| Parameter | Description | |-----------|-------------| | id | The agent ID to update |

Request Body

All fields are optional. Only include fields you want to update.

| Field | Type | Description | |-------|------|-------------| | name | string | New display name | | description | string | New description | | system_prompt | string | New system prompt | | settings | object | Updated settings (merged with existing) |

Example

bash

1curl -X PATCH https://api.orka.ai/v1/agents/agt_abc123 \
2  -H "Authorization: Bearer sk_your_api_key" \
3  -H "Content-Type: application/json" \
4  -d '{
5    "name": "Updated Agent Name",
6    "settings": {
7      "temperature": 0.3
8    }
9  }'

Delete Agent

DELETE/v1/agents/:id

Permanently deletes an agent

Path Parameters

| Parameter | Description | |-----------|-------------| | id | The agent ID to delete |

Deleting an agent is permanent and cannot be undone. All conversation history associated with this agent will also be deleted.

Example

bash

1curl -X DELETE https://api.orka.ai/v1/agents/agt_abc123 \
2  -H "Authorization: Bearer sk_your_api_key"

Response

json

1{
2  "id": "agt_abc123",
3  "deleted": true
4}

Connect Datastore

POST/v1/agents/:id/datastores

Connects a datastore to an agent

Path Parameters

| Parameter | Description | |-----------|-------------| | id | The agent ID |

Request Body

| Field | Type | Required | Description | |-------|------|----------|-------------| | datastore_id | string | Yes | ID of the datastore to connect |

Example

bash

1curl -X POST https://api.orka.ai/v1/agents/agt_abc123/datastores \
2  -H "Authorization: Bearer sk_your_api_key" \
3  -H "Content-Type: application/json" \
4  -d '{
5    "datastore_id": "ds_xyz789"
6  }'

Response

Returns the updated agent object with the new datastore in the datastores array.

Disconnect Datastore

DELETE/v1/agents/:id/datastores/:datastore_id

Disconnects a datastore from an agent

Path Parameters

| Parameter | Description | |-----------|-------------| | id | The agent ID | | datastore_id | The datastore ID to disconnect |

Example

bash

1curl -X DELETE https://api.orka.ai/v1/agents/agt_abc123/datastores/ds_xyz789 \
2  -H "Authorization: Bearer sk_your_api_key"

Response

Returns the updated agent object.

Chat with Agent

POST/v1/agents/:id/chat

Send a message to an agent and get a response

Path Parameters

| Parameter | Description | |-----------|-------------| | id | The agent ID |

Request Body

| Field | Type | Required | Description | |-------|------|----------|-------------| | message | string | Yes | The user's question | | conversation_id | string | No | Continue an existing conversation | | stream | boolean | No | Enable streaming response (default: false) |

Example

bash

1curl -X POST https://api.orka.ai/v1/agents/agt_abc123/chat \
2  -H "Authorization: Bearer sk_your_api_key" \
3  -H "Content-Type: application/json" \
4  -d '{
5    "message": "What are the key risks in our contracts?"
6  }'

Response

json

1{
2  "id": "msg_xyz789",
3  "conversation_id": "conv_abc123",
4  "content": "Based on the documents, the key risks include...",
5  "citations": [
6    {
7      "id": 1,
8      "document_id": "doc_123",
9      "document_name": "Contract.pdf",
10      "page_number": 5,
11      "excerpt": "...",
12      "score": 0.95
13    }
14  ],
15  "applied_definitions": [
16    {
17      "id": "def_456",
18      "name": "High-risk contract",
19      "type": "rule"
20    }
21  ],
22  "usage": {
23    "prompt_tokens": 150,
24    "completion_tokens": 85,
25    "total_tokens": 235
26  },
27  "created_at": "2024-01-15T12:00:00Z"
28}

List Conversations

GET/v1/agents/:id/conversations

List all conversations for an agent

Path Parameters

| Parameter | Description | |-----------|-------------| | id | The agent ID |

Query Parameters

| Parameter | Type | Description | |-----------|------|-------------| | limit | integer | Number of conversations to return (1-100) | | cursor | string | Pagination cursor |

Example

bash

1curl https://api.orka.ai/v1/agents/agt_abc123/conversations \
2  -H "Authorization: Bearer sk_your_api_key"

Response

json

1{
2  "data": [
3    {
4      "id": "conv_xyz789",
5      "agent_id": "agt_abc123",
6      "message_count": 5,
7      "created_at": "2024-01-15T10:00:00Z",
8      "updated_at": "2024-01-15T10:30:00Z"
9    }
10  ],
11  "has_more": false,
12  "next_cursor": null
13}

Get Conversation

GET/v1/agents/:id/conversations/:conversation_id

Retrieve a specific conversation with messages

Path Parameters

| Parameter | Description | |-----------|-------------| | id | The agent ID | | conversation_id | The conversation ID |

Example

bash

1curl https://api.orka.ai/v1/agents/agt_abc123/conversations/conv_xyz789 \
2  -H "Authorization: Bearer sk_your_api_key"

Response

json

1{
2  "id": "conv_xyz789",
3  "agent_id": "agt_abc123",
4  "messages": [
5    {
6      "id": "msg_001",
7      "role": "user",
8      "content": "What are the key risks?",
9      "created_at": "2024-01-15T10:00:00Z"
10    },
11    {
12      "id": "msg_002",
13      "role": "assistant",
14      "content": "Based on the documents...",
15      "citations": [...],
16      "created_at": "2024-01-15T10:00:05Z"
17    }
18  ],
19  "created_at": "2024-01-15T10:00:00Z",
20  "updated_at": "2024-01-15T10:30:00Z"
21}

Delete Conversation

DELETE/v1/agents/:id/conversations/:conversation_id

Delete a conversation and all its messages

Path Parameters

| Parameter | Description | |-----------|-------------| | id | The agent ID | | conversation_id | The conversation ID |

Example

bash

1curl -X DELETE https://api.orka.ai/v1/agents/agt_abc123/conversations/conv_xyz789 \
2  -H "Authorization: Bearer sk_your_api_key"

Response

json

1{
2  "id": "conv_xyz789",
3  "deleted": true
4}

Share Agent

POST/v1/agents/:id/share

Generate a shareable link for an agent

Path Parameters

| Parameter | Description | |-----------|-------------| | id | The agent ID |

Request Body

| Field | Type | Required | Description | |-------|------|----------|-------------| | expires_in | integer | No | Link expiration in hours (default: never) | | allow_conversations | boolean | No | Allow creating conversations (default: true) |

Example

bash

1curl -X POST https://api.orka.ai/v1/agents/agt_abc123/share \
2  -H "Authorization: Bearer sk_your_api_key" \
3  -H "Content-Type: application/json" \
4  -d '{
5    "expires_in": 168
6  }'

Response

json

1{
2  "share_url": "https://app.orka.ai/shared/agt_abc123?token=xyz",
3  "token": "xyz",
4  "expires_at": "2024-01-22T12:00:00Z"
5}

Revoke Share

DELETE/v1/agents/:id/share

Revoke all sharing links for an agent

Path Parameters

| Parameter | Description | |-----------|-------------| | id | The agent ID |

Example

bash

1curl -X DELETE https://api.orka.ai/v1/agents/agt_abc123/share \
2  -H "Authorization: Bearer sk_your_api_key"

Response

json

1{
2  "id": "agt_abc123",
3  "shares_revoked": true
4}