Proposed API overview - Wordsmith API

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.

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

Run a playbook against an NDA, read the findings, and download a tracked-changes DOCX.

Answer the other side's markup

Triage every tracked change as accept, reject or counter, and get back a response draft.

Transform documents

Compare, redline by instruction, translate, redact, convert, accept changes and merge.

Review hundreds of documents

Extract the same fields from every lease in a repository and export the grid to Excel.

Search your knowledge

Search by meaning across the repositories you can read.

Research the law

Search case law and legislation across jurisdictions, and read the documents.

Draft a document

Fill a blueprint from a term sheet and get a DOCX back.

Administer your organisation

Keep members, roles and teams in sync with your HR or practice systems, and maintain the company profile agents use.

Connect an AI assistant

Use all of this from ChatGPT, Claude or any MCP host, with about two dozen tools.

Three ideas run through the whole design

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 straight away. You poll it, wait on it, or get a callback when it finishes. There is one pattern for every long-running endpoint.

Files are the currency

Every input document is a file_id from the files API. 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.

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

# 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.
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, {items, cursor} pages and rate limits carry over. Starting an operation has its own limit, described in Long-running operations.

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.

​What you will be able to build

Review a contract

Answer the other side's markup

Transform documents

Review hundreds of documents

Search your knowledge

Research the law

Draft a document

Administer your organisation

Connect an AI assistant

​Three ideas run through the whole design

​A review in three calls

​What stays the same

​Delivery order

What you will be able to build

Three ideas run through the whole design

A review in three calls

What stays the same

Delivery order