Export Report

curl -X POST "https://api.wordsmith.ai/api/v1/reports/f544ddfc-24d5-4947-939c-ba2d1bcba35b/exports" \
  -H "Authorization: Bearer sk-ws-api1-your_api_key_here" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: b8d05a3e-61f2-4c97-a0e4-7c3b9f1d2e68" \
  -d '{
    "format": "xlsx",
    "wait": 20
  }'

# Get File Download returns a short-lived signed URL; fetch the file from it without the API key.
url=$(curl -s "https://api.wordsmith.ai/api/v1/files/ae1b497e-7400-4654-a09d-32c24b61b418/download" \
  -H "Authorization: Bearer sk-ws-api1-your_api_key_here" | jq -r .url)
curl -L "$url" -o lease-abstract.xlsx

{
  "id": "58fdce17-f67f-49f1-9501-458067b72bce",
  "type": "report_export",
  "status": "running",
  "progress": { "stage": "export", "completed": 0, "total": 1 },
  "resource": { "type": "report", "id": "f544ddfc-24d5-4947-939c-ba2d1bcba35b" },
  "result": null,
  "error": null,
  "poll_after_seconds": 5,
  "created_at": "2026-10-13T10:20:00Z",
  "updated_at": "2026-10-13T10:20:00Z",
  "completed_at": null
}

{
  "id": "58fdce17-f67f-49f1-9501-458067b72bce",
  "type": "report_export",
  "status": "succeeded",
  "progress": { "stage": "export", "completed": 1, "total": 1 },
  "resource": { "type": "report", "id": "f544ddfc-24d5-4947-939c-ba2d1bcba35b" },
  "result": { "file_id": "ae1b497e-7400-4654-a09d-32c24b61b418" },
  "error": null,
  "poll_after_seconds": null,
  "created_at": "2026-10-13T10:20:00Z",
  "updated_at": "2026-10-13T10:20:07Z",
  "completed_at": "2026-10-13T10:20:07Z"
}

POST

api

reports

{report_id}

exports

curl -X POST "https://api.wordsmith.ai/api/v1/reports/f544ddfc-24d5-4947-939c-ba2d1bcba35b/exports" \
  -H "Authorization: Bearer sk-ws-api1-your_api_key_here" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: b8d05a3e-61f2-4c97-a0e4-7c3b9f1d2e68" \
  -d '{
    "format": "xlsx",
    "wait": 20
  }'

# Get File Download returns a short-lived signed URL; fetch the file from it without the API key.
url=$(curl -s "https://api.wordsmith.ai/api/v1/files/ae1b497e-7400-4654-a09d-32c24b61b418/download" \
  -H "Authorization: Bearer sk-ws-api1-your_api_key_here" | jq -r .url)
curl -L "$url" -o lease-abstract.xlsx

{
  "id": "58fdce17-f67f-49f1-9501-458067b72bce",
  "type": "report_export",
  "status": "running",
  "progress": { "stage": "export", "completed": 0, "total": 1 },
  "resource": { "type": "report", "id": "f544ddfc-24d5-4947-939c-ba2d1bcba35b" },
  "result": null,
  "error": null,
  "poll_after_seconds": 5,
  "created_at": "2026-10-13T10:20:00Z",
  "updated_at": "2026-10-13T10:20:00Z",
  "completed_at": null
}

{
  "id": "58fdce17-f67f-49f1-9501-458067b72bce",
  "type": "report_export",
  "status": "succeeded",
  "progress": { "stage": "export", "completed": 1, "total": 1 },
  "resource": { "type": "report", "id": "f544ddfc-24d5-4947-939c-ba2d1bcba35b" },
  "result": { "file_id": "ae1b497e-7400-4654-a09d-32c24b61b418" },
  "error": null,
  "poll_after_seconds": null,
  "created_at": "2026-10-13T10:20:00Z",
  "updated_at": "2026-10-13T10:20:07Z",
  "completed_at": "2026-10-13T10:20:07Z"
}

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

