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

# Create Report

> Create a report over a repository or a set of files, optionally with columns, and optionally start it.

> [!NOTE]
>
> **Preview.** This endpoint is available to organisations in the Wordsmith MCP pilot. Other organisations receive `403 mcp_not_enabled`. See the [preview overview](/preview).

Creates a [report](/proposed/objects#report): a grid with one row per document and one column per question. Each cell holds the AI's answer to that column's question for that row's document.

Choose where the rows come from:

* **`repository_id`**: the rows follow the repository. A document added to it gets a row, and a document removed from it loses its row. The rows fill in the background, and their cells compute as they arrive, as in the app. Your organisation needs reports that follow a repository enabled.
* **`file_ids`**: one row per file. Each file is copied into the report. Add more later with [Add Rows](/api-reference/reports/add-rows).
* **Neither**: the report starts with no rows. Add them with [Add Rows](/api-reference/reports/add-rows).

You can pass the columns now, or add them later with [Add Columns](/api-reference/reports/add-columns). On a report of files, cells stay `empty` until a run computes them. Set `run: true` to start the first run straight away, or call [Run Report](/api-reference/reports/run-report) when you are ready.

## Authentication

Requires an API key, or an OAuth token with `reports:write`. Passing `repository_id` also needs `repositories:read`, and passing `file_ids` also needs `files:read`. The caller's role must allow creating reports.

## Headers

**Idempotency-Key** `string`

A unique string for this request, such as a UUID. Honoured with `run: true`: a repeat with the same key within 30 days returns the same report with `200`, so a retry never creates a second report or starts a second run. Without `run` the key is ignored: after a timeout, [list your reports](/api-reference/reports/list-reports) before you retry.

## Body parameters

**name** `string` *required*

The report's name, up to 200 characters.

**description** `string`

What the report is for.

**repository\_id** `string`

A repository whose documents become the rows, and stay the rows as it changes. Cannot be combined with `file_ids` or `run`.

**file\_ids** `string[]`

Files that become the rows, from `1` to `10` ids. Each must be a `.pdf`, `.docx`, `.doc`, `.pptx` or `.png` file. Cannot be combined with `repository_id`.

**columns** `object[]`

Up to 20 columns to create with the report.

**properties**

**name** `string` *required*

The column header, for example `Governing law`.

**prompt** `string` *required*

The question the AI answers for each document, for example `Which law governs this lease?`.

**type** `string` (default: text)

The answer type: `text`, `number`, `date`, `boolean`, `single_select` or `multi_select`.

**options** `string[]`

The allowed answers. Required for `single_select` and `multi_select`, and not allowed for other types.

**run** `boolean` (default: false)

Start computing every cell as soon as the report is created. Needs `file_ids` and at least one column. The cells' credit cost is checked against your organisation's per-operation limit before anything is created.

## Response

Returns `201` with the new [report](/proposed/objects#report) and its `columns`. The response also carries `operation_id`:

* With `run: true`, `operation_id` is the `report_run` [operation](/proposed/objects#operation). Wait for it with [Get Operation](/api-reference/operations/get-operation), as described in [Long-running operations](/proposed/long-running-operations).
* With `run: false`, `operation_id` is `null`.

With `repository_id`, `row_count` starts at `0` and grows as the repository's documents are added in the background.

```bash cURL theme={null}
curl -X POST "https://api.wordsmith.ai/api/v1/reports" \
  -H "Authorization: Bearer sk-ws-api1-your_api_key_here" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 9c2e4f61-7a3b-4d08-b5e1-6f0a2c8d4b37" \
  -d '{
    "name": "Lease abstract: retail estate",
    "description": "Key terms for every signed retail lease.",
    "file_ids": [
      "d3c3a00e-4c00-4bfe-97af-374bb41ca6db",
      "a400ba8b-98b1-49aa-b7fa-e42607a2892a"
    ],
    "columns": [
      {
        "name": "Governing law",
        "prompt": "Which law governs this lease?",
        "type": "single_select",
        "options": ["England and Wales", "Scotland", "Northern Ireland"]
      },
      {
        "name": "Term end date",
        "prompt": "On what date does the contractual term end?",
        "type": "date"
      }
    ],
    "run": true
  }'
```

```json Response theme={null}
{
  "id": "f544ddfc-24d5-4947-939c-ba2d1bcba35b",
  "name": "Lease abstract: retail estate",
  "description": "Key terms for every signed retail lease.",
  "repository_id": null,
  "row_count": 2,
  "column_count": 2,
  "status": "running",
  "columns": [
    {
      "id": "6294d0a0-e64f-41ba-96c5-47eb505e7ab0",
      "name": "Governing law",
      "prompt": "Which law governs this lease?",
      "type": "single_select",
      "options": ["England and Wales", "Scotland", "Northern Ireland"]
    },
    {
      "id": "a7335c50-fd65-45ec-90d7-b0b0341eb148",
      "name": "Term end date",
      "prompt": "On what date does the contractual term end?",
      "type": "date",
      "options": []
    }
  ],
  "operation_id": "25113fa2-7671-4474-b7c6-96794d213c6d",
  "url": "https://app.wordsmith.ai/reports/f544ddfc-24d5-4947-939c-ba2d1bcba35b",
  "created_at": "2026-10-13T09:20:00Z",
  "updated_at": "2026-10-13T09:20:00Z"
}
```

## Errors

| Status | `error_code` | When |
| - | - | - |
| 400 | `invalid_request_body` | `name` is missing, both `repository_id` and `file_ids` are set, `run` is set with `repository_id`, a column is invalid, or there are more than 20 columns or 10 files. |
| 400 | `nothing_to_run` | `run` is `true` but there are no `file_ids` or no columns. |
| 400 | `unsupported_file_type` | A file is not a `.pdf`, `.docx`, `.doc`, `.pptx` or `.png` file. Nothing is created. |
| 400 | `process_limit_exceeded` | `run` is `true` and the cells would cost more credits than one operation may use. Nothing is created. |
| 400 | `native_report_column_limit_exceeded` | The columns pass the most a report can have. |
| 400 | `bad_request` | `repository_id` is set, but reports that follow a repository are not enabled for your organisation. |
| 403 | `forbidden` | The caller's role does not allow creating reports. |
| 404 | `resource_not_found` | The repository or a file does not exist, or the caller cannot read it. |
| 409 | `idempotency_key_reused` | The `Idempotency-Key` was used within 30 days with a different body. |
| 409 | `resource_conflict` | A request with the same `Idempotency-Key` is still creating the report (retry in a few seconds), or failed and created nothing because its input was refused (use a new key). When the first request failed for another reason before its run started, the repeat creates the report instead; once the run had started, the repeat returns that report. |
| 502 | `external_dependency_failed` | A file could not be copied into the report. Nothing is created. |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.