> ## 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.

# Add Columns

> Add up to 20 extraction columns to a report.

> [!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).

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](/api-reference/reports/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`.

**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](/proposed/objects#report), in the order you sent them.

```bash cURL theme={null}
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"]
      }
    ]
  }'
```

```json Response theme={null}
{
  "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. |


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