Korelos AI Studio API

Build, deploy, and run autonomous AI agents with a single API call. Define agents in plain English, attach tools, and ship to production — no orchestration code required.

Quickstart

Create your first agent in three steps. The agent below is wired up to handle customer support questions, look up orders, and email customers — all in a single POST /v1/agents call.

1. Install the SDK (or use plain HTTP)

# Node.js
npm install @korelos/sdk

# Python
pip install korelos

# Or just curl — every endpoint is plain JSON over HTTPS
curl https://api.korelos.com/v1/agents

2. Create an agent

curl https://api.korelos.com/v1/agents \
  -H "Authorization: Bearer $KORELOS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "support-agent-v1",
    "model": "korelos-pro",
    "instructions": "You are a customer support agent. Look up orders, process refunds, escalate complex issues.",
    "tools": ["orders_api", "email_sender", "crm_writer"],
    "memory": { "enabled": true, "scope": "per_user" }
  }'

3. Run a task

curl https://api.korelos.com/v1/agents/agt_8f2k9xm3/run \
  -H "Authorization: Bearer $KORELOS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "input": "Where is order #44218? It was supposed to arrive yesterday.",
    "user_id": "u_392"
  }'

# Response
{
  "run_id": "run_b7q3z1",
  "status": "completed",
  "output": "Order #44218 shipped on Apr 21 and is currently with the courier...",
  "tool_calls": ["orders_api.lookup", "crm_writer.note"],
  "tokens": 412,
  "latency_ms": 1284
}

Authentication

All requests are authenticated with a bearer token. You’ll receive an API key after your early-access account is provisioned. Pass it on every request via the Authorization header.

Authorization: Bearer korelos_sk_live_...
Content-Type: application/json

• Keys can be scoped to specific agents and operations (read, write, execute).
• Keys are one-way hashed at rest. Lost keys cannot be recovered — rotate via the Studio Portal.
• Production keys (korelos_sk_live_*) and test keys (korelos_sk_test_*) are isolated; test keys never bill.

Agents

An agent is a configured combination of instructions, tools, model, and memory rules. Agents are first-class resources — you create one, then run tasks against it. They live until you delete them.

Create

{
  "name": "support-agent-v1",
  "model": "korelos-pro" | "openai:gpt-4o" | "anthropic:claude-sonnet-4",
  "instructions": "...",
  "tools": ["orders_api", "email_sender"],
  "memory": { "enabled": true, "scope": "per_user" | "per_session" | "global" },
  "max_steps": 10,
  "timeout_ms": 30000
}

List, get, update, delete

Runs

A run is a single task sent to an agent. Runs are stateful — you can poll for completion, stream tokens, or fire-and-forget with a webhook callback.

{
  "input": "...",
  "user_id": "u_392",
  "stream": false,
  "callback_url": "https://your-app.com/agent-webhook",
  "context": { "order_id": "#44218" }
}

Run results contain the final output, the ordered list of tool_calls, the underlying steps for debugging, token usage, and latency. Streaming runs emit Server-Sent Events with token, tool_call, tool_result, and done event types.

Tools

Tools are how agents interact with the outside world — APIs, databases, email, Slack, your CRM. Korelos ships with 31 first-party integrations and accepts arbitrary custom tools defined as JSON Schema.

{
  "name": "orders_api",
  "description": "Look up order status, shipping info, and history.",
  "endpoint": "https://api.acme.com/orders/{order_id}",
  "method": "GET",
  "auth": { "type": "bearer", "token_secret_id": "sec_acme_orders" },
  "parameters": {
    "order_id": { "type": "string", "required": true }
  }
}

First-party tools include OpenAI, Anthropic, AWS, Google Cloud, Slack, Stripe, GitHub, Azure, PostgreSQL, Twilio, HubSpot, Notion, Salesforce, Zendesk, and more — full list in the Studio Portal.

Memory

Korelos provides three memory modes for stateful agent behavior across runs:

• per_user — facts and context are scoped to the user_id on each run. Best for support and personalization.
• per_session — memory persists for the duration of a session and is cleared after expiry. Best for transactional flows.
• global — agent-wide knowledge that persists indefinitely. Best for internal-knowledge agents.

Memory is stored encrypted at rest (AES-256) and is fully erasable via DELETE /v1/agents/{id}/memory.

Errors

Korelos uses conventional HTTP status codes. The response body always contains a structured error object:

{
  "error": {
    "code": "tool_execution_failed",
    "message": "orders_api returned 503: upstream unavailable",
    "request_id": "req_9f3xq1",
    "retryable": true
  }
}

Rate limits

Limits are per-API-key, sliding-window, and surfaced in response headers:

X-Korelos-RateLimit-Limit: 1000
X-Korelos-RateLimit-Remaining: 837
X-Korelos-RateLimit-Reset: 1719511200

Changelog

• 2026-04 · v0.9 (private) — added streaming runs, per-user memory scope, callback webhooks.
• 2026-02 · v0.8 (private) — first-party tool catalog (31 integrations), Studio Portal beta.
• 2025-11 · v0.7 (private) — multi-model support (OpenAI, Anthropic, korelos-pro), agent versioning.
• 2025-08 · v0.5 (alpha) — first internal alpha: REST API and agent runtime.