Create Report

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

POST /api/v1/reports

cURL

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
  }'

Response

{
  "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"
}

Preview. This endpoint is available to organisations in the Wordsmith MCP pilot. Other organisations receive 403 mcp_not_enabled. See the preview overview.

Creates a 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.
• Neither: the report starts with no rows. Add them with Add Rows.

You can pass the columns now, or add them later with 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 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 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.

Show 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 and its columns. The response also carries operation_id:

• With run: true, operation_id is the report_run operation. Wait for it with Get Operation, as described in 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.

cURL

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
  }'

Response

{
  "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.