> ## Documentation Index
> Fetch the complete documentation index at: https://docs.beta.b3os.org/llms.txt
> Use this file to discover all available pages before exploring further.

# List models

The OpenAI model list for the models this node serves, each with a `b3os` object: context length, quantization, whether it supports tools, JSON Schema output and image input, the largest accepted request, and your per-model token and request limits. Chat models are listed while the node's model runtime is configured (one that is restarting is still listed; requests get `503` with `Retry-After`); speech models while the voice service answers. 

` GET /v1/infer/models `

List models

The OpenAI model list for the models this node serves, each with a `b3os` object: context length,
quantization, whether it supports tools, JSON Schema output and image input, the largest accepted request,
and your per-model token and request limits. Chat models are listed while the node's model runtime is
configured (one that is restarting is still listed; requests get `503` with `Retry-After`); speech models
while the voice service answers.


## Servers

- ` https://beta-api.b3os.org ` — API (API keys and CLI tokens)

- ` https://beta.b3os.org ` — Dashboard (session cookie and CSRF header; same paths)

## Authentication

The operation accepts these alternatives. Schemes within one alternative are required together.

### Alternative 1

- ` apiKey `: ` http `

  - HTTP scheme: ` bearer ` (b3os_sk_ API key or b3os_pat_ token)

  - `Authorization: Bearer <credential>`. Two credential kinds are accepted:

- **API keys** `b3os_sk_<32 base32>_<crc32>`, created in the dashboard or with `POST /v1/keys`. A key belongs to
  one project, has scopes, an optional spend cap and expiry, and is shown only once.
- **CLI tokens** `b3os_pat_<32 base32>_<crc32>`, issued by the device login (`b3os login`). They act for one
  user in the organization and project chosen at approval.

Keys are stored as SHA-256 hashes. The edge exchanges them for a 60-second node token before forwarding
a request to a node, so nodes never see your key.


### Alternative 2

- ` session `: ` apiKey `

  - Credential: ` __Host-b3os_session ` in ` cookie `

  - The dashboard session cookie on `beta.b3os.org` (host-only, `Secure`, `HttpOnly`). Requests other than
`GET`/`HEAD` must also send `x-b3os-csrf: <csrf_token>` from `GET /v1/auth/session`; SameSite is not relied
on. The cookie is never sent to `beta-api.b3os.org` or `usercontent.b3os.org`.


## Responses

### ` 200 ` — The models.

Content type: ` application/json `

- ` value `: type ` object ` — The OpenAI list shape (no cursor).

  - Required fields: ` object `, ` data `

  - ` object `: type ` string `

    - enum: ` ["list"] `

  - ` data `: type ` array `

    - ` array item `: type ` object `

      - Required fields: ` id `, ` object `, ` created `, ` owned_by `, ` b3os `

      - ` id `: type ` string `

      - ` object `: type ` string `

        - enum: ` ["model"] `

      - ` created `: type ` integer `

      - ` owned_by `: type ` string `

      - ` b3os `: type ` object ` — B3OS extension with what the model supports and your limits on it.

        - Required fields: ` kind `, ` context_length `, ` quantization `, ` tools `, ` json_schema `, ` image_input `, ` max_request_bytes `, ` limits `

        - ` kind `: type ` string `

          - enum: ` ["chat","embedding","speech"] `

        - ` context_length `: type ` integer `; nullable

        - ` quantization `: type ` string `; nullable

        - ` tools `: type ` boolean `

        - ` json_schema `: type ` boolean `

        - ` image_input `: type ` boolean `

        - ` max_request_bytes `: type ` integer `

        - ` limits `: type ` object `

          - Required fields: ` tpm `, ` rpm `

          - ` tpm `: type ` integer `; nullable — Tokens per minute for your organization.

          - ` rpm `: type ` integer `; nullable

