API DOCUMENTATION

API Documentation

Complete technical reference for integrating Arko via API Keys

Introduction

Arko provides a RESTful API that allows programmatic access to all platform features: AI agents, conversations, memories, powers, and API key management.

All endpoints require authentication via API Key and follow a consistent response format. This documentation covers all available endpoints with real, verified examples.

Base URL: https://arko.arcaelas.com/v2

Authentication

All API requests must include an API Key in the Authorization header using Bearer token format.

Authorization Header

curl -H "Authorization: Bearer arko_your_api_key_here" \
  https://arko.arcaelas.com/v2/agents

Note: API keys are shown only once when created. Store them securely. If you lose a key, you can create a new one from the Settings panel.

API Playground

Test API endpoints directly from your browser. Select an endpoint, fill in parameters, and execute requests using your API key.

Endpoints

The Arko API provides endpoints for managing agents, chats, messages, memories, powers, and API keys.

Method	Endpoint	Description
GET	/v2/agents	List all agents
POST	/v2/agents	Create agent
GET	/v2/agents/:id	Get agent
PUT	/v2/agents/:id	Update agent
DELETE	/v2/agents/:id	Delete agent
GET	/v2/chats	List all chats
POST	/v2/chats/:id/messages	Send message to chat
POST	/v2/messages	Send standalone message
GET	/v2/memories	List memories
POST	/v2/memories	Create memory
GET	/v2/powers	List powers
POST	/v2/powers	Create power
GET	/v2/keys	List API keys
POST	/v2/keys	Create API key

Agents

Agents are AI assistants with configurable personalities, models, and tools. Each agent can have a custom system prompt, temperature setting, and attached Powers.

List Agents

GET/v2/agents

Request

curl -H "Authorization: Bearer arko_your_api_key_here" \
  https://arko.arcaelas.com/v2/agents

Response

{
  "success": true,
  "data": [
    {
      "id": "agent_abc123",
      "name": "arko",
      "content": "You are Arko, a friendly AI assistant...",
      "memory": true,
      "model": "gpt-4o",
      "created_at": "2026-01-15T10:30:00.000Z"
    }
  ]
}

Field Truncation: The content field is truncated to 300 characters in list responses. Use GET /v2/agents/:id to retrieve full content.

Create Agent

POST/v2/agents

Request

curl -X POST \
  -H "Authorization: Bearer arko_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{"name": "my-agent", "content": "You are a helpful assistant.", "memory": true}' \
  https://arko.arcaelas.com/v2/agents

Chats

Chats represent conversation threads with agents. Each chat belongs to an agent and contains a history of messages.

List Chats

GET/v2/chats

Request

curl -H "Authorization: Bearer arko_your_api_key_here" \
  https://arko.arcaelas.com/v2/chats

Send Message to Chat

POST/v2/chats/:id/messages

Request

curl -X POST \
  -H "Authorization: Bearer arko_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{"content": "Hello, how are you?", "role": "user"}' \
  https://arko.arcaelas.com/v2/chats/chat_abc123/messages

Streaming: Add ?stream=true to receive a streaming response using newline-delimited JSON.

Messages

Send standalone messages without a specific chat context. The system will create or reuse a chat automatically.

POST/v2/messages

Request

curl -X POST \
  -H "Authorization: Bearer arko_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{"agentId": "agent_abc123", "content": "What is the weather?", "stream": true}' \
  https://arko.arcaelas.com/v2/messages

Streaming Response

{"type": "delta", "content": "Based on "}
{"type": "delta", "content": "the current "}
{"type": "delta", "content": "time..."}
{"type": "done", "message": {"id": "msg_xyz", "content": "Based on the current time...", "role": "assistant"}}

Streaming Mode (stream: true)

When stream: true, the response is newline-delimited JSON (NDJSON) with event types:

json

