Quickstart

This page walks through the complete flow with curl:

1. Register and log in (cookie session).
2. Create a workspace.
3. Create an API key (the raw key is shown once).
4. Get a model id from GET /v1/models.
5. Call POST /v1/chat/completions with the key.
6. Check the balance.

Replace https://api.runne.run with your instance base URL.

1. Register

curl -c cookies.txt -X POST https://api.runne.run/v1/auth/register \
  -H 'Content-Type: application/json' \
  -d '{"email":"you@example.com","password":"correct-horse-battery","name":"You"}'

Response (HTTP 201) — registration also logs you in and sets the runne_session cookie:

{ "customer_id": "0191…", "email": "you@example.com" }

password must be at least 8 characters. Re-registering the same email returns 409 email_already_registered.

2. Log in (optional)

If you already have an account:

curl -c cookies.txt -X POST https://api.runne.run/v1/auth/login \
  -H 'Content-Type: application/json' \
  -d '{"email":"you@example.com","password":"correct-horse-battery"}'

Response (HTTP 200):

{ "expires_at": "2026-09-13T09:00:00.000Z" }

3. Create a workspace

curl -b cookies.txt -X POST https://api.runne.run/v1/workspaces \
  -H 'Content-Type: application/json' \
  -d '{"name":"my-app"}'

Response (HTTP 201):

{
  "id": "0191…",
  "customer_id": "0191…",
  "name": "my-app",
  "balance": "0",
  "currency": "RUB",
  "status": "active",
  "created_at": "2026-09-12T00:00:00.000Z",
  "updated_at": "2026-09-12T00:00:00.000Z"
}

Save the workspace id — it is used in every workspace-scoped call.

4. Create an API key

curl -b cookies.txt -X POST https://api.runne.run/v1/workspaces/WORKSPACE_ID/api-keys \
  -H 'Content-Type: application/json' \
  -d '{"name":"prod-key","scopes":["chat:write","balance:read"]}'

Response (HTTP 201):

{
  "id": "0191…",
  "raw_key": "rn_live_4xK9mP2qR7sT_7hJ3kL9mN2pQ5rT8vW1xY4zA6bC0dE2fG4hI6jK8",
  "key_id": "4xK9mP2qR7sT",
  "name": "prod-key",
  "scopes": ["chat:write", "balance:read"],
  "created_at": "2026-09-12T00:00:00.000Z"
}

Save raw_key now

raw_key is returned only once. The server stores only an HMAC of the secret and cannot recover the raw value. Store it in a secrets manager and never log it.

5. Get a model id

Chat requires a model that exists in the catalog with pricing. In beta the catalog starts empty — a platform admin must create the model and its pricing first. Get the id you'll use:

curl https://api.runne.run/v1/models

Use the returned id as the model field in the next step. There is no default model: a value that isn't in the catalog returns 404 not_found (no pricing for the model).

6. Call chat completions

# Use the model id from GET /v1/models.
curl -X POST https://api.runne.run/v1/chat/completions \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer rn_live_4xK9mP2qR7sT_7hJ3kL9mN2pQ5rT8vW1xY4zA6bC0dE2fG4hI6jK8' \
  -d '{"model":"<model-id-from-v1-models>","messages":[{"role":"user","content":"Hello"}]}'

Response (beta returns a mock completion):

{
  "id": "chatcmpl-mock-…",
  "object": "chat.completion",
  "created": 1750000000,
  "model": "mock-model",
  "choices": [
    {
      "index": 0,
      "message": { "role": "assistant", "content": "This is a mock response for demonstration purposes." },
      "finish_reason": "stop"
    }
  ],
  "usage": { "prompt_tokens": 2, "completion_tokens": 50, "total_tokens": 52 }
}

The request requires the chat:write scope and is rate-limited per key. The cost is reserved, then settled against the workspace balance.

7. Check the balance

curl -X GET https://api.runne.run/v1/balance \
  -H 'Authorization: Bearer rn_live_4xK9mP2qR7sT_7hJ3kL9mN2pQ5rT8vW1xY4zA6bC0dE2fG4hI6jK8'

Response (requires balance:read scope):

{ "balance": "0", "currency": "RUB", "updated_at": "2026-09-12T00:00:00.000Z" }

The balance is empty until you top up or an admin adjusts it.

Next steps

• Authentication — the two auth modes in depth.
• Chat Completions — request/response reference.
• Payments & YooKassa — add funds.