# Use the API

> Every endpoint is an OpenAI-compatible API at its own address, so existing OpenAI code works after you change the base URL and the key.

Source: https://bitsrun.com/docs/api/
Updated: 2026-11-09

Each endpoint you deploy gets its own web address, called the base URL. It looks like this:

```text
https://01k8y4000d3m00000000000011.endpoint.bitsrun.com/v1
```

The part before `.endpoint` is your endpoint id. You find the full URL on the endpoint's card in the dashboard (with a **Copy** button), or with `bitsrun status <endpoint>` in the terminal.

Your code sends an API key with every request. An API key is a secret that proves the request comes from you. Create one on the **API keys** page; see [API keys](https://bitsrun.com/docs/api/api-keys/).

## What the API answers

| Path | Method | What it does | Works on |
|---|---|---|---|
| `/v1/chat/completions` | POST | Chat: send messages, get the next reply. Streaming and tool calls supported | Chat models |
| `/v1/completions` | POST | Plain text completion from a prompt | Chat models |
| `/v1/embeddings` | POST | Turns text into vectors (lists of numbers) for search and RAG | Embedding models |
| `/v1/models` | GET | Lists the one model this endpoint serves | Every endpoint |

GGUF models also answer the native Ollama paths (`/api/chat`, `/api/generate`, `/api/embed`, `/api/embeddings`, `/api/tags`) on the same host without `/v1`, so Ollama libraries that can send the `Authorization` header work too (the `ollama` command line app cannot). See [Chat and completions](https://bitsrun.com/docs/api/chat/#ollama-clients).

Any other path answers `404`. Endpoints that only run embeddings answer only `/v1/embeddings` and `/v1/models`.

> [!NOTE]
> The `model` field in your request can be anything. An endpoint serves exactly one model, and BitsRun always uses that model, whatever name you send. Many SDKs require the field, so pass the model name you deployed, for example `qwen3:8b`.

## Your first call

Set your key once in your terminal, then call the endpoint:

```bash
export BITSRUN_API_KEY="brk_..."

curl https://01k8y4000d3m00000000000011.endpoint.bitsrun.com/v1/chat/completions \
  -H "Authorization: Bearer $BITSRUN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "qwen3:8b", "messages": [{"role": "user", "content": "Say hello in five words."}]}'
```

The same call with the official OpenAI SDKs:

```python
import os
from openai import OpenAI

client = OpenAI(
    base_url="https://01k8y4000d3m00000000000011.endpoint.bitsrun.com/v1",
    api_key=os.environ["BITSRUN_API_KEY"],
)
reply = client.chat.completions.create(
    model="qwen3:8b",
    messages=[{"role": "user", "content": "Say hello in five words."}],
)
print(reply.choices[0].message.content)
```

```javascript
import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://01k8y4000d3m00000000000011.endpoint.bitsrun.com/v1",
  apiKey: process.env.BITSRUN_API_KEY,
});
const reply = await client.chat.completions.create({
  model: "qwen3:8b",
  messages: [{ role: "user", content: "Say hello in five words." }],
});
console.log(reply.choices[0].message.content);
```

## When the endpoint is asleep

An endpoint sleeps when nobody uses it, and the first request wakes it. That start takes a few seconds on a warm GPU and a few minutes when a new GPU starts. You are never billed for it. How your request behaves while it waits:

- **Every request** stays open and waits for the model, up to 8 minutes, then answers normally. Streaming requests get keep-alive comments while they wait; other requests get spaces before the JSON, which JSON parsers skip.
- **After 8 minutes**, or if the model fails to start, the answer has status `200` and an error body (`model_starting` or `model_unavailable`). Send the request again.
- **Header `X-BitsRun-Wait: 0`:** a request that finds the model asleep gets `503` with the code `model_starting` and a `Retry-After: 30` header after about 45 seconds instead.

Read [Cold starts](https://bitsrun.com/docs/get-started/cold-starts/) for timings and how to avoid them.

## Errors

Every error has the same shape: a stable `code` your code can check, a friendly `message`, and a `requestId` to send to support.

```json
{
  "error": {
    "code": "payment_required",
    "message": "Your credit balance has run out. Add credit in the dashboard to continue.",
    "requestId": "01k9a2b3c4d5e6f7g8h9j0k1m2"
  }
}
```

The full list, with what each one means and how to fix it, is on [Error codes](https://bitsrun.com/docs/troubleshooting/errors/).

## Pages in this section

- [Chat and completions](https://bitsrun.com/docs/api/chat/): messages, streaming, thinking, LangChain and Ollama clients
- [Embeddings](https://bitsrun.com/docs/api/embeddings/): vectors for search and RAG
- [Tool calling](https://bitsrun.com/docs/api/tools/): let the model call your functions
- [API keys](https://bitsrun.com/docs/api/api-keys/): create, limit and revoke keys
- [Limits](https://bitsrun.com/docs/api/limits/): requests at once, request fields and time limits