Response header ` x-request-id ` — The request ID (`req_…`). It is the `instance` of any problem and the key for `GET /v1/requests/{request_id}`.

- ` value `: type ` string `

  - pattern: ` "^req_[0-9a-hjkmnp-tv-z]{26}$" `

Response header ` Server-Timing ` — Phase durations in milliseconds (W3C Server Timing); the handler's phases break the request down. For a
response whose body size is known, `total` runs from reading the request head to writing the response head.
Streaming responses (event streams, WebSockets, chunked bodies) carry no `total` here: they report their
final phases in the terminal event (`job.succeeded`, `job.failed`, `job.canceled`) or the final job. The
time from the first request byte to the last response byte is recorded in the node's metrics and request
log (`GET /v1/requests/{request_id}`). The edge prepends `edge_auth` and `edge_upstream`.


- ` value `: type ` string `

Example:

```json
{
  "object": "list",
  "data": [
    {
      "id": "b3os/qwen3.5-9b",
      "object": "model",
      "created": 1772197106,
      "owned_by": "b3os",
      "b3os": {
        "kind": "chat",
        "context_length": 32768,
        "quantization": "fp8",
        "tools": true,
        "json_schema": true,
        "image_input": true,
        "max_request_bytes": 10485760,
        "limits": {
          "tpm": 200000,
          "rpm": 600
        }
      }
    },
    {
      "id": "kokoro-82m",
      "object": "model",
      "created": 0,
      "owned_by": "b3os",
      "b3os": {
        "kind": "speech",
        "context_length": null,
        "quantization": null,
        "tools": false,
        "json_schema": false,
        "image_input": false,
        "max_request_bytes": 65536,
        "limits": {
          "tpm": null,
          "rpm": 300
        }
      }
    }
  ]
}
```

### ` 401 ` — Missing or invalid credentials (`unauthorized`).

Content type: ` application/json `

- ` value `: type ` object ` — The OpenAI error body. `code` is the B3OS error code; `x-request-id` carries the request ID.

  - Required fields: ` error `

  - ` error `: type ` object `

    - Required fields: ` message `, ` type `, ` param `, ` code `

    - ` message `: type ` string `

    - ` type `: type ` string ` — `invalid_request_error`, `authentication_error`, `permission_error`, `rate_limit_error` or `server_error`.

    - ` param `: type ` string `; nullable

    - ` code `: type ` string `; nullable

Response header ` x-request-id ` — The request ID (`req_…`). It is the `instance` of any problem and the key for `GET /v1/requests/{request_id}`.

- ` value `: type ` string `

  - pattern: ` "^req_[0-9a-hjkmnp-tv-z]{26}$" `

Response header ` Server-Timing ` — Phase durations in milliseconds (W3C Server Timing); the handler's phases break the request down. For a
response whose body size is known, `total` runs from reading the request head to writing the response head.
Streaming responses (event streams, WebSockets, chunked bodies) carry no `total` here: they report their
final phases in the terminal event (`job.succeeded`, `job.failed`, `job.canceled`) or the final job. The
time from the first request byte to the last response byte is recorded in the node's metrics and request
log (`GET /v1/requests/{request_id}`). The edge prepends `edge_auth` and `edge_upstream`.


- ` value `: type ` string `

Example:

```json
{
  "error": {
    "message": "API key checksum does not match; check that the whole key was copied",
    "type": "authentication_error",
    "param": null,
    "code": "unauthorized"
  }
}
```

### ` 403 ` — The key lacks `infer:run` or `infer:read` (`forbidden`), or the egress guard refused an image URL (`egress_denied`).

Content type: ` application/json `

- ` value `: type ` object ` — The OpenAI error body. `code` is the B3OS error code; `x-request-id` carries the request ID.

  - Required fields: ` error `

  - ` error `: type ` object `

    - Required fields: ` message `, ` type `, ` param `, ` code `

    - ` message `: type ` string `

    - ` type `: type ` string ` — `invalid_request_error`, `authentication_error`, `permission_error`, `rate_limit_error` or `server_error`.

    - ` param `: type ` string `; nullable

    - ` code `: type ` string `; nullable

