API Reference

The Orka API is organized around REST. Our API accepts JSON-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes and authentication.

Base URL

All API requests should be made to:

Authentication

The Orka API uses API keys to authenticate requests. You can manage your API keys in your dashboard settings.

Include your API key in the Authorization header:

1Authorization: Bearer sk_your_api_key_here

Request Format

All requests should:

• Use HTTPS
• Include Content-Type: application/json header for POST/PUT/PATCH requests
• Include the Authorization header with your API key

Example Request

1curl -X POST https://api.orka.ai/v1/agents \
2  -H "Authorization: Bearer sk_your_api_key_here" \
3  -H "Content-Type: application/json" \
4  -d '{
5    "name": "My Agent",
6    "system_prompt": "You are a helpful assistant."
7  }'

Response Format

All responses are returned as JSON with the following structure:

Success Response

1{
2  "id": "agt_abc123",
3  "name": "My Agent",
4  "created_at": "2024-01-15T10:30:00Z"
5}

Error Response

1{
2  "error": {
3    "code": "invalid_request",
4    "message": "The 'name' field is required.",
5    "param": "name"
6  }
7}

HTTP Status Codes

| Code | Description | |------|-------------| | 200 | OK - Request succeeded | | 201 | Created - Resource created successfully | | 400 | Bad Request - Invalid request parameters | | 401 | Unauthorized - Invalid or missing API key | | 403 | Forbidden - Insufficient permissions | | 404 | Not Found - Resource doesn't exist | | 429 | Too Many Requests - Rate limit exceeded | | 500 | Server Error - Something went wrong on our end |

Error Codes

| Code | Description | |------|-------------| | invalid_request | The request body or parameters are invalid | | authentication_error | API key is invalid or missing | | permission_denied | You don't have access to this resource | | not_found | The requested resource doesn't exist | | rate_limit_exceeded | Too many requests in a short period | | processing_error | Document processing failed |

Rate Limits

API requests are rate limited to ensure fair usage:

| Tier | Requests per minute | Concurrent requests | |------|--------------------:|--------------------:| | Free | 60 | 5 | | Pro | 300 | 20 | | Enterprise | Custom | Custom |

When you exceed the rate limit, you'll receive a 429 response with a Retry-After header indicating when you can retry.

Pagination

List endpoints support cursor-based pagination:

1GET /v1/agents?limit=20&cursor=agt_abc123

Parameters

| Parameter | Type | Description | |-----------|------|-------------| | limit | integer | Number of items per page (1-100, default 20) | | cursor | string | Cursor from previous response for next page |

Response

1{
2  "data": [...],
3  "has_more": true,
4  "next_cursor": "agt_xyz789"
5}

API Endpoints

SDKs

We provide official SDKs for:

• JavaScript/TypeScript
• Python

See the Installation guide for setup instructions.