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

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.

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

↗