# Codex Status

- **Method:** `GET`
- **Path:** `/api/v1/providers/codex`
- **Operation ID:** `codex_status`
- **Tags:** providers

Your ChatGPT login's state - `none`, `pending`, `connected`, `expired` or `error` - with its plan,
when it was connected and when it expires, and the subscription's rate-limit use. Never any part of the
login itself.

## Effective servers

- `https://api.saram.sh`

  Saram

## Authentication

- **HTTPBearer**: HTTP bearer

  a Saram API key (`sk_saram_<env>_...`) or a person's AuthKit access token, as `Authorization: Bearer <credential>`. Both are told apart by shape and produce the same principal.

## Responses

### 200 Successful Response

**Content type:** `application/json`

schema: `CodexStatus`, no additional properties

`GET /api/v1/providers/codex`. Metadata about a login; never any part of one.

- **`caller` (required)**: `string`
- **`state` (required)**: `string`, possible values: `"none", "pending", "connected", "expired", "error"`
- **`account_id`**: `string | null`
- **`connected_at`**: `string | null`, format: `date-time`
- **`error`**: `string | null`

  Why the last login attempt failed, when `state` is `error` and no gateway call was involved. The OAuth
  `error_description`, which cannot carry a token.
- **`expires_at`**: `string | null`, format: `date-time`
- **`gateway`**: `object | null`, schema: `CodexGateway`, no additional properties

  What the ChatGPT gateway reports about this caller's slot: whether it can serve, and the consumer rate
  limit's state from the last `x-codex-*` headers it saw. Never a token and never a routing key.
  - **`last_error`**: `string | null`
  - **`login`**: `string | null`
  - **`primary_reset_at`**: `string | null`, format: `date-time`
  - **`primary_used_percent`**: `number | null`
- **`last_refresh`**: `string | null`, format: `date-time`
- **`pending`**: `object | null`, schema: `CodexPending`, no additional properties

  A device login in flight. The `device_auth_id` that redeems it is not here and never leaves the pod.
  - **`expires_at` (required)**: `string`, format: `date-time`
  - **`user_code` (required)**: `string`
  - **`verification_url` (required)**: `string`
- **`plan_type`**: `string | null`
- **`providers`**: `object | null`, schema: `CodexProviders`, no additional properties

  The `providers` block to paste into a run spec, secret name included, so the caller never has to type
  one. The ref is the routing key's name, never its value.
  - **`entries` (required)**: `object`

    **Additional properties:**

    schema: `CodexProvidersEntry`, no additional properties

    One `providers` entry of a run spec, routed through this caller's ChatGPT login.
    - **`base_url` (required)**: `string`
    - **`credential_ref` (required)**: `string`
    - **`model` (required)**: `string`
  - **`roles` (required)**: `object`

    **Additional properties:**

    `string`

**Example:**

```json
{
  "caller": "",
  "state": "none",
  "pending": {
    "user_code": "",
    "verification_url": "",
    "expires_at": ""
  },
  "account_id": "",
  "plan_type": "",
  "connected_at": "",
  "expires_at": "",
  "last_refresh": "",
  "error": "",
  "gateway": {
    "login": "",
    "primary_used_percent": 1,
    "primary_reset_at": "",
    "last_error": ""
  },
  "providers": {
    "entries": {
      "additionalProperty": {
        "model": "",
        "base_url": "",
        "credential_ref": ""
      }
    },
    "roles": {
      "additionalProperty": ""
    }
  }
}
```

### 403 the API key lacks the required scope

## Schemas

- `CodexGateway` — shown above.
- `CodexPending` — shown above.
- `CodexProviders` — shown above.
- `CodexProvidersEntry` — shown above.
- `CodexStatus` — shown above.