> ## 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.

# Mappings

> Route an incoming model name to a target model

A mapping points an incoming model name at a target model, so callers can use a stable name
while you change what runs behind it. Mappings belong to a workspace, so pass `workspace_id`
on reads and writes. Reads need `mapping:read` and writes need `mapping:write`.

## List mappings

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

<RequestExample>
  ```bash cURL theme={null}
  curl 'https://platform.nemu.cc/api/v1/mappings?workspace_id=ws_1' \
    -H 'Authorization: Bearer <access_token>'
  ```

  ```ts SDK theme={null}
  const mappings = await workspace.mappings.list();
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "data": [
      {
        "id": "map_1",
        "workspace_id": "ws_1",
        "source_name": "gpt-4",
        "target_model": "primary/gpt-oss-120b",
        "priority": 1,
        "enabled": true,
        "is_pattern": false,
        "created_at": "2026-01-04T10:22:00.000Z",
        "updated_at": "2026-01-04T10:22:00.000Z"
      }
    ]
  }
  ```
</ResponseExample>

## Get a mapping

```
GET /api/v1/mappings/{id}?workspace_id=ws_1
```

## Create a mapping

```
POST /api/v1/mappings
```

<ParamField body="workspace_id" type="string" required>
  The workspace the mapping belongs to.
</ParamField>

<ParamField body="source_name" type="string" required>
  The incoming name callers send.
</ParamField>

<ParamField body="target_model" type="string" required>
  The gateway name to route to.
</ParamField>

<ParamField body="priority" type="integer">
  The order in which mappings are matched. Lower runs first.
</ParamField>

<ParamField body="enabled" type="boolean">
  Whether the mapping is active.
</ParamField>

<ParamField body="is_pattern" type="boolean">
  Treat `source_name` as a pattern rather than an exact match.
</ParamField>

<RequestExample>
  ```ts SDK theme={null}
  const mapping = await workspace.mappings.create({
    source_name: "gpt-4",
    target_model: "primary/gpt-oss-120b",
  });
  ```
</RequestExample>

## Update a mapping

```
PATCH /api/v1/mappings/{id}
```

Accepts any create field. Send `workspace_id` in the body.

## Delete a mapping

```
DELETE /api/v1/mappings/{id}
```