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

# Objects

> The objects the proposed endpoints return. Every endpoint page links back here.

> [!WARNING]
>
> **Proposed — not available yet.** This page describes a design under review. Nothing here can be called today.

All ids are UUIDs. All timestamps are ISO 8601 in UTC. Lists come back as a page: `{"items": [...], "cursor": "..."}`, where `cursor` is `null` on the last page. Pass it back as `?cursor=` to get the next one.

## Operation

The handle for anything that can take longer than a request. See [Long-running operations](/proposed/long-running-operations).

**id** `string` *required*

The operation id.

**type** `string` *required*

What the operation does: `question`, `review`, `review_redline`, `review_decisions`, `document_action`, `repository_indexing`, `report_run`, `report_export`, `playbook_generation` or `draft`.

**status** `string` *required*

`queued`, `running`, `succeeded`, `failed` or `cancelled`. The last three are terminal.

**progress** `object | null`

**properties**

**stage** `string`

The current step, e.g. `checks`, `redline`, `indexing`.

**completed** `integer`

Units done so far (checks, cells, documents).

**total** `integer | null`

Units in all, when known.

**resource** `object` *required*

The object this operation works on. Read it for the full picture.

**properties**

**type** `string`

`review`, `file`, `repository`, `report`, `playbook`, `blueprint`, `draft` or `session`.

**id** `string | null`

Its id. `null` until the work has created it, such as the session of a draft that has not started yet.

**result** `object | null`

Set when `status` is `succeeded`. Its shape depends on `type`:

| `type` | `result` |
| - | - |
| `question` | `{ "question_id", "session_id", "answer", "attachments" }` |
| `review` | `{ "review_id", "findings": { "total", "issues", "high", "medium", "low" }, "redline_file_id" }` |
| `review_redline`, `review_decisions`, `report_export` | `{ "file_id" }` |
| `document_action` | `{ "action", "file_ids", "summary" }` |
| `repository_indexing` | `{ "indexed", "failed" }` |
| `report_run` | `{ "cells_completed", "cells_total" }` |
| `playbook_generation` | `{ "playbook_id" }` |
| `draft` | `{ "file_id", "values", "url" }`. `values` is `null` without a blueprint. |

**error** `object | null`

Set when `status` is `failed`.

**properties**

**code** `string`

Machine-readable, e.g. `worker_lost`, `insufficient_credits`, `unsupported_file`.

**message** `string`

Human-readable detail.

**retryable** `boolean`

Whether starting the same work again may succeed.

**poll\_after\_seconds** `integer | null`

When to ask again. `null` once the operation is terminal.

**created\_at** `string` *required*

**updated\_at** `string` *required*

**completed\_at** `string | null`

## Review

A playbook or instructions review of one or more files. Built: see [Get Review](/api-reference/reviews/get-review), which documents every field. `counterparty_edits` reviews are read, not started, through the API.

**id** `string` *required*

**name** `string` *required*

The review's name, as the Wordsmith app shows it.

**type** `string` *required*

`playbook`, `instructions` or `counterparty_edits`.

**status** `string` *required*

`queued`, `running`, `completed`, `failed` or `cancelled`.

**file\_ids** `string[]` *required*

The review's own copies of the reviewed files.

**playbook\_id** `string | null`

Set for `playbook` reviews.

**instructions** `string | null`

Set for `instructions` reviews.

**party** `string | null`

The side the review acts for, as named in the document.

**findings** `object`

**properties**

**total** `integer`

**issues** `integer`

Findings whose `status` is `issue`.

**high** `integer`

**medium** `integer`

**low** `integer`

**redline\_file\_id** `string | null`

The tracked-changes DOCX of every proposed amendment, which the review writes itself. A ZIP of one DOCX per document when the amendments change more than one document.

**operation\_id** `string | null`

The latest operation the caller started on this review.

**url** `string`

Opens the review in Wordsmith.

**created\_at** `string` *required*

**updated\_at** `string` *required*

## Finding

One check's result. Its `id` is the check's id within the review. See [List Findings](/api-reference/reviews/list-findings).

**id** `string` *required*

**name** `string` *required*

The check's name.

**status** `string` *required*

`issue`, `ok`, `not_applicable` or `error`.

**severity** `string | null`

`high`, `medium` or `low`. Set for issues.

**explanation** `string | null`

Why, with reference to the playbook position.

**citations** `object[]`

`{ "file_id", "text" }` for each passage relied on.

**amendments** `object[]`

`{ "id", "type", "preview" }` for each proposed change. `type` is `modification`, `insertion`, `deletion` or `comment`.

## File

Unchanged from the live API: `{ "id", "file_name", "content_type", "content_length", "created_at" }`.

## Session and message

**Session** `object`

