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

# API Reference

> All nine endpoints an Admin Key can call, with parameters, responses and examples.

The base URL is `https://api.ephone.ai` and every request carries `Authorization: Bearer sk-admin-...`.

Apart from the two export endpoints, responses use the `{"success": bool, "message": string, "data": ...}` envelope.

## Account

### Get account profile

`GET /api/user/self` · scope `account:read`

Returns the account profile. `balance` is the current balance.

```bash theme={null}
curl https://api.ephone.ai/api/user/self \
  -H "Authorization: Bearer $ADMIN_KEY"
```

```json theme={null}
{
  "success": true,
  "data": {
    "username": "alice",
    "display_name": "Alice",
    "balance": "128.5000",
    "used_quota": "71.5000",
    "request_count": 1024,
    "group": "default",
    "level": 2
  }
}
```

Passwords, session credentials and identity documents never appear in the response.

## Call logs

### Call statistics

`GET /api/log/self/stat` · scope `logs:read`

Returns spend and throughput statistics for a time range.

| Parameter         | Type   | Description                  |
| ----------------- | ------ | ---------------------------- |
| `start_timestamp` | int    | Start time, Unix seconds     |
| `end_timestamp`   | int    | End time, Unix seconds       |
| `model_name`      | string | Filter by model, optional    |
| `token_name`      | string | Filter by key name, optional |
| `vendor_id`       | int    | Filter by provider, optional |

```bash theme={null}
curl -G https://api.ephone.ai/api/log/self/stat \
  -H "Authorization: Bearer $ADMIN_KEY" \
  -d start_timestamp=1767225600 \
  -d end_timestamp=1769904000 \
  -d model_name=gpt-4o
```

```json theme={null}
{
  "success": true,
  "data": { "quota": 12.3456, "rpm": 8, "tpm": 15420, "mpm": 0.42 }
}
```

`quota` is the amount spent over the range.

### Export log details

`GET /api/log/self/stream-export` · scope `logs:read`

Streams log details.

<Warning>
  **This endpoint returns the CSV body directly; it does not return a download link.** The response is `Content-Type: text/csv; charset=utf-8`, written row by row as a stream, with a UTF-8 BOM at the start so Excel reads it correctly. Redirect the response body to a file — no second request is needed.
</Warning>

| Parameter         | Type   | Description                                |
| ----------------- | ------ | ------------------------------------------ |
| `start_timestamp` | int    | Start time, Unix seconds                   |
| `end_timestamp`   | int    | End time, Unix seconds                     |
| `model_name`      | string | Filter by model, optional                  |
| `vendor_id`       | int    | Filter by provider, optional               |
| `status`          | string | Filter by status, optional                 |
| `columns`         | string | Comma-separated columns; empty exports all |
| `currency`        | string | `CNY` or `USD`, affects amount columns     |

<CodeGroup>
  ```bash cURL theme={null}
  curl -G https://api.ephone.ai/api/log/self/stream-export \
    -H "Authorization: Bearer $ADMIN_KEY" \
    -d start_timestamp=1767225600 \
    -d end_timestamp=1769904000 \
    -d currency=USD \
    -o logs.csv
  ```

  ```python Python theme={null}
  import requests

  r = requests.get(
      "https://api.ephone.ai/api/log/self/stream-export",
      headers={"Authorization": f"Bearer {ADMIN_KEY}"},
      params={"start_timestamp": 1767225600, "end_timestamp": 1769904000},
      stream=True,
  )
  r.raise_for_status()
  with open("logs.csv", "wb") as f:
      for chunk in r.iter_content(chunk_size=8192):
          f.write(chunk)
  ```
</CodeGroup>

Available columns include `created_at`, `model_name`, `token_name`, `prompt_tokens`, `completion_tokens`, `cached_tokens`, `reasoning_tokens` and `quota`. If you use caching, reasoning or multimodal models, export the detailed columns explicitly — the aggregate counts alone will not reconcile against what you were charged.

## Usage analytics

### Export usage analytics

`GET /api/data/self/pivot/stream-export` · scope `usage:read`

Aggregates usage by dimension and streams it as CSV, same as above.

