Add Columns

Add up to 20 extraction columns to a report.

POST /api/v1/reports/{report_id}/columns

cURL

curl -X POST "https://api.wordsmith.ai/api/v1/reports/f544ddfc-24d5-4947-939c-ba2d1bcba35b/columns" \
  -H "Authorization: Bearer sk-ws-api1-your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "columns": [
      {
        "name": "Annual rent (GBP)",
        "prompt": "What is the initial annual rent in pounds sterling, excluding VAT?",
        "type": "number"
      },
      {
        "name": "Permitted use",
        "prompt": "Which uses does the lease permit? Pick every one that applies.",
        "type": "multi_select",
        "options": ["Retail", "Food and drink", "Office", "Storage"]
      }
    ]
  }'

Response

{
  "items": [
    {
      "id": "0b49a741-bba9-4895-91c0-a5163e60fc22",
      "name": "Annual rent (GBP)",
      "prompt": "What is the initial annual rent in pounds sterling, excluding VAT?",
      "type": "number",
      "options": []
    },
    {
      "id": "cae204f5-2bec-47c0-87dc-7399f9aeb7ec",
      "name": "Permitted use",
      "prompt": "Which uses does the lease permit? Pick every one that applies.",
      "type": "multi_select",
      "options": ["Retail", "Food and drink", "Office", "Storage"]
    }
  ]
}

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

Adds columns to a report. Each column is a question the AI answers for every row’s document. New columns go after the existing ones.

On a report created through the API over files, new columns start with every cell empty, and adding them computes nothing and uses no credits. Fill the new cells with Run Report, passing the new column ids as column_ids. The columns are added together or not at all: if one cannot be added, the ones added before it are removed, so you can retry the request.

A report whose rows follow a repository, and a report made in the app with auto-run on, compute new columns straight away, as the app does. Their credit cost is checked against your organisation’s per-operation limit first.

Authentication

Requires an API key, or an OAuth token with reports:write. The caller also needs edit access to the report.

Path parameters

report_id · string · required

The report id.

Body parameters

columns · object[] · required

The columns to add, from 1 to 20.

Show properties

name · string · required

The column header, for example Rent review frequency.

prompt · string · required

The question the AI answers for each document. Be specific: say what to extract and in what form.

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.

Response

Returns 201 with { "items": Column[] }: the new columns, in the order you sent them.

cURL

curl -X POST "https://api.wordsmith.ai/api/v1/reports/f544ddfc-24d5-4947-939c-ba2d1bcba35b/columns" \
  -H "Authorization: Bearer sk-ws-api1-your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "columns": [
      {
        "name": "Annual rent (GBP)",
        "prompt": "What is the initial annual rent in pounds sterling, excluding VAT?",
        "type": "number"
      },
      {
        "name": "Permitted use",
        "prompt": "Which uses does the lease permit? Pick every one that applies.",
        "type": "multi_select",
        "options": ["Retail", "Food and drink", "Office", "Storage"]
      }
    ]
  }'

Response

{
  "items": [
    {
      "id": "0b49a741-bba9-4895-91c0-a5163e60fc22",
      "name": "Annual rent (GBP)",
      "prompt": "What is the initial annual rent in pounds sterling, excluding VAT?",
      "type": "number",
      "options": []
    },
    {
      "id": "cae204f5-2bec-47c0-87dc-7399f9aeb7ec",
      "name": "Permitted use",
      "prompt": "Which uses does the lease permit? Pick every one that applies.",
      "type": "multi_select",
      "options": ["Retail", "Food and drink", "Office", "Storage"]
    }
  ]
}

Errors

Status	error_code	When
400	invalid_request_body	columns is empty or has more than 20 items, a column lacks name or prompt, type is not a known value, or options is missing for a select type or set for another type.
400	native_report_column_limit_exceeded	The new columns pass the most a report can have.
400	process_limit_exceeded	The report computes new columns straight away, and they would cost more credits than one operation may use. The whole batch is checked before any column is added, so nothing changes.
403	forbidden	The caller can read the report but cannot edit it.
404	resource_not_found	No report with this id, or the caller cannot read it.