Agent context

# Worg agent context

> Worg is an OpenAI-compatible API for AI inference. Base URL: https://api.getworg.com/v1. This file is the short version of https://docs.getworg.com; the full docs are at https://docs.getworg.com/llms-full.txt.

## Rules

- Base URL: https://api.getworg.com/v1. Use the official OpenAI SDK with this base URL, or plain HTTP.
- Endpoints: POST /v1/chat/completions and GET /v1/models. Nothing else exists under /v1.
- Model: use an ID from GET /v1/models, for example deepseek-v4.1-flash:cached. Do not guess IDs.
- Always set max_tokens.
- Read the API key from the WORG_API_KEY environment variable. Never write the key into code, config files, tests, the repository or logs, and never print it. If the variable is not set, stop and ask the user to set it.
- Call the API from server-side code only, never from a browser.
- Branch on the error code field, not the message. Retry 429 and 502 with backoff.
- Before concluding that your code is wrong after a 5xx or a timeout, fetch https://status.getworg.com/api/status.json and check whether a component is down.

## Request

```bash
curl https://api.getworg.com/v1/chat/completions \
  -H "Authorization: Bearer $WORG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "deepseek-v4.1-flash:cached",
    "messages": [{"role": "user", "content": "Say hello in Indonesian."}],
    "max_tokens": 512
  }'
```

With the OpenAI SDK for Python:

```python
import os
from openai import OpenAI

client = OpenAI(
    base_url="https://api.getworg.com/v1",
    api_key=os.environ["WORG_API_KEY"],
)

response = client.chat.completions.create(
    model="deepseek-v4.1-flash:cached",
    messages=[{"role": "user", "content": "Say hello in Indonesian."}],
    max_tokens=512,
)
print(response.model)
print(response.choices[0].message.content)
```

## Models

From GET /v1/models when these docs were built. Call it again for the current list.

- `deepseek-v4.1-flash:cached`: DeepSeek V4.1 Flash, context 1,048,576 tokens
- `deepseek-v4.1-flash:standard`: DeepSeek V4.1 Flash, context 1,048,576 tokens
- `qwen3.8-27b:standard`: Qwen3.8 27B, context 262,144 tokens

A model name alone tries its lanes in this order and moves to the next lane if one fails. The response's model field names the lane that answered.

- `deepseek-v4.1-flash`: `deepseek-v4.1-flash:cached`, then `deepseek-v4.1-flash:standard`
- `qwen3.8-27b`: `qwen3.8-27b:standard`

## Not available

Only POST /v1/chat/completions and GET /v1/models exist. There is no Responses API, no Anthropic Messages API, no embeddings, no audio and no image generation. A client that needs one of them will get 404 not_found.

## First checks

- List the models with your key: curl https://api.getworg.com/v1/models -H "Authorization: Bearer $WORG_API_KEY". A list back means the key and base URL are right.
- Read the code field of the error, not only the message. The message can change; the code does not.
- Keep the x-request-id header from the response. Send it with any question to team@getworg.com.

## Troubleshooting