| Parameter         | Type   | Description                            |
| ----------------- | ------ | -------------------------------------- |
| `start_timestamp` | int    | Start time, **milliseconds**           |
| `end_timestamp`   | int    | End time, **milliseconds**             |
| `group_by`        | string | Dimension, e.g. `model`, `token`       |
| `metric`          | string | Metric; `spend` is the amount          |
| `granularity`     | string | `hour`, `day` or `week`, default `day` |
| `top_n`           | int    | Keep the top N entries, default 20     |
| `model_name`      | string | Filter by model, optional              |

<Note>
  Timestamps here are in **milliseconds**, unlike the log endpoints which use seconds. A single query spans at most about six months.
</Note>

```bash theme={null}
curl -G https://api.ephone.ai/api/data/self/pivot/stream-export \
  -H "Authorization: Bearer $ADMIN_KEY" \
  -d start_timestamp=1767225600000 \
  -d end_timestamp=1769904000000 \
  -d group_by=model \
  -d metric=spend \
  -d granularity=day \
  -o usage.csv
```

## API key management

<Warning>
  These endpoints manage **API keys used to call models**, not Admin Keys. An Admin Key can never create, edit or revoke any Admin Key, including itself.
</Warning>

### List keys

`GET /api/token/` · scope `keys:read`

Returns a page of API keys. Key values are masked; plaintext is not retrievable through any endpoint.

| Parameter   | Type | Description                |
| ----------- | ---- | -------------------------- |
| `p`         | int  | Page number, starting at 1 |
| `page_size` | int  | Items per page             |

```bash theme={null}
curl -G https://api.ephone.ai/api/token/ \
  -H "Authorization: Bearer $ADMIN_KEY" \
  -d p=1 -d page_size=20
```

```json theme={null}
{
  "success": true,
  "data": {
    "items": [
      {
        "id": 42,
        "name": "production",
        "key_mask": "sk-e****9f2c",
        "status": 1,
        "remain_quota": "50.0000",
        "unlimited_quota": false,
        "expired_time": -1,
        "group": "default",
        "created_time": 1767225600
      }
    ],
    "page": 1,
    "page_size": 20,
    "total": 1
  }
}
```

An `expired_time` of `-1` means the key never expires.

### Get one key

`GET /api/token/{id}` · scope `keys:read`

Returns the full configuration of one key, with the value masked.

```bash theme={null}
curl https://api.ephone.ai/api/token/42 \
  -H "Authorization: Bearer $ADMIN_KEY"
```

### Create a key

`POST /api/token/` · scope `keys:write`

Creates a new API key. **The plaintext appears only in this response.**

| Field             | Type   | Description                                     |
| ----------------- | ------ | ----------------------------------------------- |
| `name`            | string | Name, up to 50 characters                       |
| `remain_quota`    | number | Quota; ignored when `unlimited_quota` is `true` |
| `unlimited_quota` | bool   | Whether the key has unlimited quota             |
| `expired_time`    | int    | Expiry as Unix seconds, `-1` for never          |
| `group`           | string | Group; empty uses the default                   |

```bash theme={null}
curl -X POST https://api.ephone.ai/api/token/ \
  -H "Authorization: Bearer $ADMIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"batch","remain_quota":10,"expired_time":-1,"group":"default"}'
```

```json theme={null}
{
  "success": true,
  "data": { "id": 43, "key": "sk-ep-the-new-key-plaintext" }
}
```

<Warning>
  Save `key` right away. Only its hash is stored, so no endpoint can return the plaintext afterwards — that applies to Admin Keys and signed-in users alike.
</Warning>

### Update a key

`PUT /api/token/` · scope `keys:write`

Updates an existing key. The body must include `id`.

```bash theme={null}
curl -X PUT https://api.ephone.ai/api/token/ \
  -H "Authorization: Bearer $ADMIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{"id":43,"name":"batch-adjusted","remain_quota":20}'
```

### Delete a key

`DELETE /api/token/{id}` · scope `keys:write`

Deletes the key immediately.

```bash theme={null}
curl -X DELETE https://api.ephone.ai/api/token/43 \
  -H "Authorization: Bearer $ADMIN_KEY"
```

<Note>
  Bulk deletion is not available to Admin Keys. Delete keys one at a time, or use the console.
</Note>