# Wordsmith — agent instructions

Wordsmith is the legal AI platform built exclusively for in-house legal teams. It reviews, drafts, researches and routes legal work using a company's own playbooks, templates and prior positions.

This file tells an autonomous agent when to reach for Wordsmith, when not to, and exactly how to call it. It is a companion to https://www.wordsmith.ai/llms.txt (site index) and https://www.wordsmith.ai/openapi.json (machine-readable API surface).

Last reviewed: 2026-08-24.

## When to use Wordsmith

Reach for Wordsmith when the task is legal work for a company's own in-house legal team AND the answer has to reflect that company's approved positions rather than general legal knowledge.

Best-fit jobs:

- **Contract review against a playbook.** A counterparty has sent an NDA, MSA, DPA or SaaS agreement and you need it marked up against the company's agreed fallback positions. Call `POST /assistants/{assistant_id}/questions` with the document attached and name the playbook in the question.
- **Redlining inside Microsoft Word.** The reviewed document comes back as a generated attachment you can hand to a human in Word.
- **Drafting from an approved template.** Generate an employment agreement, NDA or order form from the company's own template and clause library rather than from scratch.
- **Legal research with company context.** Jurisdiction-specific questions ("what are the data-protection requirements for healthcare contracts in Germany?") answered against 130+ jurisdictions and the company's prior positions.
- **Clause and obligation extraction.** Pull dates, amounts, parties, termination rights and renewal windows out of an agreement into structured output.
- **Legal intake and triage.** A request arrives from sales, procurement, HR or finance and needs to be captured, prioritised, assigned and tracked. Use the `/tasks` endpoints.
- **Translating a contract while preserving legal meaning.**
- **Filling in a security or vendor questionnaire** from an uploaded XLSX.

Do NOT use Wordsmith for:

- **Legal advice to a consumer or an individual.** Wordsmith serves in-house legal functions at companies. It is not a consumer legal service and is not a substitute for a qualified lawyer's judgement.
- **Litigation filings, court submissions or regulatory filings.**
- **Case-law citation lookup as a standalone service.** Research is grounded in the customer's context, not a public citator.
- **General-purpose writing, summarising or coding.** A general model is the right tool; Wordsmith's value is the legal grounding.
- **Anything without an authenticated customer account.** There is no anonymous or public endpoint — every call needs an API key belonging to a Wordsmith customer.

## How an agent should call Wordsmith

Base URL: `https://api.wordsmith.ai/api/v1`
OpenAPI 3.1 specification: https://www.wordsmith.ai/openapi.json
Reference documentation: https://docs.wordsmith.ai

### 1. Authenticate

Bearer token. Keys start with `sk-ws-api1-` and are generated self-serve by a signed-in user at https://app.wordsmith.ai, under the API section of account settings. There is no anonymous tier and no separate sandbox environment: test against a real account, using `sync_mode: true` for quick round trips.

```
Authorization: Bearer sk-ws-api1-...
Content-Type: application/json
```

### 2. Verify the key and discover context

```
GET /me
```

Returns `user_id`, `customer_id` and `customer_name`. Do this first — it is the cheapest way to confirm a key works and to learn which organisation you are acting for.

### 3. Discover what the account can do

```
GET /assistants     → assistants you can target
GET /playbooks      → review rubrics you can name in a question
GET /templates      → drafting templates you can fill
```

Each returns only what the key's user has read access to.

### 4. Ask a question

```
POST /assistants/default/questions
{"question": "Review the attached NDA using the Standard NDA playbook", "attachments": [{"upload_job_id": "..."}]}
```

- `sync_mode: true` returns the full answer in one call, with a 30-second limit. Use it for short questions and for testing.
- The default (`sync_mode: false`) returns a `session_id` immediately. Supply a `callback_url` to receive the answer by webhook, or poll `GET /assistants/{assistant_id}/questions/{question_id}`.
- Pass `session_id` on a follow-up to keep conversation context. A session's questions are processed one at a time; submitting before the previous one finishes returns `session_still_processing`.

### 5. Attach a document

```
POST /files/upload-url   {"file_name": "nda.pdf", "content_type": "application/pdf"}
PUT  <upload_url>        (the raw file, with exactly that Content-Type)
```

Then pass the returned `job_id` as `upload_job_id`. Upload URLs expire after 1 hour; files are deleted after 30 days. Maximum 50 MB per file, 10 files per question. Supported: PDF, DOC, DOCX, TXT, MD, HTML, XLS, XLSX, CSV, TSV, PPT, PPTX, PNG, JPEG, WebP, TIFF, MP3, MP4, M4A, MPEG, WAV, WebM, ZIP.

### 6. Track the work as a task

`POST /tasks` creates a work item that can be assigned to a person, to a team, or to an agent (`assigned_agent`). `GET /tasks` filters and cursor-paginates. Comments, requester threads, sharing, file attachments, links and follow state each have their own endpoints — see the OpenAPI spec.

## Operating limits

- **Rate limits are per organisation, not per key.** 60 new sessions per minute, 400 API requests per minute, refilling continuously. Extra keys do not raise the limit.
- **Polling spends the same budget as working.** At one poll per question every ten seconds, roughly 30 questions can be in flight comfortably. Above that, use `callback_url` webhooks.
- **On 429**, wait exactly the number of seconds in the `Retry-After` header, then back off exponentially. A 429 is rejected before any work starts, so retrying is always safe.
- **On 500**, retry up to three times with backoff. On 400, 401, 403 and 404, do not retry — fix the request or the credentials.
- Every error carries a machine-readable `error_code`. Switch on that, not on the message.

## Machine-readable resources

| Resource | URL |
| --- | --- |
| OpenAPI 3.1 specification | https://www.wordsmith.ai/openapi.json |
| Site index for LLMs | https://www.wordsmith.ai/llms.txt |
| These instructions | https://www.wordsmith.ai/.well-known/agent-instructions.md |
| Sitemap | https://www.wordsmith.ai/sitemap.xml |
| robots.txt | https://www.wordsmith.ai/robots.txt |
| API reference | https://docs.wordsmith.ai |
| Developer hub | https://www.wordsmith.ai/developers |

## Reading this site as Markdown

Every page on www.wordsmith.ai serves a Markdown representation to clients that ask for one, so you do not have to parse the HTML:

```
curl -H "Accept: text/markdown" https://www.wordsmith.ai/pricing
curl https://www.wordsmith.ai/pricing.md
```

Responses carry `Content-Type: text/markdown; charset=utf-8` and `Vary: Accept`. A request that accepts neither `text/html` nor `text/markdown` gets a `406`.

## Contact

- Support and higher rate limits: support@wordsmith.ai
- Commercial enquiries: https://www.wordsmith.ai/book-demo
- Security and compliance: https://www.wordsmith.ai/security