{"type": "chat", "id": "...", "name": "...", "agent": {...}}
{"type": "message", "id": "...", "role": "user", "content": "..."}
{"type": "message_start", "id": "..."}
{"type": "delta", "content": "chunk of text"}
{"type": "message_end", "id": "..."}
{"type": "done", "messages": [...]}

Response headers: Content-Type: application/x-ndjson, Cache-Control: no-cache

Memories

Memories allow agents to retain information across conversations. You can create, list, and manage memories programmatically.

List Memories

GET/v2/memories

Request

curl -H "Authorization: Bearer arko_your_api_key_here" \
  https://arko.arcaelas.com/v2/memories

Create Memory

POST/v2/memories

Request

curl -X POST \
  -H "Authorization: Bearer arko_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{"content": "User prefers responses in Spanish", "tags": ["preference", "language"]}' \
  https://arko.arcaelas.com/v2/memories

Powers

Powers are custom tools that extend agent capabilities. They allow agents to call external APIs and services during conversations.

List Powers

GET/v2/powers

Request

curl -H "Authorization: Bearer arko_your_api_key_here" \
  https://arko.arcaelas.com/v2/powers

Note: List Response Fields

The parameters field is NOT included in list responses for performance. Use GET /v2/powers/:id to retrieve full power details including parameters.

Create Power

POST/v2/powers

Request

curl -X POST \
  -H "Authorization: Bearer arko_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{"name": "weather", "content": "Gets current weather data", "url": "https://api.weather.com/v1/current"}' \
  https://arko.arcaelas.com/v2/powers

Parameter Update Semantics

Parameter with id + name: null → DELETE
Parameter with id + name value → UPDATE
Parameter without id → CREATE

This allows mixed create/update/delete operations in a single request.

API Keys

Manage your API keys programmatically. Note: API key endpoints require Firebase JWT authentication (not API key auth).

List Keys

GET/v2/keys

Request

curl -H "Authorization: Bearer arko_your_api_key_here" \
  https://arko.arcaelas.com/v2/keys

Note: SHA Field Truncation

The sha field is truncated in list responses for security (shows first 12 characters + "..."). Full key is only returned on creation (POST /v2/keys) or via GET /v2/keys/:id.

Create Key

POST/v2/keys

Request

curl -X POST \
  -H "Authorization: Bearer arko_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{"name": "production-key"}' \
  https://arko.arcaelas.com/v2/keys

Important: The full API key value is only returned once at creation time. Store it securely immediately.

Object Schemas

Detailed schemas for all API objects returned by the Arko Studio API.

Agent

AI assistants with configurable personalities, models, and tools.

Agent Object

{
  "id": string,              // Unique identifier (UUID)
  "uid": string,             // User ID (owner)
  "name": string,            // Agent name (max 200 chars, lowercase alphanumeric)
  "content": string,         // System prompt/description (max 5000 chars)
  "memory": boolean,         // Whether agent uses user memories
  "created_at": string,      // ISO 8601 timestamp
  "updated_at": string       // ISO 8601 timestamp
}

Chat

Conversation threads with agents containing message history.

Chat Object

{
  "id": string,              // Unique identifier (UUID)
  "uid": string,             // User ID (owner)
  "aid": string,             // Agent ID
  "name": string,            // Chat name (max 200 chars)
  "archived": boolean,       // Whether chat is archived
  "created_at": string,      // ISO 8601 timestamp
  "updated_at": string       // ISO 8601 timestamp
}

Message

Individual messages within a chat. Can be user, assistant, or tool messages.

Message Object

{
  "id": string,              // Unique identifier (UUID)
  "cid": string,             // Chat ID
  "role": "user" | "assistant" | "tool",
  "content": string,         // Message content (max 5000 chars)
  "tool_call_id": string,    // Tool call ID (for role: "tool" only)
  "created_at": string,      // ISO 8601 timestamp
  "updated_at": string       // ISO 8601 timestamp
}

Memory

Persistent information that agents can remember across conversations.

Memory Object