Response header ` x-request-id ` — The request ID (`req_…`). It is the `instance` of any problem and the key for `GET /v1/requests/{request_id}`.

- ` value `: type ` string `

  - pattern: ` "^req_[0-9a-hjkmnp-tv-z]{26}$" `

Response header ` Server-Timing ` — Phase durations in milliseconds (W3C Server Timing); the handler's phases break the request down. For a
response whose body size is known, `total` runs from reading the request head to writing the response head.
Streaming responses (event streams, WebSockets, chunked bodies) carry no `total` here: they report their
final phases in the terminal event (`job.succeeded`, `job.failed`, `job.canceled`) or the final job. The
time from the first request byte to the last response byte is recorded in the node's metrics and request
log (`GET /v1/requests/{request_id}`). The edge prepends `edge_auth` and `edge_upstream`.


- ` value `: type ` string `

### ` 429 ` — A limit applies (`rate_limited` for requests, tokens or remote image bytes per minute, `concurrency_limited` for requests in flight for the organization, `quota_exceeded`; `credits_exhausted` arrives as 402).

Content type: ` application/json `

- ` value `: type ` object ` — The OpenAI error body. `code` is the B3OS error code; `x-request-id` carries the request ID.

  - Required fields: ` error `

  - ` error `: type ` object `

    - Required fields: ` message `, ` type `, ` param `, ` code `

    - ` message `: type ` string `

    - ` type `: type ` string ` — `invalid_request_error`, `authentication_error`, `permission_error`, `rate_limit_error` or `server_error`.

    - ` param `: type ` string `; nullable

    - ` code `: type ` string `; nullable

Response header ` x-request-id ` — The request ID (`req_…`). It is the `instance` of any problem and the key for `GET /v1/requests/{request_id}`.

- ` value `: type ` string `

  - pattern: ` "^req_[0-9a-hjkmnp-tv-z]{26}$" `

Response header ` Server-Timing ` — Phase durations in milliseconds (W3C Server Timing); the handler's phases break the request down. For a
response whose body size is known, `total` runs from reading the request head to writing the response head.
Streaming responses (event streams, WebSockets, chunked bodies) carry no `total` here: they report their
final phases in the terminal event (`job.succeeded`, `job.failed`, `job.canceled`) or the final job. The
time from the first request byte to the last response byte is recorded in the node's metrics and request
log (`GET /v1/requests/{request_id}`). The edge prepends `edge_auth` and `edge_upstream`.


- ` value `: type ` string `

Response header ` Retry-After ` — Seconds to wait before retrying or polling again.

- ` value `: type ` integer `

  - minimum: ` 0 `

Response header ` RateLimit-Limit ` — Requests allowed in the current window for the limit that applies to this operation.

- ` value `: type ` integer `

Response header ` RateLimit-Remaining ` — Requests left in the current window.

- ` value `: type ` integer `

Response header ` RateLimit-Reset ` — Seconds until the current window resets.

- ` value `: type ` integer `

Example:

```json
{
  "error": {
    "message": "200000 tokens per minute allowed on b3os/qwen3.5-9b; retry in 9 seconds",
    "type": "rate_limit_error",
    "param": null,
    "code": "rate_limited"
  }
}
```

### ` 500 ` — Something failed inside B3OS (`internal`).

Content type: ` application/json `

- ` value `: type ` object ` — The OpenAI error body. `code` is the B3OS error code; `x-request-id` carries the request ID.

  - Required fields: ` error `

  - ` error `: type ` object `

    - Required fields: ` message `, ` type `, ` param `, ` code `

    - ` message `: type ` string `

    - ` type `: type ` string ` — `invalid_request_error`, `authentication_error`, `permission_error`, `rate_limit_error` or `server_error`.

    - ` param `: type ` string `; nullable

    - ` code `: type ` string `; nullable

