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

# Overview

> Base URL, authentication, versioning, and response shape for the REST API

The REST API lets your app manage workspaces, providers, models, prompts, mappings, configs,
indexes, quotas, and metrics. It is served under one base URL.

```
https://platform.nemu.cc/api/v1
```

## Authentication

Every request carries a bearer token. Get one by running an OAuth flow, then send it in the
`Authorization` header.

<ParamField header="Authorization" type="string" required>
  `Bearer <access_token>`
</ParamField>

<Card title="How to get a token" href="/oauth/quickstart">
  Register an app and run the flow that fits your case.
</Card>

## Versioning

Pin a dated version with the `Nemu-Api-Version` header. Omit it to use the latest version.
Every response echoes the version it was served with.

<ParamField header="Nemu-Api-Version" type="string">
  A dated version such as `2026-07-14`.
</ParamField>

See [versioning](/oauth/versioning) for the full details.

## Response shape

A list endpoint wraps its rows in `data`, and often includes a `total`. A single item
endpoint wraps the item in `data`.

```json theme={null}
{
  "data": [
    { "id": "ws_1", "name": "prod" },
    { "id": "ws_2", "name": "staging" }
  ],
  "total": 2
}
```

## Workspace scoped resources

Providers, models, prompts, mappings, configs, and indexes belong to a workspace. Pass the
workspace on reads as a `workspace_id` query parameter, and on writes as a `workspace_id`
field in the body.

```
GET /api/v1/providers?workspace_id=ws_1
```

## Verbs

| Verb     | Use                                           |
| -------- | --------------------------------------------- |
| `GET`    | Read a collection or a single item            |
| `POST`   | Create an item                                |
| `PATCH`  | Update fields on an item                      |
| `PUT`    | Replace an item, accepted wherever `PATCH` is |
| `DELETE` | Remove an item                                |

## Status codes

| Code  | Meaning                                                   |
| ----- | --------------------------------------------------------- |
| `200` | Success                                                   |
| `400` | Invalid body or unsupported API version                   |
| `401` | Missing, invalid, or expired token                        |
| `403` | The token lacks the scope or the account lacks permission |
| `404` | The item was not found                                    |
| `409` | A conflict, such as a duplicate name                      |
| `429` | Rate limited, check the `Retry-After` header              |

## Rate limits

Responses include `X-RateLimit-Limit`, `X-RateLimit-Remaining`, and `X-RateLimit-Reset`.
When you exceed a limit the API returns `429` with a `Retry-After` header in seconds.

## Resources

| Resource                      | Base path     | Scope                                 |
| ----------------------------- | ------------- | ------------------------------------- |
| [User](/api/user)             | `/user`       | `profile:read`                        |
| [Workspaces](/api/workspaces) | `/workspaces` | `workspaces:read`, `workspaces:write` |
| [Providers](/api/providers)   | `/providers`  | `providers:read`, `providers:write`   |
| [Models](/api/models)         | `/models`     | `models:read`, `models:write`         |
| [Mappings](/api/mappings)     | `/mappings`   | `mapping:read`, `mapping:write`       |
| [Prompts](/api/prompts)       | `/prompts`    | `prompts:read`, `prompts:write`       |
| [Configs](/api/configs)       | `/configs`    | `models:read`, `models:write`         |
| [Indexes](/api/indexes)       | `/indexes`    | `models:read`, `models:write`         |
| [Quotas](/api/quotas)         | `/quotas`     | `quotas:read`, `quotas:write`         |
| [Metrics](/api/metrics)       | `/metrics`    | `usage:read`                          |