{
  "id": string,              // Unique identifier (UUID)
  "uid": string,             // User ID (owner)
  "content": string,         // Memory content (max 500 chars)
  "created_at": string,      // ISO 8601 timestamp
  "updated_at": string       // ISO 8601 timestamp
}

Power

Custom tools that extend agent capabilities via webhooks.

Power Object

{
  "id": string,              // Unique identifier (UUID)
  "uid": string,             // User ID (owner)
  "name": string,            // Power name (max 200 chars)
  "content": string,         // Power description (max 500 chars)
  "url": string,             // Webhook URL (max 1024 chars)
  "method": string,          // HTTP method (GET, POST, PUT, PATCH, DELETE)
  "x_header_key": string,    // Auth header key (max 500 chars)
  "x_header_value": string,  // Auth header value (max 1024 chars)
  "created_at": string,      // ISO 8601 timestamp
  "updated_at": string       // ISO 8601 timestamp
}

Parameter

Parameters for Power tools, defining input requirements.

Parameter Object

{
  "id": string,              // Unique identifier (UUID)
  "pid": string,             // Power ID
  "name": string,            // Parameter name (max 200 chars)
  "content": string,         // Parameter description (max 500 chars)
  "value": string,           // Default value (max 200 chars)
  "required": boolean,       // Whether parameter is required
  "created_at": string,      // ISO 8601 timestamp
  "updated_at": string       // ISO 8601 timestamp
}

API Key

Authentication credentials for API access.

API Key Object

{
  "id": string,              // Unique identifier (UUID)
  "uid": string,             // User ID (owner)
  "name": string,            // Key name (max 100 chars)
  "sha": string,             // Full API key (format: sk-{64 hex chars})
  "scopes": string[],        // Permission scopes
  "expired_at": string,      // Expiration timestamp (empty = never expires)
  "created_at": string,      // ISO 8601 timestamp
  "updated_at": string       // ISO 8601 timestamp
}

Note: The sha field containing the full API key is only returned when creating a new key. List operations return a truncated version for security.

ToolCall

Tool/function calls made by assistant messages.

ToolCall Object

{
  "id": string,              // Unique identifier (UUID)
  "mid": string,             // Message ID (assistant message)
  "tcid": string,            // OpenAI tool call ID (call_xxx)
  "name": string,            // Function/tool name
  "arguments": string        // JSON string of arguments
}

Pagination

List endpoints that return multiple items support pagination using offset and limit query parameters.

Query Parameters

Parameter	Type	Default	Description
offset	integer	0	Number of items to skip
limit	integer	20	Maximum number of items to return (max: 100)

Response Format

Paginated responses include the data array, total count, and pagination metadata.

Paginated Response

{
  "success": true,
  "data": {
    "rows": [
      {
        "id": "agent_abc123",
        "name": "arko",
        "content": "You are Arko...",
        "created_at": "2026-01-15T10:30:00.000Z"
      },
      {
        "id": "agent_def456",
        "name": "customer-support",
        "content": "You are a customer support agent...",
        "created_at": "2026-01-16T14:22:00.000Z"
      }
    ],
    "count": 42,        // Total number of items
    "offset": 0,        // Current offset
    "limit": 20         // Current limit
  }
}

Example Usage

Request with Pagination

# Get the second page of agents (items 20-39)
curl -H "Authorization: Bearer arko_your_api_key_here" \
  "https://arko.arcaelas.com/v2/agents?offset=20&limit=20"

# Get first 5 chats
curl -H "Authorization: Bearer arko_your_api_key_here" \
  "https://arko.arcaelas.com/v2/chats?limit=5"

Pagination Limits: The maximum limit value is 100. Requests exceeding this will be capped at 100 items per page.

Response Format

All API responses follow a consistent JSON format with a success boolean and either a data or error field.

Success Response

{
  "success": true,
  "data": {
    "id": "agent_abc123",
    "name": "arko",
    "content": "You are Arko..."
  }
}

