Worken API

Worken provides a REST API that lets you build integrations, control AI agents programmatically, stream conversations, and read billing data. It is the same backend powering the Worken dashboard.

Base URL

https://api.worken.ru

API access

There are two deployments of the Worken API:

• Internal API (worken-api) — used only by Worken services and the dashboard. Requests are authorized via Worken-Organization, Worken-Project, and Worken-User headers and go through an internal ingress; this API is not exposed on the public internet.
• External public API (worken-api-public) — exposed at https://api.worken.ru and used by customers. It only accepts project-scoped API keys in the Authorization: Bearer sk-… header and ignores any Worken-* headers.

All customer-facing docs in this section describe the external API at https://api.worken.ru.

Authentication

Every request must carry a project-scoped API key in the Authorization header:

curl https://api.worken.ru/bots \
  -H "Authorization: Bearer sk-your-api-key"

The API key identifies the project the request belongs to. All resources — bots, chats, threads, integrations — are scoped to that project.

Public consumers (SDKs, backends, MCP servers, CLIs) always authenticate with bearer API keys against https://api.worken.ru.

Internally, Worken services and the dashboard call a separate internal API using header-based auth:

• Worken-Organization
• Worken-Project
• Worken-User

These headers are sent only inside Worken's infrastructure via an internal ingress and are not a supported way to authenticate against the public https://api.worken.ru endpoint.

Obtaining an API key

1. Open the Worken dashboard and navigate to Project → API Keys.
2. Click Create key, give it a recognisable name (e.g. production-server), and copy the value.
3. Store it in a secret manager or environment variable. The plain-text value is shown only once.

// Store the key securely, never hardcode it
const client = new WorkenClient({ apiKey: process.env.WORKEN_API_KEY })

import os
from worken import WorkenClient

client = WorkenClient(api_key=os.environ["WORKEN_API_KEY"])

WARNING

Treat your API key like a password. Do not embed it in client-side code or commit it to version control.

Key format

All API keys follow the pattern sk-<hex string>. The prefix sk- is mandatory — requests that omit it are rejected with 401.

Key scopes

Keys are project-scoped. One key grants access to all resources inside a single project. If you need to segment access (e.g. separate read-only integrations from write access), create dedicated keys and manage them individually.

Key rotation

Delete the old key from Project → API Keys and create a replacement. Both keys remain valid simultaneously until the old one is deleted, enabling zero-downtime rotation.

401 — Unauthorized

A missing, malformed, or revoked key returns:

{
  "error": "Unauthorized"
}

Request format

All endpoints accept and return application/json. Include the content-type header on POST / PATCH requests:

curl https://api.worken.ru/bots \
  -X POST \
  -H "Authorization: Bearer sk-..." \
  -H "Content-Type: application/json" \
  -d '{"name": "Support Bot"}'

Response format

Successful responses return 2xx HTTP status with a JSON body. Failed responses return a 4xx or 5xx status:

// Success shape — depends on endpoint
type BotResponse = {
  id: string
  name: string
  status: 'active' | 'disabled' | 'error'
  created_at: string
}

// Error shape — all endpoints
type ErrorResponse = {
  error: string
  message?: string
}

Rate limits

Plan	Requests per minute
Free	60
Starter	300
Pro	600
Enterprise	unlimited

Rate-limited requests receive 429 Too Many Requests with a Retry-After header indicating when you may retry.

Pagination

List endpoints accept limit and offset query parameters:

GET /threads?limit=20&offset=40

Cursor-based pagination is available on /threads via the cursor parameter for real-time feeds.

Versioning

The API is currently at version 1. Breaking changes will be communicated via the changelog at least 60 days in advance.

Related

Learn more

Quick Start

Set up your first agent and connect it to a chat in 5 minutes

↗

Learn more

Endpoints Reference

Full list of available endpoints with request and response types

↗

Learn more

worken npm package

TypeScript SDK, MCP tool hosting, and TUI

↗