Response header ` x-request-id ` — The request ID (`req_…`). It is the `instance` of any problem and the key for `GET /v1/requests/{request_id}`.

- ` value `: type ` string `

  - pattern: ` "^req_[0-9a-hjkmnp-tv-z]{26}$" `

Response header ` Server-Timing ` — Phase durations in milliseconds (W3C Server Timing); the handler's phases break the request down. For a
response whose body size is known, `total` runs from reading the request head to writing the response head.
Streaming responses (event streams, WebSockets, chunked bodies) carry no `total` here: they report their
final phases in the terminal event (`job.succeeded`, `job.failed`, `job.canceled`) or the final job. The
time from the first request byte to the last response byte is recorded in the node's metrics and request
log (`GET /v1/requests/{request_id}`). The edge prepends `edge_auth` and `edge_upstream`.


- ` value `: type ` string `

Example:

```json
{
  "error": {
    "message": "internal error (request req_01m5t4yg394wegr3j4y01qb363)",
    "type": "server_error",
    "param": null,
    "code": "internal"
  }
}
```

### ` 503 ` — The model runtime, the voice service or the B3IQ gateway route is restarting, overloaded or not set up on
this node (`infer_backend_unavailable`, `capacity_unavailable`), or the node is unavailable
(`node_unavailable`).


Content type: ` application/json `

- ` value `: type ` object ` — The OpenAI error body. `code` is the B3OS error code; `x-request-id` carries the request ID.

  - Required fields: ` error `

  - ` error `: type ` object `

    - Required fields: ` message `, ` type `, ` param `, ` code `

    - ` message `: type ` string `

    - ` type `: type ` string ` — `invalid_request_error`, `authentication_error`, `permission_error`, `rate_limit_error` or `server_error`.

    - ` param `: type ` string `; nullable

    - ` code `: type ` string `; nullable

Response header ` x-request-id ` — The request ID (`req_…`). It is the `instance` of any problem and the key for `GET /v1/requests/{request_id}`.

- ` value `: type ` string `

  - pattern: ` "^req_[0-9a-hjkmnp-tv-z]{26}$" `

Response header ` Server-Timing ` — Phase durations in milliseconds (W3C Server Timing); the handler's phases break the request down. For a
response whose body size is known, `total` runs from reading the request head to writing the response head.
Streaming responses (event streams, WebSockets, chunked bodies) carry no `total` here: they report their
final phases in the terminal event (`job.succeeded`, `job.failed`, `job.canceled`) or the final job. The
time from the first request byte to the last response byte is recorded in the node's metrics and request
log (`GET /v1/requests/{request_id}`). The edge prepends `edge_auth` and `edge_upstream`.


- ` value `: type ` string `

Response header ` Retry-After ` — Seconds to wait before retrying or polling again.

- ` value `: type ` integer `

  - minimum: ` 0 `

Example:

```json
{
  "error": {
    "message": "The model runtime on n1 is restarting; retry in 5 seconds",
    "type": "server_error",
    "param": null,
    "code": "infer_backend_unavailable"
  }
}
```

## Request examples

### cURL

```curl
curl -X GET 'https://beta-api.b3os.org/v1/infer/models' \
  -H 'Authorization: Bearer YOUR_API_TOKEN'
```

### JavaScript

```javascript
const response = await fetch('https://beta-api.b3os.org/v1/infer/models', {
  method: 'GET',
  headers: {
      "Authorization": "Bearer YOUR_API_TOKEN"
  }
});

const data = await response.json();
console.log(data);
```

### Python

```python
import requests

headers = {
    'Authorization': 'Bearer YOUR_API_TOKEN'
}

response = requests.get('https://beta-api.b3os.org/v1/infer/models', headers=headers)
print(response.json())
```