Error Response

{
  "success": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid or expired API key"
  }
}

Errors

The API uses standard HTTP status codes. Here are the most common error responses:

Status	Code	Description
400	BAD_REQUEST	Invalid request body or parameters
401	UNAUTHORIZED	Missing or invalid authentication token
403	FORBIDDEN	Insufficient permissions
404	NOT_FOUND	Resource not found
429	RATE_LIMITED	Too many requests, try again later
500	INTERNAL_ERROR	Internal server error

Rate Limits

API requests are rate-limited to ensure fair usage. Limits vary by plan:

Plan	Requests/Minute	Daily Limit
Free	50	1,000
Premium	200	Unlimited

Rate limit information is included in response headers:

Rate Limit Headers

X-RateLimit-Limit: 50
X-RateLimit-Remaining: 47
X-RateLimit-Reset: 1707307200

Code Examples

Complete examples for common use cases.

Create an Agent and Start a Conversation

Step 1: Create Agent

curl -X POST \
  -H "Authorization: Bearer arko_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "customer-support",
    "content": "You are a customer support agent for an e-commerce platform. Be helpful, concise, and empathetic.",
    "memory": true
  }' \
  https://arko.arcaelas.com/v2/agents

Step 2: Send a Message

curl -X POST \
  -H "Authorization: Bearer arko_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "agentId": "AGENT_ID_FROM_STEP_1",
    "content": "I need help with my order #12345",
    "stream": true
  }' \
  https://arko.arcaelas.com/v2/messages

JavaScript/TypeScript Example

example.ts

const API_BASE = "https://arko.arcaelas.com/v2";
const API_KEY = "arko_your_api_key_here";

async function createAgent() {
  const response = await fetch(`${API_BASE}/agents`, {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      name: "my-agent",
      content: "You are a helpful assistant.",
      memory: true,
    }),
  });

  const data = await response.json();
  return data.data;
}

async function sendMessage(agentId: string, content: string) {
  const response = await fetch(`${API_BASE}/messages?stream=true`, {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ agentId, content }),
  });

  const reader = response.body?.getReader();
  const decoder = new TextDecoder();

  while (reader) {
    const { done, value } = await reader.read();
    if (done) break;

    const chunk = decoder.decode(value);
    const lines = chunk.split("\n").filter(Boolean);

    for (const line of lines) {
      const event = JSON.parse(line);
      if (event.type === "delta") {
        process.stdout.write(event.content);
      }
    }
  }
}

// Usage
const agent = await createAgent();
await sendMessage(agent.id, "Hello! What can you do?");

Python Example

example.py

import requests
import json

API_BASE = "https://arko.arcaelas.com/v2"
API_KEY = "arko_your_api_key_here"

headers = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json"
}

# Create an agent
agent_response = requests.post(
    f"{API_BASE}/agents",
    headers=headers,
    json={
        "name": "python-agent",
        "content": "You are a helpful Python assistant.",
        "memory": True
    }
)
agent = agent_response.json()["data"]
print(f"Created agent: {agent['id']}")

# Send a message with streaming
response = requests.post(
    f"{API_BASE}/messages",
    headers=headers,
    json={
        "agentId": agent["id"],
        "content": "Write a hello world in Python",
        "stream": True
    },
    stream=True
)

for line in response.iter_lines():
    if line:
        event = json.loads(line)
        if event["type"] == "delta":
            print(event["content"], end="", flush=True)

print()  # New line after streaming

Introduction

Arko provides a RESTful API that allows programmatic access to all platform features: AI agents, conversations, memories, powers, and API key management.

All endpoints require authentication via API Key and follow a consistent response format. This documentation covers all available endpoints with real, verified examples.

Base URL: https://arko.arcaelas.com/v2

Authentication

All API requests must include an API Key in the Authorization header using Bearer token format.

Authorization Header

curl -H "Authorization: Bearer arko_your_api_key_here" \
  https://arko.arcaelas.com/v2/agents

