API DOCUMENTATION
Complete technical reference for integrating Arko via API Keys
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
Agents, Chats, Messages, and Powers use /v3/ endpoints. Auth, Keys, and Memories use /v2/ endpoints.
All API requests must include an API Key in the Authorization header using Bearer token format.
curl -H "Authorization: Bearer arko_your_api_key_here" \
https://arko.arcaelas.com/v3/agentsNote
sk-... and are shown only once when created. Store them securely. Some endpoints (auth, keys) require Firebase JWT tokens and cannot be accessed via API keys.| Scope | Access |
|---|---|
| agents:read | List and get agents |
| agents:write | Create, update, delete agents |
| chats:read | List and get chats and messages |
| chats:write | Send messages, update, delete chats |
| powers:read | List and get powers |
| powers:write | Create, update, delete powers |
| memories:read | List and get memories |
| memories:write | Create, update, delete memories |
| keys:read | List and get API keys |
| keys:delete | Delete API keys |
| _jwt_only | Operations restricted to Firebase JWT (auth profile, key management) |
Test API endpoints directly from your browser. Select an endpoint, fill in parameters, and execute requests using your API key.
All available endpoints documented with real request/response examples.
| Method | Endpoint | Description | Scope |
|---|---|---|---|
| POST | /v2/auth | Register user (JWT only, idempotent) | none (JWT) |
| GET | /v2/auth | Get current user | any |
| PUT | /v2/auth | Update user profile | JWT only |
| DELETE | /v2/auth | Delete user account | JWT only |
| GET | /v3/agents | List agents | agents:read |
| POST | /v3/agents | Create agent | agents:write |
| GET | /v3/agents/:id | Get agent detail | agents:read |
| PUT | /v3/agents/:id | Update agent | agents:write |
| DELETE | /v3/agents/:id | Delete agent | agents:write |
| GET | /v3/chats | List chats | chats:read |
| GET | /v3/chats/:id | Get chat detail | chats:read |
| PUT | /v3/chats/:id | Update chat | chats:write |
| DELETE | /v3/chats/:id | Delete chat | chats:write |
| GET | /v3/chats/:id/messages | List chat messages | chats:read |
| POST | /v3/messages | Send message (stream/JSON) | chats:write |
| GET | /v3/powers | List powers | powers:read |
| POST | /v3/powers | Create power | powers:write |
| GET | /v3/powers/:id | Get power detail | powers:read |
| PUT | /v3/powers/:id | Update power | powers:write |
| DELETE | /v3/powers/:id | Delete power | powers:write |
| GET | /v2/memories | List memories | memories:read |
| POST | /v2/memories | Create memory | memories:write |
| GET | /v2/memories/:id | Get memory | memories:read |
| PUT | /v2/memories/:id | Update memory | memories:write |
| DELETE | /v2/memories/:id | Delete memory | memories:write |
| GET | /v2/keys | List API keys | JWT only |
| POST | /v2/keys | Create API key | JWT only |
| GET | /v2/keys/:id | Get API key | JWT only |
| PUT | /v2/keys/:id | Update API key | JWT only |
| DELETE | /v2/keys/:id | Delete API key | JWT only |
Manage AI agents and their configuration.
/v3/agentscurl -H "Authorization: Bearer arko_your_api_key_here" \
"https://arko.arcaelas.com/v3/agents?limit=10&order=DESC"{
"success": true,
"data": {
"rows": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "My Agent",
"content": "You are a helpful assistant...",
"memory": true,
"web": false,
"images": false,
"created_at": "2026-01-15T10:30:00.000Z",
"updated_at": "2026-01-15T10:30:00.000Z"
}
],
"count": 1,
"offset": 0,
"limit": 10
}
}Default order
order parameter is specified, results are sorted ASC (oldest first). Set ?order=DESC for newest first.Field Truncation
content field is truncated to 300 characters in list responses. Use GET /v3/agents/:id to retrieve full content with attached powers./v3/agentscurl -X POST \
-H "Authorization: Bearer arko_your_api_key_here" \
-H "Content-Type: application/json" \
-d '{"name": "Support Bot", "content": "You help users with technical issues.", "memory": true}' \
https://arko.arcaelas.com/v3/agents{
"success": true,
"data": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "Support Bot",
"content": "You help users with technical issues.",
"memory": true,
"web": false,
"images": false,
"created_at": "2026-01-15T10:30:00.000Z",
"updated_at": "2026-01-15T10:30:00.000Z"
}
}JWT-only fields
memory, web, and images can only be set to true when authenticated via Firebase JWT. API Key requests will have these forced to false.Manage conversations with AI agents.
Note
aid parameter. There is no separate chat creation endpoint./v3/chatscurl -H "Authorization: Bearer arko_your_api_key_here" \
"https://arko.arcaelas.com/v3/chats?archived=false&limit=20"{
"success": true,
"data": {
"rows": [
{
"id": "c1a2b3d4-e5f6-7890-abcd-111111111111",
"name": "My Conversation",
"content": "Last message preview...",
"archived": false,
"agent": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "My Agent"
},
"created_at": "2026-01-01T00:00:00Z",
"updated_at": "2026-01-01T12:00:00Z"
}
],
"count": 1,
"offset": 0,
"limit": 20
}
}/v3/chats/:id/messagescurl -H "Authorization: Bearer arko_your_api_key_here" \
"https://arko.arcaelas.com/v3/chats/CHAT_ID/messages?order=ASC"{
"success": true,
"data": {
"rows": [
{
"id": "d1e2f3a4-b5c6-7890-abcd-222222222222",
"role": "user",
"content": "Hello!",
"type": "text",
"created_at": "2026-01-01T00:00:00Z",
"updated_at": "2026-01-01T00:00:00Z"
},
{
"id": "e2f3a4b5-c6d7-8901-bcde-333333333333",
"role": "assistant",
"content": "Hi there! How can I help?",
"type": "text",
"created_at": "2026-01-01T00:00:01Z",
"updated_at": "2026-01-01T00:00:01Z"
}
],
"count": 2,
"offset": 0,
"limit": 10
}
}user and assistant messages with non-empty content are returned. Tool messages are hidden. Ordered by created_at.Send a message to an agent. Creates a new chat if aid is provided, or uses existing chat with cid.
/v3/messages| Field | Type | Required | Description |
|---|---|---|---|
| content | string | Yes | Message text |
| cid | string | No* | Chat ID (use existing chat, priority over aid) |
| aid | string | No* | Agent ID (creates new chat if no cid) |
| stream | boolean | No | NDJSON streaming (default: true) |
* Must provide cid OR aid. If cid is provided, it takes priority.
curl -X POST \
-H "Authorization: Bearer arko_your_api_key_here" \
-H "Content-Type: application/json" \
-d '{"aid": "AGENT_ID", "content": "Hello!", "stream": false}' \
https://arko.arcaelas.com/v3/messages{
"success": true,
"data": {
"chat": {
"id": "c1a2b3d4-e5f6-7890-abcd-111111111111",
"name": "Hello!",
"agent": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "My Agent"
}
},
"messages": [
{
"id": "d1e2f3a4-b5c6-7890-abcd-222222222222",
"cid": "c1a2b3d4-e5f6-7890-abcd-111111111111",
"role": "user",
"content": "Hello!",
"type": "text",
"created_at": "2026-01-01T00:00:00Z",
"updated_at": "2026-01-01T00:00:00Z"
},
{
"id": "e2f3a4b5-c6d7-8901-bcde-333333333333",
"cid": "c1a2b3d4-e5f6-7890-abcd-111111111111",
"role": "assistant",
"content": "Hi there! How can I help?",
"type": "text",
"created_at": "2026-01-01T00:00:01Z",
"updated_at": "2026-01-01T00:00:01Z"
}
]
}
}Streaming Support
When stream: true (default), the response is NDJSON (Content-Type: application/x-ndjson) with event types:
{"type": "chat", "id": "...", "name": "...", "agent": {"id": "...", "name": "..."}}
{"type": "message", "id": "...", "role": "user", "content": "Hello!"}
{"type": "message_start", "id": "..."}
{"type": "delta", "content": "chunk of text"}
{"type": "message_end", "id": "..."}
{"type": "done", "messages": [{"id": "...", "role": "user", "content": "...", "type": "text"}, {"id": "...", "role": "assistant", "content": "...", "type": "text"}]}
{"type": "error", "message": "...", "code": "ERR_STREAM"}Store persistent user information that agents can access.
/v2/memoriescurl -H "Authorization: Bearer arko_your_api_key_here" \
https://arko.arcaelas.com/v2/memories{
"success": true,
"data": {
"rows": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"content": "User prefers TypeScript over JavaScript",
"created_at": "2026-01-01T00:00:00Z",
"updated_at": "2026-01-01T00:00:00Z"
}
],
"count": 1,
"offset": 0,
"limit": 10
}
}/v2/memoriescurl -X POST \
-H "Authorization: Bearer arko_your_api_key_here" \
-H "Content-Type: application/json" \
-d '{"content": "User prefers responses in Spanish"}' \
https://arko.arcaelas.com/v2/memories{
"success": true,
"data": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"content": "User prefers responses in Spanish",
"created_at": "2026-01-01T12:00:00Z",
"updated_at": "2026-01-01T12:00:00Z"
}
}Create custom tools that agents can use to interact with external APIs.
/v3/powerscurl -H "Authorization: Bearer arko_your_api_key_here" \
https://arko.arcaelas.com/v3/powers{
"success": true,
"data": {
"rows": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "weather",
"content": "Get current weather data",
"url": "https://api.weather.com/forecast",
"created_at": "2026-01-01T00:00:00Z",
"updated_at": "2026-01-01T00:00:00Z"
}
],
"count": 1,
"offset": 0,
"limit": 10
}
}List Response Fields
webhook and parameters fields are NOT included in list responses. Use GET /v3/powers/:id to retrieve full power details including parameters and webhook config./v3/powerscurl -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/forecast", "parameters": [{"name": "location", "content": "City name", "required": true}]}' \
https://arko.arcaelas.com/v3/powers{
"success": true,
"data": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "weather",
"content": "Gets current weather data",
"webhook": {
"url": "https://api.weather.com/forecast",
"header": {}
},
"parameters": [
{
"id": "f1e2d3c4-b5a6-7890-fedc-ba0987654321",
"name": "location",
"content": "City name",
"value": "",
"required": true
}
],
"created_at": "2026-01-01T12:00:00Z",
"updated_at": "2026-01-01T12:00:00Z"
}
}Parameter Update Semantics (PUT /v3/powers/:id)
id + name: null → DELETEid + name value → UPDATEid → CREATEThis allows mixed create/update/delete operations in a single request.
Manage API keys for programmatic access (JWT-only endpoint).
/v2/keyscurl -H "Authorization: Bearer YOUR_JWT_TOKEN" \
https://arko.arcaelas.com/v2/keysJWT-Only Endpoint:
sha field is truncated in list responses (first 10 characters + "..."). The full key is only returned on creation (POST /v2/keys)./v2/keyscurl -X POST \
-H "Authorization: Bearer YOUR_JWT_TOKEN" \
-H "Content-Type: application/json" \
-d '{"name": "production-key", "scopes": ["agents:read", "chats:read", "chats:write"]}' \
https://arko.arcaelas.com/v2/keys{
"success": true,
"data": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "production-key",
"sha": "sk-1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234",
"scopes": ["agents:read", "chats:read", "chats:write"],
"expired_at": "",
"created_at": "2026-01-01T12:00:00Z",
"updated_at": "2026-01-01T12:00:00Z"
}
}Important
sha) is only returned once at creation time. Store it securely immediately.Detailed schemas for all API objects returned by the Arko Studio API.
AI assistants with configurable capabilities and attached powers.
{
"id": string, // UUID
"name": string, // Agent name (max 200 chars)
"content": string, // System prompt (truncated to 300 chars in list)
"memory": boolean, // Persistent memory enabled
"web": boolean, // Web search enabled
"images": boolean, // Image generation enabled
"created_at": string, // ISO 8601
"updated_at": string // ISO 8601
}{
// ...same fields as list, plus:
"powers": [ // Attached powers with full details
{
"id": string,
"name": string,
"content": string,
"webhook": { "url": string, "header": Record<string, string> },
"parameters": [{ "id": string, "name": string, "content": string, "value": string, "required": boolean }],
"created_at": string,
"updated_at": string
}
]
}Conversation threads with agents. Created automatically via POST /v3/messages.
{
"id": string, // UUID
"name": string, // Chat name (max 200 chars)
"content": string, // Last message preview (truncated to 150 chars)
"archived": boolean, // Archive status
"agent": { // Associated agent reference
"id": string,
"name": string
},
"created_at": string, // ISO 8601
"updated_at": string // ISO 8601
}Individual messages within a chat (only user and assistant roles are visible via API).
{
"id": string, // UUID
"role": "user" | "assistant",
"content": string, // Message text or image URL
"type": "text" | "image", // Message type
"created_at": string, // ISO 8601
"updated_at": string // ISO 8601
}Persistent information that agents with memory enabled can access.
{
"id": string, // UUID
"content": string, // Memory content (max 500 chars)
"created_at": string, // ISO 8601
"updated_at": string // ISO 8601
}Custom webhook tools that extend agent capabilities.
{
"id": string, // UUID
"name": string, // Power name (max 200 chars)
"content": string, // Description (max 500 chars)
"webhook": {
"url": string, // Webhook URL
"header": Record<string, string> // Auth headers
},
"parameters": [
{
"id": string, // UUID
"name": string, // Parameter name (max 200 chars)
"content": string, // Description (max 500 chars)
"value": string, // Default value (max 200 chars)
"required": boolean // Whether required
}
],
"created_at": string, // ISO 8601
"updated_at": string // ISO 8601
}{
"id": string,
"name": string,
"content": string, // Truncated to 300 chars
"url": string, // Webhook URL
"created_at": string,
"updated_at": string
}Authentication credentials for programmatic API access.
{
"id": string, // UUID
"name": string, // Key name (max 100 chars)
"sha": string, // API key (sk-{64 hex chars}), truncated in list
"scopes": string[], // Permission scopes
"expired_at": string, // Expiration (ISO 8601, empty = never)
"created_at": string, // ISO 8601
"updated_at": string // ISO 8601
}Note
sha field containing the full API key is only returned when creating a new key (POST /v2/keys). List operations return a truncated version (first 10 chars + "...").List endpoints support pagination using offset, limit, order, and search query parameters.
| Parameter | Type | Default | Description |
|---|---|---|---|
| offset | integer | 0 | Number of items to skip |
| limit | integer | 10 | Maximum items to return (1-100) |
| order | string | ASC | Sort direction (ASC or DESC) |
| search | string | - | Partial name/content filter |
{
"success": true,
"data": {
"rows": [...],
"count": 42, // Total items matching query
"offset": 0, // Applied offset
"limit": 10 // Applied limit
}
}# Get second page of agents (items 20-39)
curl -H "Authorization: Bearer arko_your_api_key_here" \
"https://arko.arcaelas.com/v3/agents?offset=20&limit=20"
# Search chats by name
curl -H "Authorization: Bearer arko_your_api_key_here" \
"https://arko.arcaelas.com/v3/chats?search=support&limit=5"All API responses follow a consistent structure with success/error indicators.
{
"success": true,
"data": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "My Agent",
"content": "You are a helpful assistant..."
}
}{
"success": false,
"message": "NOT_FOUND",
"cause": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"code": "ERR_NOT_FOUND"
}
}{
"success": true,
"data": null
}All errors follow a standard format with HTTP status codes and descriptive messages.
| Status | Code | Description |
|---|---|---|
| 400 | ERR_VALIDATION | Invalid request body or parameters |
| 400 | ERR_INVALID_JSON | Malformed JSON in request body |
| 401 | ERR_NO_TOKEN | Missing or invalid authentication token |
| 403 | ERR_INSUFFICIENT_SCOPE | API Key lacks required scope for this endpoint |
| 403 | ERR_FORBIDDEN | Action not allowed (e.g. API Key used on JWT-only endpoint) |
| 403 | ERR_CAPACITY_LIMIT | Account resource limit reached |
| 404 | ERR_NOT_FOUND | Resource not found |
| 415 | ERR_INVALID_CONTENT_TYPE | Content-Type must be application/json for POST/PUT/PATCH |
| 500 | - | Internal server error |
Complete examples for common use cases.
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.",
"memory": true
}' \
https://arko.arcaelas.com/v3/agentscurl -X POST \
-H "Authorization: Bearer arko_your_api_key_here" \
-H "Content-Type: application/json" \
-d '{
"aid": "AGENT_ID_FROM_STEP_1",
"content": "I need help with my order #12345",
"stream": false
}' \
https://arko.arcaelas.com/v3/messagesconst API_KEY = "arko_your_api_key_here";
async function createAgent() {
const response = await fetch("https://arko.arcaelas.com/v3/agents", {
method: "POST",
headers: {
"Authorization": `Bearer ${API_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
name: "my-agent",
content: "You are a helpful assistant.",
}),
});
const { data } = await response.json();
return data;
}
async function sendMessage(agentId: string, content: string) {
const response = await fetch("https://arko.arcaelas.com/v3/messages", {
method: "POST",
headers: {
"Authorization": `Bearer ${API_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({ aid: agentId, content, stream: true }),
});
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?");import requests
import json
API_KEY = "arko_your_api_key_here"
headers = {
"Authorization": f"Bearer {API_KEY}",
"Content-Type": "application/json"
}
# Create an agent
agent_response = requests.post(
"https://arko.arcaelas.com/v3/agents",
headers=headers,
json={
"name": "python-agent",
"content": "You are a helpful Python assistant.",
}
)
agent = agent_response.json()["data"]
print(f"Created agent: {agent['id']}")
# Send a message with streaming
response = requests.post(
"https://arko.arcaelas.com/v3/messages",
headers=headers,
json={
"aid": 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