`{ "id", "agent_id", "title", "url", "created_at", "updated_at" }`. Get Session also returns `message_count`.

**Message** `object`

`{ "id", "role": "user" | "assistant", "content", "attachments": File[], "status": "completed" | "in_progress" | "error", "created_at" }`

## Repository and document

Live in the preview: see [Get Repository](/api-reference/repositories/get-repository).

**Repository** `object`

`{ "id", "name", "description", "document_count", "url", "created_at", "updated_at" }`. A single repository adds `"indexing_status": "idle" | "indexing" | "failed"`.

**RepositoryDocument** `object`

`{ "id", "file_id", "file_name", "folder_id", "indexing_status": "pending" | "indexed" | "failed", "created_at" }`

**Folder** `object`

`{ "id", "name", "parent_id" }`

**SearchResult** `object`

`{ "file_id", "file_name", "repository_id", "document_id", "snippet", "score" }`

## Report

**Report** `object`

`{ "id", "name", "description", "repository_id", "row_count", "column_count", "status": "idle" | "running", "url", "created_at", "updated_at" }`. Get Report also returns `columns: Column[]`, and Create Report also returns `operation_id`, the run it started.

**Column** `object`

`{ "id", "name", "prompt", "type": "text" | "number" | "date" | "boolean" | "single_select" | "multi_select", "options": string[] }`

**Row** `object`

`{ "id", "file_id", "name" }`

**Cell** `object`

`{ "row_id", "column_id", "value", "display_value", "status": "empty" | "pending" | "computing" | "done" | "failed", "citations": object[], "reviewed": boolean, "updated_at" }`

## Playbook and check

**Playbook** `object`

`{ "id", "name", "description", "url", "checks": Check[], "created_at", "updated_at" }`. The list route returns `{ "id", "name", "description", "url" }`. `url` opens the playbook in Wordsmith.

**Check** `object`

`{ "id", "name", "instructions", "severity": "high" | "medium" | "low", "standard_position", "fallback_positions": string[] }`. `fallback_positions` is read-only: only negotiation playbooks built in the app have them.

## Blueprint

**Blueprint** `object`

`{ "id", "name", "description", "url", "placeholders": [{ "key", "label", "type": "text" | "choice" | "multi_choice" | "boolean" | "table", "required", "description", "options" }] }`. The list routes return the first four fields. `url` opens the blueprint in Wordsmith; a Wordsmith blueprint opens read-only there, with an option to duplicate it.

## Research

**ResearchResult** `object`

`{ "source", "document_id", "title", "citation", "court_or_issuer", "jurisdiction", "date", "snippet", "url" }`

**ResearchDocument** `object`

`{ "source", "document_id", "title", "citation", "date", "url", "text", "text_truncated", "next_offset" }`. Pass `next_offset` back as `offset` to read on; it is `null` at the end. See [Get Research Document](/api-reference/research/get-document).

## Organisation

**CompanyProfile** `object`

`{ "id", "name", "address", "registration_number", "tax_number", "jurisdictions": string[], "industry": string[], "preferred_signatories": string[], "organization_type", "ownership", "is_part_of_group", "is_regulated", "regulatory_details", "is_gdpr_applicable", "data_storage_locations", "business_description", "target_customer_profiles": string[], "additional_info" }`. Agents use it as context about your organisation. An organisation can have several, for example one per group company.

**Member** `object`

`{ "id", "name", "email", "kind": "human" | "agent" | "chat_bot" | "service", "is_suspended", "predefined_roles": ("viewer" | "full_user" | "admin")[], "custom_role_ids": string[], "team_ids": string[] }`. The live List Users returns the first five fields. `team_ids` holds the teams the member is on directly.

**Team** `object`

`{ "id", "name", "parent_team_id", "member_count", "direct_member_count", "member_ids", "hidden", "membership_source": "manual" | "slack_channel", "members": [{ "user_id", "role": "admin" | "member" }] }`. The live List Teams returns the first six fields; Get Team adds the rest. `members` lists direct members only; `hidden` is `true` when the team or a team above it is hidden.

**Invite** `object`

`{ "id", "email", "predefined_roles", "custom_role_ids", "status": "pending" | "accepted" | "expired", "invited_by", "created_at", "expires_at" }`. Invites last 30 days. A revoked invite is deleted. The join link is never returned.

**Role** `object`

`{ "id", "name", "type": "predefined" | "custom", "description", "active", "member_count" }`. Predefined roles have the ids `viewer`, `full_user` and `admin`, and no `description`.

## Callback event

**Event** `object`

`{ "id", "type": "operation.succeeded" | "operation.failed" | "operation.cancelled", "created_at", "data" }`. `data` is the [operation](#operation). See [Callbacks](/proposed/callbacks).


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