Note: API keys are shown only once when created. Store them securely. If you lose a key, you can create a new one from the Settings panel.

API Playground

Test API endpoints directly from your browser. Select an endpoint, fill in parameters, and execute requests using your API key.

Endpoints

The Arko API provides endpoints for managing agents, chats, messages, memories, powers, and API keys.

Method	Endpoint	Description
GET	/v2/agents	List all agents
POST	/v2/agents	Create agent
GET	/v2/agents/:id	Get agent
PUT	/v2/agents/:id	Update agent
DELETE	/v2/agents/:id	Delete agent
GET	/v2/chats	List all chats
POST	/v2/chats/:id/messages	Send message to chat
POST	/v2/messages	Send standalone message
GET	/v2/memories	List memories
POST	/v2/memories	Create memory
GET	/v2/powers	List powers
POST	/v2/powers	Create power
GET	/v2/keys	List API keys
POST	/v2/keys	Create API key

Agents

Agents are AI assistants with configurable personalities, models, and tools. Each agent can have a custom system prompt, temperature setting, and attached Powers.

List Agents

GET/v2/agents

Request

curl -H "Authorization: Bearer arko_your_api_key_here" \
  https://arko.arcaelas.com/v2/agents

Response

{
  "success": true,
  "data": [
    {
      "id": "agent_abc123",
      "name": "arko",
      "content": "You are Arko, a friendly AI assistant...",
      "memory": true,
      "model": "gpt-4o",
      "created_at": "2026-01-15T10:30:00.000Z"
    }
  ]
}

Field Truncation: The content field is truncated to 300 characters in list responses. Use GET /v2/agents/:id to retrieve full content.

Create Agent

POST/v2/agents

Request

curl -X POST \
  -H "Authorization: Bearer arko_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{"name": "my-agent", "content": "You are a helpful assistant.", "memory": true}' \
  https://arko.arcaelas.com/v2/agents

Chats

Chats represent conversation threads with agents. Each chat belongs to an agent and contains a history of messages.

List Chats

GET/v2/chats

Request

curl -H "Authorization: Bearer arko_your_api_key_here" \
  https://arko.arcaelas.com/v2/chats

Send Message to Chat

POST/v2/chats/:id/messages

Request

curl -X POST \
  -H "Authorization: Bearer arko_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{"content": "Hello, how are you?", "role": "user"}' \
  https://arko.arcaelas.com/v2/chats/chat_abc123/messages

Streaming: Add ?stream=true to receive a streaming response using newline-delimited JSON.

Messages

Send standalone messages without a specific chat context. The system will create or reuse a chat automatically.

POST/v2/messages

Request

curl -X POST \
  -H "Authorization: Bearer arko_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{"agentId": "agent_abc123", "content": "What is the weather?", "stream": true}' \
  https://arko.arcaelas.com/v2/messages

Streaming Response

{"type": "delta", "content": "Based on "}
{"type": "delta", "content": "the current "}
{"type": "delta", "content": "time..."}
{"type": "done", "message": {"id": "msg_xyz", "content": "Based on the current time...", "role": "assistant"}}

Streaming Mode (stream: true)

When stream: true, the response is newline-delimited JSON (NDJSON) with event types:

json

{"type": "chat", "id": "...", "name": "...", "agent": {...}}
{"type": "message", "id": "...", "role": "user", "content": "..."}
{"type": "message_start", "id": "..."}
{"type": "delta", "content": "chunk of text"}
{"type": "message_end", "id": "..."}
{"type": "done", "messages": [...]}

Response headers: Content-Type: application/x-ndjson, Cache-Control: no-cache

Memories

Memories allow agents to retain information across conversations. You can create, list, and manage memories programmatically.

List Memories

GET/v2/memories

Request

curl -H "Authorization: Bearer arko_your_api_key_here" \
  https://arko.arcaelas.com/v2/memories

Create Memory

POST/v2/memories

