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

# Writers

> List and retrieve writers (songwriters, composers) for a project.

## List Writers

Returns a paginated list of root writers for a project. Writers represent songwriters and composers extracted from contract documents.

### Request

```
GET /v1/writers
```

### Query Parameters

| Parameter       | Type    | Required | Default | Description                                                  |
| --------------- | ------- | -------- | ------- | ------------------------------------------------------------ |
| `projectId`     | UUID    | Yes      | —       | The project to list writers for                              |
| `page`          | integer | No       | `1`     | Page number (1-indexed)                                      |
| `perPage`       | integer | No       | `20`    | Items per page (1–100)                                       |
| `includeMerged` | string  | No       | `false` | Set to `true` to include merged writers for each root writer |

### Headers

| Header          | Required | Description                                                |
| --------------- | -------- | ---------------------------------------------------------- |
| `Authorization` | Yes      | `Bearer <token>` — must be scoped to the requested project |

### Response

```json theme={null}
{
  "data": [
    {
      "id": "writer-1",
      "name": "Max Martin",
      "project_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "merged": [
        { "id": "writer-2", "name": "Martin Sandberg" }
      ]
    }
  ]
}
```

<Note>
  The `merged` array only appears when `includeMerged=true`.
</Note>

### Errors

| Status | Description                                     |
| ------ | ----------------------------------------------- |
| `400`  | Missing `projectId` or invalid query parameters |
| `403`  | Token is not scoped to the requested project    |

### Example

```bash theme={null}
curl "https://api.royaltyport.com/v1/writers?projectId=a1b2c3d4-...&page=1&perPage=50" \
  -H "Authorization: Bearer rp_your_token_here"
```

***

## Get Writer

Returns a single writer by ID.

### Request

```
GET /v1/writers/{writer_id}
```

### Path Parameters

| Parameter   | Type   | Required | Description   |
| ----------- | ------ | -------- | ------------- |
| `writer_id` | string | Yes      | The writer ID |

### Query Parameters

| Parameter       | Type   | Required | Default | Description                             |
| --------------- | ------ | -------- | ------- | --------------------------------------- |
| `projectId`     | UUID   | Yes      | —       | The project the writer belongs to       |
| `includeMerged` | string | No       | `false` | Set to `true` to include merged writers |

### Headers

| Header          | Required | Description                                                |
| --------------- | -------- | ---------------------------------------------------------- |
| `Authorization` | Yes      | `Bearer <token>` — must be scoped to the requested project |

### Response

```json theme={null}
{
  "data": {
    "id": "writer-1",
    "name": "Max Martin",
    "project_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "merged": [
      { "id": "writer-2", "name": "Martin Sandberg" }
    ]
  }
}
```

### Errors

| Status | Description                                  |
| ------ | -------------------------------------------- |
| `400`  | Missing `projectId`                          |
| `403`  | Token is not scoped to the requested project |
| `404`  | Writer not found                             |

### Example

```bash theme={null}
curl "https://api.royaltyport.com/v1/writers/writer-1?projectId=a1b2c3d4-..." \
  -H "Authorization: Bearer rp_your_token_here"
```