Create Report

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

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

POST

api

reports

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

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

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

string

required

The report’s name, up to 200 characters.

string

What the report is for.

string

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

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.

object[]

Up to 20 columns to create with the report.

Show properties

string

required

The column header, for example Governing law.

string

required

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

string

default:"text"

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

string[]

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

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

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

Preview

Agents, playbooks and blueprints

Sessions

Playbook authoring

Drafts

Files

Document actions

Operations

Research

Reports

Reviews

Organisation

Sharing

Usage and value

Repositories and search

Authentication

Headers

Body parameters

Response

Errors

​Authentication

​Headers

​Body parameters

​Response

​Errors

Authentication

Headers

Body parameters

Response

Errors