Request

curl -X POST \
  -H "Authorization: Bearer arko_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{"content": "User prefers responses in Spanish", "tags": ["preference", "language"]}' \
  https://arko.arcaelas.com/v2/memories

Powers

Powers are custom tools that extend agent capabilities. They allow agents to call external APIs and services during conversations.

List Powers

GET/v2/powers

Request

curl -H "Authorization: Bearer arko_your_api_key_here" \
  https://arko.arcaelas.com/v2/powers

Note: List Response Fields

The parameters field is NOT included in list responses for performance. Use GET /v2/powers/:id to retrieve full power details including parameters.

Create Power

POST/v2/powers

Request

curl -X POST \
  -H "Authorization: Bearer arko_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{"name": "weather", "content": "Gets current weather data", "url": "https://api.weather.com/v1/current"}' \
  https://arko.arcaelas.com/v2/powers

Parameter Update Semantics

Parameter with id + name: null → DELETE
Parameter with id + name value → UPDATE
Parameter without id → CREATE

This allows mixed create/update/delete operations in a single request.

API Keys

Manage your API keys programmatically. Note: API key endpoints require Firebase JWT authentication (not API key auth).

List Keys

GET/v2/keys

Request

curl -H "Authorization: Bearer arko_your_api_key_here" \
  https://arko.arcaelas.com/v2/keys

Note: SHA Field Truncation

The sha field is truncated in list responses for security (shows first 12 characters + "..."). Full key is only returned on creation (POST /v2/keys) or via GET /v2/keys/:id.

Create Key

POST/v2/keys

Request

curl -X POST \
  -H "Authorization: Bearer arko_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{"name": "production-key"}' \
  https://arko.arcaelas.com/v2/keys

Important: The full API key value is only returned once at creation time. Store it securely immediately.

Object Schemas

Detailed schemas for all API objects returned by the Arko Studio API.

Agent

AI assistants with configurable personalities, models, and tools.

Agent Object

{
  "id": string,              // Unique identifier (UUID)
  "uid": string,             // User ID (owner)
  "name": string,            // Agent name (max 200 chars, lowercase alphanumeric)
  "content": string,         // System prompt/description (max 5000 chars)
  "memory": boolean,         // Whether agent uses user memories
  "created_at": string,      // ISO 8601 timestamp
  "updated_at": string       // ISO 8601 timestamp
}

Chat

Conversation threads with agents containing message history.

Chat Object

{
  "id": string,              // Unique identifier (UUID)
  "uid": string,             // User ID (owner)
  "aid": string,             // Agent ID
  "name": string,            // Chat name (max 200 chars)
  "archived": boolean,       // Whether chat is archived
  "created_at": string,      // ISO 8601 timestamp
  "updated_at": string       // ISO 8601 timestamp
}

Message

Individual messages within a chat. Can be user, assistant, or tool messages.

Message Object

{
  "id": string,              // Unique identifier (UUID)
  "cid": string,             // Chat ID
  "role": "user" | "assistant" | "tool",
  "content": string,         // Message content (max 5000 chars)
  "tool_call_id": string,    // Tool call ID (for role: "tool" only)
  "created_at": string,      // ISO 8601 timestamp
  "updated_at": string       // ISO 8601 timestamp
}

Memory

Persistent information that agents can remember across conversations.

Memory Object

{
  "id": string,              // Unique identifier (UUID)
  "uid": string,             // User ID (owner)
  "content": string,         // Memory content (max 500 chars)
  "created_at": string,      // ISO 8601 timestamp
  "updated_at": string       // ISO 8601 timestamp
}

Power

Custom tools that extend agent capabilities via webhooks.

Power Object

