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

# Proposed API overview

> What the next version of the Wordsmith API and MCP server adds, and the principles behind it.

> [!WARNING]
>
> **Proposed — not available yet.** These pages describe a design under review. They are unlisted: reachable by link, but not in the navigation or search. The live API is documented under [API Reference](/api-reference/user/get-me).

Today the Wordsmith API lets you ask an agent a question, manage tasks, and upload files. This proposal opens up the rest of Wordsmith: playbook reviews, counterparty edits, redlines and comparisons, reports, repositories and knowledge search, legal research, drafting, and usage and value.

## What you will be able to build

> **[Review a contract](/api-reference/reviews/create-review)**
>
> Run a playbook against an NDA, read the findings, and download a tracked-changes DOCX.

> **[Answer the other side's markup](/proposed/api/reviews/submit-decisions)**
>
> Triage every tracked change as accept, reject or counter, and get back a response draft.

> **[Transform documents](/api-reference/documents/compare)**
>
> Compare, redline by instruction, translate, redact, convert, accept changes and merge.

> **[Review hundreds of documents](/api-reference/reports/create-report)**
>
> Extract the same fields from every lease in a repository and export the grid to Excel.

> **[Search your knowledge](/api-reference/search/search-knowledge)**
>
> Search by meaning across the repositories you can read.

> **[Research the law](/api-reference/research/search)**
>
> Search case law and legislation across jurisdictions, and read the documents.

> **[Draft a document](/api-reference/drafts/create-draft)**
>
> Fill a blueprint from a term sheet and get a DOCX back.

> **[Administer your organisation](/api-reference/organisation/create-invite)**
>
> Keep members, roles and teams in sync with your HR or practice systems, and maintain the company profile agents use.

> **[Connect an AI assistant](/proposed/mcp)**
>
> Use all of this from ChatGPT, Claude or any MCP host, with about two dozen tools.

## Three ideas run through the whole design

**1. Long work returns an operation**

Reviews, redlines, translations and reports take minutes. Every request still has to finish within 29 seconds. So anything that can take longer returns an [operation](/proposed/long-running-operations) straight away. You poll it, wait on it, or get a [callback](/proposed/callbacks) when it finishes. There is one pattern for every long-running endpoint.

**2. Files are the currency**

Every input document is a `file_id` from the [files API](/api-reference/files/upload-url). Every document Wordsmith produces, such as a redline, a translation or an export, is a new `file_id` you download the same way. No endpoint takes or returns document bytes inline.

**3. The REST API is broad; the MCP server is small**

REST has an endpoint for every action, so integrations can do exactly what they need. The [MCP server](/proposed/mcp) has about two dozen tools shaped around jobs, such as `review_document` and `transform_document`. Assistants pick the right tool more reliably from a short list, and every tool calls the same code as its REST endpoints.

## A review in three calls

```bash theme={null}
# 1. Start a playbook review. Returns an operation.
curl -X POST https://api.wordsmith.ai/api/v1/reviews \
  -H "Authorization: Bearer sk-ws-api1-your_api_key_here" \
  -H "Idempotency-Key: 6f1d2c3e-review-nda-42" \
  -H "Content-Type: application/json" \
  -d '{"type": "playbook", "file_ids": ["9a1d7e44-2b6c-4f08-8d3a-71c5e0b9f2a6"],
       "playbook_id": "2c4b8f90-5d1e-4a37-b6e2-c8f0a3d71e45", "generate_redline": true}'

# 2. Wait for it. Each call holds for up to 20 seconds and returns as soon as it finishes.
curl "https://api.wordsmith.ai/api/v1/operations/3b8e0f1c-6a2d-4e57-9c1b-2f7d8a4e6b90?wait=20" \
  -H "Authorization: Bearer sk-ws-api1-your_api_key_here"

# 3. Read the findings, then download result.redline_file_id with the files API.
curl "https://api.wordsmith.ai/api/v1/reviews/5f0c9a12-8e3b-4d71-a6c4-0b2e9f7d3c58/findings?status=issue" \
  -H "Authorization: Bearer sk-ws-api1-your_api_key_here"
```

## What stays the same

* **Authentication.** API keys and OAuth tokens work as today. New areas get new [scopes](/proposed/scopes).
* **Existing endpoints.** Questions, tasks, files, playbooks and directory routes keep their paths and responses. `/templates` becomes `/blueprints`, and the old path keeps working with a deprecation header. Everything new is additive under `/api/v1`.
* **Errors, pagination and rate limits.** The [error envelope](/errors), `{items, cursor}` pages and [rate limits](/rate-limits) carry over. Starting an operation has its own limit, described in [Long-running operations](/proposed/long-running-operations#limits).

## Delivery order

| Phase | What ships |
| - | - |
| 0 | Operations, idempotency keys, retried callbacks |
| 1 | Reviews, document actions, sessions, and the consolidated MCP tools |
| 2 | Repositories, knowledge search, reports |
| 3 | Playbook authoring, drafting, research |
| 4 | Sharing, usage and value, organisation administration |

Each phase moves into the **API Reference** when it is live.


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