Exports a report to a new file in your private space and returns a report_export operation. The file is the one the report’s Download menu produces in the app: one row per document and one column per question. The export holds the cells as they are when it is built. To export a complete grid, wait for any run to finish first. A report with more than 250,000 cells (rows × columns) is too large to export here; download it from the app. When the operation succeeds, download the file with Get File Download. See Long-running operations for how to wait. An export cannot be cancelled.

Authentication

Requires an API key, or an OAuth token with reports:write. Downloading the file needs files:read. The caller needs read access to the report and permission to upload files.

Path parameters

string

required

The report id.

Headers

string

A unique string for this request, such as a UUID. A repeat with the same key within 30 days returns the same operation with 200 instead of starting a second export.

Body parameters

string

default:"xlsx"

The file format: xlsx, csv or json.

integer

default:"0"

Seconds to wait for the export to finish before responding, from 0 to 20. Most exports finish within this time.

string

An HTTPS URL that receives a signed POST with the operation when it reaches a terminal state. API keys only.

Response

Returns 202 with the operation. Its type is report_export and its resource is the report. When it succeeds, result holds { "file_id" }: the exported file. If the export finishes within wait, the response is still 202, and the operation is already succeeded.

curl -X POST "https://api.wordsmith.ai/api/v1/reports/f544ddfc-24d5-4947-939c-ba2d1bcba35b/exports" \
  -H "Authorization: Bearer sk-ws-api1-your_api_key_here" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: b8d05a3e-61f2-4c97-a0e4-7c3b9f1d2e68" \
  -d '{
    "format": "xlsx",
    "wait": 20
  }'

# Get File Download returns a short-lived signed URL; fetch the file from it without the API key.
url=$(curl -s "https://api.wordsmith.ai/api/v1/files/ae1b497e-7400-4654-a09d-32c24b61b418/download" \
  -H "Authorization: Bearer sk-ws-api1-your_api_key_here" | jq -r .url)
curl -L "$url" -o lease-abstract.xlsx

{
  "id": "58fdce17-f67f-49f1-9501-458067b72bce",
  "type": "report_export",
  "status": "running",
  "progress": { "stage": "export", "completed": 0, "total": 1 },
  "resource": { "type": "report", "id": "f544ddfc-24d5-4947-939c-ba2d1bcba35b" },
  "result": null,
  "error": null,
  "poll_after_seconds": 5,
  "created_at": "2026-10-13T10:20:00Z",
  "updated_at": "2026-10-13T10:20:00Z",
  "completed_at": null
}

{
  "id": "58fdce17-f67f-49f1-9501-458067b72bce",
  "type": "report_export",
  "status": "succeeded",
  "progress": { "stage": "export", "completed": 1, "total": 1 },
  "resource": { "type": "report", "id": "f544ddfc-24d5-4947-939c-ba2d1bcba35b" },
  "result": { "file_id": "ae1b497e-7400-4654-a09d-32c24b61b418" },
  "error": null,
  "poll_after_seconds": null,
  "created_at": "2026-10-13T10:20:00Z",
  "updated_at": "2026-10-13T10:20:07Z",
  "completed_at": "2026-10-13T10:20:07Z"
}

Errors

Status	`error_code`	When
400	`invalid_request_body`	`format` is not `xlsx`, `csv` or `json`, or a field has the wrong type.
400	`invalid_wait`	`wait` is outside `0`–`20`.
400	`invalid_callback_url`	`callback_url` is not a public https URL.
400	`callback_signing_unavailable`	The API key has no webhook secret to sign the callback with. Create a new API key, or long-poll the operation instead.
403	`forbidden`	The caller’s role does not allow uploading files, so the export has nowhere to go.
404	`resource_not_found`	No report with this id, or the caller cannot read it.
409	`idempotency_key_reused`	The `Idempotency-Key` was used within 30 days with a different body.

An export of a report that is too large ends as failed with error.code report_too_large. Any other failure ends with export_failed, which is retryable.

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

Path parameters

Headers

Body parameters

Response

Errors

​Authentication

​Path parameters

​Headers

​Body parameters

​Response

​Errors

Authentication

Path parameters

Headers

Body parameters

Response

Errors