{
  "id": string,              // Unique identifier (UUID)
  "uid": string,             // User ID (owner)
  "name": string,            // Power name (max 200 chars)
  "content": string,         // Power description (max 500 chars)
  "url": string,             // Webhook URL (max 1024 chars)
  "method": string,          // HTTP method (GET, POST, PUT, PATCH, DELETE)
  "x_header_key": string,    // Auth header key (max 500 chars)
  "x_header_value": string,  // Auth header value (max 1024 chars)
  "created_at": string,      // ISO 8601 timestamp
  "updated_at": string       // ISO 8601 timestamp
}

Parameter

Parameters for Power tools, defining input requirements.

Parameter Object

{
  "id": string,              // Unique identifier (UUID)
  "pid": string,             // Power ID
  "name": string,            // Parameter name (max 200 chars)
  "content": string,         // Parameter description (max 500 chars)
  "value": string,           // Default value (max 200 chars)
  "required": boolean,       // Whether parameter is required
  "created_at": string,      // ISO 8601 timestamp
  "updated_at": string       // ISO 8601 timestamp
}

API Key

Authentication credentials for API access.

API Key Object

{
  "id": string,              // Unique identifier (UUID)
  "uid": string,             // User ID (owner)
  "name": string,            // Key name (max 100 chars)
  "sha": string,             // Full API key (format: sk-{64 hex chars})
  "scopes": string[],        // Permission scopes
  "expired_at": string,      // Expiration timestamp (empty = never expires)
  "created_at": string,      // ISO 8601 timestamp
  "updated_at": string       // ISO 8601 timestamp
}

Note: The sha field containing the full API key is only returned when creating a new key. List operations return a truncated version for security.

ToolCall

Tool/function calls made by assistant messages.

ToolCall Object

{
  "id": string,              // Unique identifier (UUID)
  "mid": string,             // Message ID (assistant message)
  "tcid": string,            // OpenAI tool call ID (call_xxx)
  "name": string,            // Function/tool name
  "arguments": string        // JSON string of arguments
}

Pagination

List endpoints that return multiple items support pagination using offset and limit query parameters.

Query Parameters

Parameter	Type	Default	Description
offset	integer	0	Number of items to skip
limit	integer	20	Maximum number of items to return (max: 100)

Response Format

Paginated responses include the data array, total count, and pagination metadata.

Paginated Response

{
  "success": true,
  "data": {
    "rows": [
      {
        "id": "agent_abc123",
        "name": "arko",
        "content": "You are Arko...",
        "created_at": "2026-01-15T10:30:00.000Z"
      },
      {
        "id": "agent_def456",
        "name": "customer-support",
        "content": "You are a customer support agent...",
        "created_at": "2026-01-16T14:22:00.000Z"
      }
    ],
    "count": 42,        // Total number of items
    "offset": 0,        // Current offset
    "limit": 20         // Current limit
  }
}

Example Usage

Request with Pagination

# Get the second page of agents (items 20-39)
curl -H "Authorization: Bearer arko_your_api_key_here" \
  "https://arko.arcaelas.com/v2/agents?offset=20&limit=20"

# Get first 5 chats
curl -H "Authorization: Bearer arko_your_api_key_here" \
  "https://arko.arcaelas.com/v2/chats?limit=5"

Pagination Limits: The maximum limit value is 100. Requests exceeding this will be capped at 100 items per page.

Response Format

All API responses follow a consistent JSON format with a success boolean and either a data or error field.

Success Response

{
  "success": true,
  "data": {
    "id": "agent_abc123",
    "name": "arko",
    "content": "You are Arko..."
  }
}

Error Response

{
  "success": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid or expired API key"
  }
}

Errors

The API uses standard HTTP status codes. Here are the most common error responses:

Status	Code	Description
400	BAD_REQUEST	Invalid request body or parameters
401	UNAUTHORIZED	Missing or invalid authentication token
403	FORBIDDEN	Insufficient permissions
404	NOT_FOUND	Resource not found
429	RATE_LIMITED	Too many requests, try again later
500	INTERNAL_ERROR	Internal server error

Rate Limits

API requests are rate-limited to ensure fair usage. Limits vary by plan:

Plan	Requests/Minute	Daily Limit
Free	50	1,000
Premium	200	Unlimited

Rate limit information is included in response headers:

Rate Limit Headers

X-RateLimit-Limit: 50
X-RateLimit-Remaining: 47
X-RateLimit-Reset: 1707307200

Code Examples

Complete examples for common use cases.

Create an Agent and Start a Conversation

Step 1: Create Agent

curl -X POST \
  -H "Authorization: Bearer arko_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "customer-support",
    "content": "You are a customer support agent for an e-commerce platform. Be helpful, concise, and empathetic.",
    "memory": true
  }' \
  https://arko.arcaelas.com/v2/agents

Step 2: Send a Message

curl -X POST \
  -H "Authorization: Bearer arko_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "agentId": "AGENT_ID_FROM_STEP_1",
    "content": "I need help with my order #12345",
    "stream": true
  }' \
  https://arko.arcaelas.com/v2/messages

JavaScript/TypeScript Example

example.ts

const API_BASE = "https://arko.arcaelas.com/v2";
const API_KEY = "arko_your_api_key_here";

async function createAgent() {
  const response = await fetch(`${API_BASE}/agents`, {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      name: "my-agent",
      content: "You are a helpful assistant.",
      memory: true,
    }),
  });

  const data = await response.json();
  return data.data;
}

async function sendMessage(agentId: string, content: string) {
  const response = await fetch(`${API_BASE}/messages?stream=true`, {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ agentId, content }),
  });

  const reader = response.body?.getReader();
  const decoder = new TextDecoder();

  while (reader) {
    const { done, value } = await reader.read();
    if (done) break;

    const chunk = decoder.decode(value);
    const lines = chunk.split("\n").filter(Boolean);

    for (const line of lines) {
      const event = JSON.parse(line);
      if (event.type === "delta") {
        process.stdout.write(event.content);
      }
    }
  }
}

// Usage
const agent = await createAgent();
await sendMessage(agent.id, "Hello! What can you do?");

Python Example

example.py

import requests
import json

API_BASE = "https://arko.arcaelas.com/v2"
API_KEY = "arko_your_api_key_here"

headers = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json"
}

# Create an agent
agent_response = requests.post(
    f"{API_BASE}/agents",
    headers=headers,
    json={
        "name": "python-agent",
        "content": "You are a helpful Python assistant.",
        "memory": True
    }
)
agent = agent_response.json()["data"]
print(f"Created agent: {agent['id']}")

# Send a message with streaming
response = requests.post(
    f"{API_BASE}/messages",
    headers=headers,
    json={
        "agentId": agent["id"],
        "content": "Write a hello world in Python",
        "stream": True
    },
    stream=True
)

for line in response.iter_lines():
    if line:
        event = json.loads(line)
        if event["type"] == "delta":
            print(event["content"], end="", flush=True)

print()  # New line after streaming

API Documentation

Introduction

Authentication

API Playground

Request Body

Endpoints

Agents

List Agents

Create Agent

Chats

List Chats

Send Message to Chat

Messages

Memories

List Memories

Create Memory

Powers

List Powers

Create Power

API Keys

List Keys

Create Key

Object Schemas

Agent

Chat

Message

Memory

Power

Parameter

API Key

ToolCall

Pagination

Query Parameters

Response Format

Example Usage

Response Format

Errors

Rate Limits

Code Examples

Create an Agent and Start a Conversation

JavaScript/TypeScript Example

Python Example

API Documentation

Introduction

Authentication

API Playground

Request Body

Endpoints

Agents

List Agents

Create Agent

Chats

List Chats

Send Message to Chat

Messages

Memories

List Memories

Create Memory

Powers

List Powers

Create Power

API Keys

List Keys

Create Key

Object Schemas

Agent

Chat

Message

Memory

Power

Parameter

API Key

ToolCall

Pagination

Query Parameters

Response Format

Example Usage

Response Format

Errors

Rate Limits