| Symptom | Check |
| --- | --- |
| 5xx errors or timeouts | Check the status page first: https://status.getworg.com. If it shows an incident, the fault is on the Worg side and your code can stay as it is; retry with backoff until it clears. If everything is up, send the x-request-id to team@getworg.com. See https://status.getworg.com. |
| 401 invalid_api_key | The key is missing, wrong, or has quotes or spaces around it. Check that WORG_API_KEY is set in the process that sends the request, and that the header is Authorization: Bearer <key>. See https://docs.getworg.com/authentication#send-the-key. |
| 404 not_found on every request | The base URL is wrong. It must be exactly https://api.getworg.com/v1: with /v1, and without /chat/completions at the end. Clients add the path themselves. See https://docs.getworg.com/connect-clients#settings. |
| 404 not_found on /v1/responses, /v1/messages or /v1/embeddings | The client calls an API that Worg does not offer. Switch it to Chat Completions. In the Vercel AI SDK, use the OpenAI-compatible provider or openai.chat(), not openai(). See https://docs.getworg.com/connect-clients#not-supported. |
| 404 model_not_found | The model ID is mistyped or has a prefix the client did not remove. Copy an ID from GET /v1/models, or use combo/<name> for a combo. See https://docs.getworg.com/models. |
| 402 insufficient_balance while the balance still shows money | Worg holds the most a request can cost before sending it. Without max_tokens the hold covers the whole output limit, which can be more than the balance. Set max_tokens; the error message states both amounts. See https://docs.getworg.com/rate-limits#hold. |
| 402 key_budget_exceeded, workspace_budget_exceeded or org_budget_exceeded | A monthly budget is used up. A top-up does not help: an admin raises the budget in the console, or you use another key. See https://docs.getworg.com/errors#key_budget_exceeded. |
| 403 model_not_allowed | The key is limited to other models. An admin adds the model to the key, or you use a key that allows it. See https://docs.getworg.com/authentication#keys. |
| 403 key_suspended | The key spent far more than usual in the last hour. An owner or admin rotates or resumes it in API keys. See https://docs.getworg.com/authentication#suspended-keys. |
| 429 rpm_exceeded, tpm_exceeded or concurrency_exceeded | Your own limits. They apply per key and to the whole organization, so a second key does not add capacity. Wait for the seconds in Retry-After and run fewer requests at once; coding agents that start parallel tasks reach the concurrency limit first. To go higher, write to team@getworg.com. See https://docs.getworg.com/rate-limits#limits. |
| 429 capacity_busy or 502 upstream_unavailable | The lane is busy or briefly down. Retry with backoff. Call the model by its name alone, such as deepseek-v4.1-flash, to let Worg try its other lane in the same request, or use a combo. See https://docs.getworg.com/models#model-without-a-lane. |
| A stream stops with an error chunk | The lane failed after the stream started. A started stream stays on its lane, even in a combo, so send the request again. See https://docs.getworg.com/errors#codes. |
| The answer is cut off (finish_reason "length"), or content is empty and reasoning_content is not | max_tokens ran out. On lanes that reason, the thinking uses output tokens too. Raise max_tokens or lower reasoning_effort. See https://docs.getworg.com/models. |
| A CORS error in the browser | Browsers on other sites cannot call /v1. Call the API from your server and keep the key there. See https://docs.getworg.com/authentication#keep-keys-on-the-server. |

## Error codes

| Status | Code | What to do |
| --- | --- | --- |
| 400 | `invalid_request` | Fix the request. The message names the problem. |
| 401 | `invalid_api_key` | Check the key and the Authorization header. |
| 402 | `insufficient_balance` | Top up, or set a lower max_tokens. |
| 402 | `key_budget_exceeded` | An admin raises the key budget, or use another key. A top-up does not help. |
| 402 | `workspace_budget_exceeded` | An admin raises the workspace budget. |
| 402 | `org_budget_exceeded` | An owner raises the organization budget. |
| 402 | `credit_limit_reached` | Settle the open statement, or ask Worg to raise the limit. |
| 402 | `playground_budget_exceeded` | Use an API key, or wait for the next day (WIB). |
| 403 | `key_disabled` | Create a new key. |
| 403 | `key_expired` | Create a new key. |
| 403 | `key_suspended` | An admin reviews it in API keys, then rotates or resumes it. |
| 403 | `org_suspended` | Contact support. |
| 403 | `org_not_approved` | Wait for the approval email, or contact support. |
| 403 | `model_not_allowed` | An admin changes the key's models, or use another key. |
| 404 | `model_not_found` | Use an ID from GET /v1/models. |
| 404 | `not_found` | Use /v1/chat/completions or /v1/models. |
| 413 | `body_too_large` | Send a shorter request. |
| 413 | `images_too_large` | Send smaller images (2,048 px on the longest side or less) or fewer of them. Through a combo, the next lane is tried first. |
| 429 | `rpm_exceeded` | Retry after the seconds in Retry-After. |
| 429 | `tpm_exceeded` | Retry after 60 seconds (Retry-After). |
| 429 | `concurrency_exceeded` | Retry when one finishes (Retry-After: 1). |
| 429 | `capacity_busy` | Retry after 5 seconds (Retry-After). Calling the model name alone or a combo lets Worg try another lane first. |
| 500 | `internal` | Retry. If it repeats, send the x-request-id to support. |
| 502 | `upstream_unavailable` | Retry with backoff and check the status page. Calling the model name alone or a combo lets Worg try another lane first. |

## More

- Every page in one file: https://docs.getworg.com/llms-full.txt
- Page index: https://docs.getworg.com/llms.txt
- OpenAPI description: https://docs.getworg.com/openapi.json
- Any page as Markdown: add .md to its URL, for example https://docs.getworg.com/errors.md