{ "openapi": "3.1.0", "info": { "title": "Wordsmith Public API", "version": "1.0.0", "summary": "Programmatic access to Wordsmith, the legal AI platform built exclusively for in-house legal teams.", "description": "The Wordsmith Public API lets AI agents, copilots and internal tools invoke Wordsmith's legal capabilities directly: ask legal questions grounded in your own playbooks and templates, upload contracts for review, and create and manage legal tasks.\n\n**When to use it.** Reach for this API when a workflow needs contract review, legal drafting, legal research across jurisdictions, or intake and triage of legal requests, and the answer must be grounded in a specific company's approved positions rather than general legal knowledge.\n\n**Getting started.** Sign in at https://app.wordsmith.ai, open the API section of your account settings, and generate a key. Keys are prefixed `sk-ws-api1-` and are sent as a bearer token. Call `GET /me` first to confirm the key works.\n\n**Execution modes.** `POST /assistants/{assistant_id}/questions` runs synchronously (`sync_mode: true`, 30-second limit) or asynchronously (the default), returning a session id you either poll with `GET /assistants/{assistant_id}/questions/{question_id}` or receive via a `callback_url` webhook. Webhooks are strongly preferred at volume: polling consumes the same rate limit as the calls that create the work.\n\n**Rate limits.** Per organisation, not per key: 60 new sessions per minute and 400 API requests per minute, refilling continuously. A 429 carries `Retry-After`; honour it, then back off exponentially.\n\n**Authorisation model.** Access is scoped to what the key's user can see — list endpoints return only the assistants, playbooks, templates and tasks that user has read access to, and tasks carry their own `private`/`customer` visibility with `read`/`write` access levels. API keys themselves are not sub-scoped today; request least-privilege keys from support@wordsmith.ai.\n\nThis document is published by Wordsmith at https://www.wordsmith.ai/openapi.json and is derived from the reference documentation at https://docs.wordsmith.ai.", "termsOfService": "https://www.wordsmith.ai/terms-of-service", "license": { "name": "Proprietary — governed by the Wordsmith Terms of Service", "url": "https://www.wordsmith.ai/terms-of-service" }, "contact": { "name": "Wordsmith API support", "email": "support@wordsmith.ai", "url": "https://docs.wordsmith.ai" }, "x-audience": "In-house legal teams and the AI agents acting on their behalf" }, "externalDocs": { "description": "Wordsmith API documentation", "url": "https://docs.wordsmith.ai" }, "servers": [ { "url": "https://api.wordsmith.ai/api/v1", "description": "Production" } ], "security": [ { "bearerAuth": [] } ], "tags": [ { "name": "User", "description": "Identity of the authenticated key.", "externalDocs": { "url": "https://docs.wordsmith.ai/api-reference/user/get-me" } }, { "name": "Assistants", "description": "Ask legal questions and retrieve answers.", "externalDocs": { "url": "https://docs.wordsmith.ai/api-reference/assistants/list-assistants" } }, { "name": "Files", "description": "Upload documents for analysis.", "externalDocs": { "url": "https://docs.wordsmith.ai/api-reference/files/upload-url" } }, { "name": "Playbooks", "description": "Review rubrics an assistant can apply.", "externalDocs": { "url": "https://docs.wordsmith.ai/api-reference/playbooks/list-playbooks" } }, { "name": "Templates", "description": "Drafting templates an assistant can fill.", "externalDocs": { "url": "https://docs.wordsmith.ai/api-reference/templates/list-templates" } }, { "name": "Tasks", "description": "Create, assign and progress legal work items.", "externalDocs": { "url": "https://docs.wordsmith.ai/api-reference/tasks/list-tasks" } }, { "name": "Directory", "description": "People, agents and teams in the organisation.", "externalDocs": { "url": "https://docs.wordsmith.ai/api-reference/directory/list-users" } } ], "paths": { "/me": { "get": { "operationId": "getCurrentUser", "tags": [ "User" ], "summary": "Get the authenticated user", "description": "Returns the user and customer organisation behind the API key. Call this first to verify a key works and to discover the organisation you are acting in.", "externalDocs": { "description": "Reference documentation", "url": "https://docs.wordsmith.ai/api-reference/user/get-me" }, "responses": { "200": { "description": "The authenticated user.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/User" } } } }, "400": { "description": "Bad request. See `error_code` for the specific cause.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, malformed or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The API key does not have permission to perform this action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The requested resource was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded. Honour the `Retry-After` header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "500": { "description": "Unexpected server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/assistants": { "get": { "operationId": "listAssistants", "tags": [ "Assistants" ], "summary": "List assistants", "description": "Lists the assistants the key's user has read access to, including both organisation-specific and global assistants. Use an `id` from here as `assistant_id`, or the literal `default` for the general assistant.", "externalDocs": { "description": "Reference documentation", "url": "https://docs.wordsmith.ai/api-reference/assistants/list-assistants" }, "responses": { "200": { "description": "Assistants available to the caller.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Assistant" } } } } }, "400": { "description": "Bad request. See `error_code` for the specific cause.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, malformed or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The API key does not have permission to perform this action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The requested resource was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded. Honour the `Retry-After` header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "500": { "description": "Unexpected server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/assistants/{assistant_id}/questions": { "post": { "operationId": "createAssistantQuestion", "tags": [ "Assistants" ], "summary": "Ask the assistant a legal question", "description": "Creates a session by asking a question, or continues an existing session when `session_id` is supplied. Attach contracts to have them reviewed, redlined, summarised or extracted. Use `sync_mode: true` only for testing; production integrations should run async and receive the answer via `callback_url`.", "externalDocs": { "description": "Reference documentation", "url": "https://docs.wordsmith.ai/api-reference/assistants/create-question" }, "responses": { "200": { "description": "The created question. `answer` is populated only in sync mode or once processing completes.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QuestionResponse" } } } }, "400": { "description": "Bad request. See `error_code` for the specific cause.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, malformed or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The API key does not have permission to perform this action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The requested resource was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded. Honour the `Retry-After` header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "500": { "description": "Unexpected server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "assistant_id", "in": "path", "required": true, "description": "Assistant to use. `default` is the general Wordsmith assistant.", "schema": { "type": "string", "default": "default" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QuestionRequest" } } } } } }, "/assistants/{assistant_id}/questions/{question_id}": { "get": { "operationId": "getAssistantQuestion", "tags": [ "Assistants" ], "summary": "Get a question's status and answer", "description": "Polls one question. Start at 2-3 second intervals and back off exponentially; most questions finish within 2-5 minutes. Each poll consumes rate-limit budget, so prefer a `callback_url` webhook at volume.", "externalDocs": { "description": "Reference documentation", "url": "https://docs.wordsmith.ai/api-reference/assistants/get-question-status" }, "responses": { "200": { "description": "Current state of the question.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QuestionResponse" } } } }, "400": { "description": "Bad request. See `error_code` for the specific cause.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, malformed or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The API key does not have permission to perform this action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The requested resource was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded. Honour the `Retry-After` header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "500": { "description": "Unexpected server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "assistant_id", "in": "path", "required": true, "description": "Assistant that processed the question.", "schema": { "type": "string" } }, { "name": "question_id", "in": "path", "required": true, "description": "The `id` returned when the question was created.", "schema": { "type": "string", "format": "uuid" } } ] } }, "/files/upload-url": { "post": { "operationId": "createFileUploadUrl", "tags": [ "Files" ], "summary": "Create a presigned file upload URL", "description": "Step one of attaching a document. PUT the file to `upload_url` with exactly the `content_type` you declared, then pass `job_id` as `upload_job_id` on a question or task. URLs expire after 1 hour; files are deleted after 30 days. Maximum 50 MB per file.", "externalDocs": { "description": "Reference documentation", "url": "https://docs.wordsmith.ai/api-reference/files/upload-url" }, "responses": { "200": { "description": "Where to upload, and the handle to reference the file by.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UploadUrlResponse" } } } }, "400": { "description": "Bad request. See `error_code` for the specific cause.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, malformed or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The API key does not have permission to perform this action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The requested resource was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded. Honour the `Retry-After` header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "500": { "description": "Unexpected server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UploadUrlRequest" } } } } } }, "/playbooks": { "get": { "operationId": "listPlaybooks", "tags": [ "Playbooks" ], "summary": "List playbooks", "description": "Lists the review playbooks the key's user has read access to. Reference one by name or `id` in a question to have the assistant review a document against it.", "externalDocs": { "description": "Reference documentation", "url": "https://docs.wordsmith.ai/api-reference/playbooks/list-playbooks" }, "responses": { "200": { "description": "Playbooks available to the caller.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Playbook" } } } } }, "400": { "description": "Bad request. See `error_code` for the specific cause.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, malformed or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The API key does not have permission to perform this action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The requested resource was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded. Honour the `Retry-After` header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "500": { "description": "Unexpected server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/templates": { "get": { "operationId": "listTemplates", "tags": [ "Templates" ], "summary": "List drafting templates", "description": "Lists the document templates the key's user has read access to. Reference one by name or `id` in a question to have the assistant fill it in.", "externalDocs": { "description": "Reference documentation", "url": "https://docs.wordsmith.ai/api-reference/templates/list-templates" }, "responses": { "200": { "description": "Templates available to the caller.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Template" } } } } }, "400": { "description": "Bad request. See `error_code` for the specific cause.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, malformed or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The API key does not have permission to perform this action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The requested resource was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded. Honour the `Retry-After` header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "500": { "description": "Unexpected server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/tasks": { "get": { "operationId": "listTasks", "tags": [ "Tasks" ], "summary": "List and filter tasks", "description": "Returns a cursor-paginated page of tasks the caller can see, ordered by priority, then due date, then most recently created. Archived and draft tasks are excluded unless filtered for. Keep `limit` identical across every page of a walk — the cursor is tied to the page size it was issued with.", "externalDocs": { "description": "Reference documentation", "url": "https://docs.wordsmith.ai/api-reference/tasks/list-tasks" }, "responses": { "200": { "description": "A page of tasks.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaskPage" } } } }, "400": { "description": "Bad request. See `error_code` for the specific cause.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, malformed or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The API key does not have permission to perform this action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The requested resource was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded. Honour the `Retry-After` header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "500": { "description": "Unexpected server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "query", "in": "query", "required": false, "description": "Free-text search across title, description, additional context and comment text.", "schema": { "type": "string" } }, { "name": "status", "in": "query", "required": false, "description": "Comma-separated statuses to include.", "schema": { "type": "string", "examples": [ "in_progress,completed" ] } }, { "name": "priority", "in": "query", "required": false, "description": "Single priority to filter on.", "schema": { "$ref": "#/components/schemas/TaskPriority" } }, { "name": "assigned_to", "in": "query", "required": false, "description": "Only tasks assigned to this user.", "schema": { "type": "string", "format": "uuid" } }, { "name": "involving", "in": "query", "required": false, "description": "Tasks this user is involved in at all — assignee, creator or shared.", "schema": { "type": "string", "format": "uuid" } }, { "name": "team_id", "in": "query", "required": false, "description": "Task team id.", "schema": { "type": "string", "format": "uuid" } }, { "name": "tags", "in": "query", "required": false, "description": "Comma-separated tag list.", "schema": { "type": "string" } }, { "name": "complete_by_from", "in": "query", "required": false, "description": "Only tasks due at or after this ISO 8601 timestamp.", "schema": { "type": "string" } }, { "name": "complete_by_to", "in": "query", "required": false, "description": "Only tasks due at or before this ISO 8601 timestamp.", "schema": { "type": "string" } }, { "name": "cursor", "in": "query", "required": false, "description": "Pagination cursor from a previous response.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "Page size, 1-100.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } } ] }, "post": { "operationId": "createTask", "tags": [ "Tasks" ], "summary": "Create a task", "description": "Creates a task in the organisation's default task team. `assigned_to` and `assigned_agent` are independent — a task can carry both a human owner and an executing agent. Set `draft: true` to stage it for review and accept it later by patching `draft` to false. Choosing a different team, and creating a task as private, are not supported in v1.", "externalDocs": { "description": "Reference documentation", "url": "https://docs.wordsmith.ai/api-reference/tasks/create-task" }, "responses": { "200": { "description": "The created task.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Task" } } } }, "400": { "description": "Bad request. See `error_code` for the specific cause.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, malformed or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The API key does not have permission to perform this action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The requested resource was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded. Honour the `Retry-After` header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "500": { "description": "Unexpected server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "title" ], "description": "The task to create.", "properties": { "title": { "type": "string", "description": "Short summary of the work to be done." }, "description": { "type": "string", "description": "Primary instruction for whoever picks the task up." }, "parent_task_id": { "type": "string", "format": "uuid", "description": "Create as a subtask of this task." }, "assigned_to": { "type": "string", "format": "uuid", "description": "Person responsible." }, "assigned_agent": { "type": "string", "format": "uuid", "description": "Agent that should execute the task." }, "assigned_team_id": { "type": "string", "format": "uuid", "description": "Team the task is assigned to. Grants that team editor access." }, "matter_id": { "type": "string", "format": "uuid", "description": "Matter to file the task under." }, "status": { "$ref": "#/components/schemas/TaskStatus" }, "priority": { "$ref": "#/components/schemas/TaskPriority" }, "complete_by": { "type": "string", "format": "date-time", "description": "Due date, ISO 8601." }, "tags": { "type": "array", "items": { "type": "string" }, "description": "Free-form labels." }, "linked_items": { "type": "array", "items": { "$ref": "#/components/schemas/LinkedItem" }, "description": "Chats, reviews, reports or other tasks to link." }, "draft": { "type": "boolean", "description": "Create as a draft rather than a committed work item." } } } } } } } }, "/tasks/{task_id}": { "get": { "operationId": "getTask", "tags": [ "Tasks" ], "summary": "Get a task", "description": "Fetches a single task by id, including its assignees, status, due date, tags and links. `display_id` is the human-facing key shown in the Wordsmith UI.", "externalDocs": { "description": "Reference documentation", "url": "https://docs.wordsmith.ai/api-reference/tasks/get-task" }, "responses": { "200": { "description": "The task.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Task" } } } }, "400": { "description": "Bad request. See `error_code` for the specific cause.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, malformed or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The API key does not have permission to perform this action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The requested resource was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded. Honour the `Retry-After` header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "500": { "description": "Unexpected server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "task_id", "in": "path", "required": true, "description": "The task's unique identifier.", "schema": { "type": "string", "format": "uuid" } } ] }, "patch": { "operationId": "updateTask", "tags": [ "Tasks" ], "summary": "Update a task", "description": "Only the fields you send change, and `{}` does nothing. An explicit null CLEARS `description`, `additional_context`, `assigned_to`, `assigned_agent`, `assigned_team_id`, `complete_by` and `matter_id`; for every other field null is ignored. State changes are fields, not endpoints: archive with `archived: true`, accept a draft with `draft: false`. Archiving and drafting are orthogonal to `status`.", "externalDocs": { "description": "Reference documentation", "url": "https://docs.wordsmith.ai/api-reference/tasks/update-task" }, "responses": { "200": { "description": "The updated task.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Task" } } } }, "400": { "description": "Bad request. See `error_code` for the specific cause.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, malformed or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The API key does not have permission to perform this action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The requested resource was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded. Honour the `Retry-After` header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "500": { "description": "Unexpected server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "task_id", "in": "path", "required": true, "description": "The task's unique identifier.", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "description": "Fields to change.", "properties": { "title": { "type": "string", "description": "Short summary of the work." }, "description": { "type": [ "string", "null" ], "description": "Primary instruction. Null clears it." }, "additional_context": { "type": [ "string", "null" ], "description": "Supplementary context. Null clears it." }, "assigned_to": { "type": [ "string", "null" ], "format": "uuid", "description": "Null unassigns." }, "assigned_agent": { "type": [ "string", "null" ], "format": "uuid", "description": "Null detaches the agent." }, "assigned_team_id": { "type": [ "string", "null" ], "format": "uuid", "description": "Null unassigns the team." }, "matter_id": { "type": [ "string", "null" ], "format": "uuid", "description": "Null unfiles the task." }, "status": { "$ref": "#/components/schemas/TaskStatus" }, "priority": { "$ref": "#/components/schemas/TaskPriority" }, "complete_by": { "type": [ "string", "null" ], "format": "date-time", "description": "Null clears the due date." }, "tags": { "type": "array", "items": { "type": "string" }, "description": "Replaces the whole tag list." }, "linked_items": { "type": "array", "items": { "$ref": "#/components/schemas/LinkedItem" }, "description": "Replaces the whole link list." }, "involved_people": { "type": "array", "items": { "type": "string", "format": "uuid" }, "description": "Replaces the set of people involved." }, "archived": { "type": "boolean", "description": "Shelve (true) or restore (false)." }, "draft": { "type": "boolean", "description": "Accept a draft with false. To reject a draft, delete the task." } } } } } } }, "delete": { "operationId": "deleteTask", "tags": [ "Tasks" ], "summary": "Delete a task or reject a draft", "description": "Deletes the task and its subtasks. Rejecting a draft is the same operation.", "externalDocs": { "description": "Reference documentation", "url": "https://docs.wordsmith.ai/api-reference/tasks/delete-task" }, "responses": { "204": { "description": "Deleted." }, "400": { "description": "Bad request. See `error_code` for the specific cause.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, malformed or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The API key does not have permission to perform this action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The requested resource was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded. Honour the `Retry-After` header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "500": { "description": "Unexpected server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "task_id", "in": "path", "required": true, "description": "The task's unique identifier.", "schema": { "type": "string", "format": "uuid" } } ] } }, "/tasks/{task_id}/subtasks": { "get": { "operationId": "listSubtasks", "tags": [ "Tasks" ], "summary": "List a task's subtasks", "description": "Lists the subtasks of a task. Create one by passing `parent_task_id` when creating a task.", "externalDocs": { "description": "Reference documentation", "url": "https://docs.wordsmith.ai/api-reference/tasks/list-subtasks" }, "responses": { "200": { "description": "The subtasks.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Task" } } } } }, "400": { "description": "Bad request. See `error_code` for the specific cause.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, malformed or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The API key does not have permission to perform this action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The requested resource was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded. Honour the `Retry-After` header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "500": { "description": "Unexpected server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "task_id", "in": "path", "required": true, "description": "The task's unique identifier.", "schema": { "type": "string", "format": "uuid" } } ] } }, "/tasks/{task_id}/comments": { "get": { "operationId": "listTaskComments", "tags": [ "Tasks" ], "summary": "List a task's internal comments", "description": "Comments are the task's internal discussion, visible to people with access to the task. To reach the person who requested the task, use the thread endpoints instead.", "externalDocs": { "description": "Reference documentation", "url": "https://docs.wordsmith.ai/api-reference/tasks/list-comments" }, "responses": { "200": { "description": "The comments.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/TaskComment" } } } } }, "400": { "description": "Bad request. See `error_code` for the specific cause.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, malformed or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The API key does not have permission to perform this action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The requested resource was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded. Honour the `Retry-After` header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "500": { "description": "Unexpected server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "task_id", "in": "path", "required": true, "description": "The task's unique identifier.", "schema": { "type": "string", "format": "uuid" } } ] }, "post": { "operationId": "addTaskComment", "tags": [ "Tasks" ], "summary": "Add an internal comment", "description": "Adds an internal comment. Attach files by passing ids from the file upload endpoint.", "externalDocs": { "description": "Reference documentation", "url": "https://docs.wordsmith.ai/api-reference/tasks/add-comment" }, "responses": { "200": { "description": "The created comment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaskComment" } } } }, "400": { "description": "Bad request. See `error_code` for the specific cause.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, malformed or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The API key does not have permission to perform this action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The requested resource was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded. Honour the `Retry-After` header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "500": { "description": "Unexpected server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "task_id", "in": "path", "required": true, "description": "The task's unique identifier.", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "content" ], "description": "The comment to add.", "properties": { "content": { "type": "string", "description": "Comment body." }, "file_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "description": "Files to attach, from the file upload endpoint." } } } } } } } }, "/tasks/{task_id}/comments/{comment_id}": { "patch": { "operationId": "updateTaskComment", "tags": [ "Tasks" ], "summary": "Edit a comment", "description": "Edits the content of a comment you authored.", "externalDocs": { "description": "Reference documentation", "url": "https://docs.wordsmith.ai/api-reference/tasks/update-comment" }, "responses": { "200": { "description": "The updated comment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaskComment" } } } }, "400": { "description": "Bad request. See `error_code` for the specific cause.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, malformed or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The API key does not have permission to perform this action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The requested resource was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded. Honour the `Retry-After` header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "500": { "description": "Unexpected server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "task_id", "in": "path", "required": true, "description": "The task's unique identifier.", "schema": { "type": "string", "format": "uuid" } }, { "name": "comment_id", "in": "path", "required": true, "description": "The comment's unique identifier.", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "content" ], "description": "Replacement content.", "properties": { "content": { "type": "string", "description": "The replacement comment body." } } } } } } }, "delete": { "operationId": "deleteTaskComment", "tags": [ "Tasks" ], "summary": "Delete a comment", "description": "Permanently deletes one comment from a task's internal discussion. Replies to the deleted comment are not removed automatically.", "externalDocs": { "description": "Reference documentation", "url": "https://docs.wordsmith.ai/api-reference/tasks/delete-comment" }, "responses": { "204": { "description": "Deleted." }, "400": { "description": "Bad request. See `error_code` for the specific cause.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, malformed or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The API key does not have permission to perform this action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The requested resource was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded. Honour the `Retry-After` header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "500": { "description": "Unexpected server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "task_id", "in": "path", "required": true, "description": "The task's unique identifier.", "schema": { "type": "string", "format": "uuid" } }, { "name": "comment_id", "in": "path", "required": true, "description": "The comment's unique identifier.", "schema": { "type": "string", "format": "uuid" } } ] } }, "/tasks/{task_id}/comments/{comment_id}/replies": { "post": { "operationId": "replyToTaskComment", "tags": [ "Tasks" ], "summary": "Reply to a comment", "description": "Creates a threaded reply; the new comment's `parent_comment_id` is the comment you replied to.", "externalDocs": { "description": "Reference documentation", "url": "https://docs.wordsmith.ai/api-reference/tasks/reply-comment" }, "responses": { "200": { "description": "The created reply.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaskComment" } } } }, "400": { "description": "Bad request. See `error_code` for the specific cause.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, malformed or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The API key does not have permission to perform this action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The requested resource was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded. Honour the `Retry-After` header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "500": { "description": "Unexpected server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "task_id", "in": "path", "required": true, "description": "The task's unique identifier.", "schema": { "type": "string", "format": "uuid" } }, { "name": "comment_id", "in": "path", "required": true, "description": "The comment's unique identifier.", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "content" ], "description": "The reply.", "properties": { "content": { "type": "string", "description": "Comment body." }, "file_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "description": "Files to attach." } } } } } } } }, "/tasks/{task_id}/thread": { "get": { "operationId": "listTaskThread", "tags": [ "Tasks" ], "summary": "Read the requester conversation", "description": "Tasks raised over Slack, email or a connected mailbox carry a thread with the requester. Behind a feature flag separate from tasks: returns 404 unless enabled for your organisation.", "externalDocs": { "description": "Reference documentation", "url": "https://docs.wordsmith.ai/api-reference/tasks/list-thread" }, "responses": { "200": { "description": "Messages in the thread.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ThreadMessage" } } } } }, "400": { "description": "Bad request. See `error_code` for the specific cause.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, malformed or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The API key does not have permission to perform this action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The requested resource was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded. Honour the `Retry-After` header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "500": { "description": "Unexpected server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "task_id", "in": "path", "required": true, "description": "The task's unique identifier.", "schema": { "type": "string", "format": "uuid" } } ] }, "post": { "operationId": "addTaskThreadReply", "tags": [ "Tasks" ], "summary": "Reply to the requester", "description": "Sends a reply back over the task's origin channel. For a connected personal mailbox the reply is staged as a draft for the mailbox owner to send. For an internal note the requester never sees, add a comment instead. Behind a feature flag: returns 404 unless enabled for your organisation.", "externalDocs": { "description": "Reference documentation", "url": "https://docs.wordsmith.ai/api-reference/tasks/add-thread-reply" }, "responses": { "200": { "description": "The sent or staged reply.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ThreadMessage" } } } }, "400": { "description": "Bad request. See `error_code` for the specific cause.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, malformed or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The API key does not have permission to perform this action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The requested resource was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded. Honour the `Retry-After` header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "500": { "description": "Unexpected server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "task_id", "in": "path", "required": true, "description": "The task's unique identifier.", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "content" ], "description": "The reply to send.", "properties": { "content": { "type": "string", "description": "The reply body, sent to the requester." }, "file_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "description": "Files to attach." } } } } } } } }, "/tasks/{task_id}/sharing": { "get": { "operationId": "getTaskSharing", "tags": [ "Tasks" ], "summary": "Read a task's sharing state", "description": "Returns the task's visibility and the exact set of people and teams it is shared with, each with their access level. Read this before calling the PUT, which replaces the whole state.", "externalDocs": { "description": "Reference documentation", "url": "https://docs.wordsmith.ai/api-reference/tasks/get-sharing" }, "responses": { "200": { "description": "Current sharing state.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaskSharing" } } } }, "400": { "description": "Bad request. See `error_code` for the specific cause.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, malformed or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The API key does not have permission to perform this action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The requested resource was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded. Honour the `Retry-After` header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "500": { "description": "Unexpected server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "task_id", "in": "path", "required": true, "description": "The task's unique identifier.", "schema": { "type": "string", "format": "uuid" } } ] }, "put": { "operationId": "updateTaskSharing", "tags": [ "Tasks" ], "summary": "Replace a task's sharing state", "description": "Replaces the whole sharing state — send the full desired lists, because anyone omitted loses access.", "externalDocs": { "description": "Reference documentation", "url": "https://docs.wordsmith.ai/api-reference/tasks/update-sharing" }, "responses": { "200": { "description": "The new sharing state.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaskSharing" } } } }, "400": { "description": "Bad request. See `error_code` for the specific cause.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, malformed or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The API key does not have permission to perform this action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The requested resource was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded. Honour the `Retry-After` header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "500": { "description": "Unexpected server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "task_id", "in": "path", "required": true, "description": "The task's unique identifier.", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaskSharing" } } } } } }, "/tasks/{task_id}/files": { "post": { "operationId": "attachTaskFiles", "tags": [ "Tasks" ], "summary": "Attach files to a task", "description": "Upload the file first with the file upload endpoint, then attach it by id.", "externalDocs": { "description": "Reference documentation", "url": "https://docs.wordsmith.ai/api-reference/tasks/attach-files" }, "responses": { "200": { "description": "The updated task.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Task" } } } }, "400": { "description": "Bad request. See `error_code` for the specific cause.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, malformed or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The API key does not have permission to perform this action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The requested resource was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded. Honour the `Retry-After` header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "500": { "description": "Unexpected server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "task_id", "in": "path", "required": true, "description": "The task's unique identifier.", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "file_ids" ], "description": "Files to attach.", "properties": { "file_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "description": "File ids from the file upload endpoint." } } } } } } } }, "/tasks/{task_id}/files/{file_id}": { "delete": { "operationId": "removeTaskFile", "tags": [ "Tasks" ], "summary": "Detach a file from a task", "description": "Detaches the file from the task; the underlying file is not deleted. The file is addressed in the path because bodies on DELETE are unreliable through proxies.", "externalDocs": { "description": "Reference documentation", "url": "https://docs.wordsmith.ai/api-reference/tasks/remove-file" }, "responses": { "200": { "description": "The updated task.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Task" } } } }, "400": { "description": "Bad request. See `error_code` for the specific cause.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, malformed or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The API key does not have permission to perform this action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The requested resource was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded. Honour the `Retry-After` header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "500": { "description": "Unexpected server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "task_id", "in": "path", "required": true, "description": "The task's unique identifier.", "schema": { "type": "string", "format": "uuid" } }, { "name": "file_id", "in": "path", "required": true, "description": "File to detach.", "schema": { "type": "string", "format": "uuid" } } ] } }, "/tasks/{task_id}/links": { "post": { "operationId": "addTaskLinks", "tags": [ "Tasks" ], "summary": "Link items to a task", "description": "Links chats, reviews, reports or other tasks. Ids are prefixless, as everywhere in this API.", "externalDocs": { "description": "Reference documentation", "url": "https://docs.wordsmith.ai/api-reference/tasks/add-links" }, "responses": { "200": { "description": "The updated task.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Task" } } } }, "400": { "description": "Bad request. See `error_code` for the specific cause.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, malformed or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The API key does not have permission to perform this action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The requested resource was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded. Honour the `Retry-After` header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "500": { "description": "Unexpected server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "task_id", "in": "path", "required": true, "description": "The task's unique identifier.", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "linked_items" ], "description": "Items to link.", "properties": { "linked_items": { "type": "array", "minItems": 1, "items": { "$ref": "#/components/schemas/LinkedItem" }, "description": "The items to link. At least one." } } } } } } } }, "/tasks/{task_id}/links/{link_type}/{link_id}": { "delete": { "operationId": "removeTaskLink", "tags": [ "Tasks" ], "summary": "Unlink an item", "description": "Removes one link. The link is addressed by type and id in the path rather than a request body.", "externalDocs": { "description": "Reference documentation", "url": "https://docs.wordsmith.ai/api-reference/tasks/remove-link" }, "responses": { "200": { "description": "The updated task.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Task" } } } }, "400": { "description": "Bad request. See `error_code` for the specific cause.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, malformed or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The API key does not have permission to perform this action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The requested resource was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded. Honour the `Retry-After` header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "500": { "description": "Unexpected server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "task_id", "in": "path", "required": true, "description": "The task's unique identifier.", "schema": { "type": "string", "format": "uuid" } }, { "name": "link_type", "in": "path", "required": true, "description": "Kind of linked item.", "schema": { "type": "string", "enum": [ "chat", "review", "report", "task" ] } }, { "name": "link_id", "in": "path", "required": true, "description": "Identifier of the linked item.", "schema": { "type": "string", "format": "uuid" } } ] } }, "/tasks/{task_id}/follow": { "get": { "operationId": "getTaskFollowStatus", "tags": [ "Tasks" ], "summary": "Check follow status", "description": "Reports whether the authenticated user follows the task. Followers receive notifications when it changes.", "externalDocs": { "description": "Reference documentation", "url": "https://docs.wordsmith.ai/api-reference/tasks/get-follow" }, "responses": { "200": { "description": "Follow status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FollowStatus" } } } }, "400": { "description": "Bad request. See `error_code` for the specific cause.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, malformed or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The API key does not have permission to perform this action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The requested resource was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded. Honour the `Retry-After` header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "500": { "description": "Unexpected server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "task_id", "in": "path", "required": true, "description": "The task's unique identifier.", "schema": { "type": "string", "format": "uuid" } } ] }, "put": { "operationId": "followTask", "tags": [ "Tasks" ], "summary": "Follow a task", "description": "Follows the task. Idempotent — following an already-followed task succeeds.", "externalDocs": { "description": "Reference documentation", "url": "https://docs.wordsmith.ai/api-reference/tasks/follow-task" }, "responses": { "200": { "description": "Follow status after the call.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FollowStatus" } } } }, "400": { "description": "Bad request. See `error_code` for the specific cause.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, malformed or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The API key does not have permission to perform this action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The requested resource was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded. Honour the `Retry-After` header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "500": { "description": "Unexpected server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "task_id", "in": "path", "required": true, "description": "The task's unique identifier.", "schema": { "type": "string", "format": "uuid" } } ] }, "delete": { "operationId": "unfollowTask", "tags": [ "Tasks" ], "summary": "Unfollow a task", "description": "Stops following. Idempotent — unfollowing a task you do not follow succeeds.", "externalDocs": { "description": "Reference documentation", "url": "https://docs.wordsmith.ai/api-reference/tasks/unfollow-task" }, "responses": { "200": { "description": "Follow status after the call.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FollowStatus" } } } }, "400": { "description": "Bad request. See `error_code` for the specific cause.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, malformed or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The API key does not have permission to perform this action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The requested resource was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded. Honour the `Retry-After` header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "500": { "description": "Unexpected server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "task_id", "in": "path", "required": true, "description": "The task's unique identifier.", "schema": { "type": "string", "format": "uuid" } } ] } }, "/users": { "get": { "operationId": "listUsers", "tags": [ "Directory" ], "summary": "List people and agents", "description": "Lists the people and agents in your organisation. Use it to resolve the ids on a task, or to find someone to assign work to.", "externalDocs": { "description": "Reference documentation", "url": "https://docs.wordsmith.ai/api-reference/directory/list-users" }, "responses": { "200": { "description": "People and agents.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/DirectoryUser" } } } } }, "400": { "description": "Bad request. See `error_code` for the specific cause.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, malformed or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The API key does not have permission to perform this action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The requested resource was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded. Honour the `Retry-After` header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "500": { "description": "Unexpected server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "active_only", "in": "query", "required": false, "description": "`true` to exclude suspended accounts.", "schema": { "type": "string", "enum": [ "true", "false" ] } }, { "name": "human_only", "in": "query", "required": false, "description": "`true` to exclude agents.", "schema": { "type": "string", "enum": [ "true", "false" ] } } ] } }, "/teams": { "get": { "operationId": "listTeams", "tags": [ "Directory" ], "summary": "List teams", "description": "Lists the teams in your organisation. Team ids are what `assigned_team_id` and the sharing endpoints expect. Teams nest: `parent_team_id` is set on a sub-team, `member_count` counts the whole roster and `direct_member_count` only this team's own members.", "externalDocs": { "description": "Reference documentation", "url": "https://docs.wordsmith.ai/api-reference/directory/list-teams" }, "responses": { "200": { "description": "Teams.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Team" } } } } }, "400": { "description": "Bad request. See `error_code` for the specific cause.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, malformed or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The API key does not have permission to perform this action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The requested resource was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded. Honour the `Retry-After` header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "500": { "description": "Unexpected server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "description": "API key issued from the Wordsmith dashboard (https://app.wordsmith.ai), sent as `Authorization: Bearer sk-ws-api1-...`. Keys are organisation-wide; access is enforced per resource against the key's user." } }, "schemas": { "Error": { "type": "object", "description": "Standard error envelope returned by every 4xx and 5xx response.", "required": [ "error_code", "ws_api_error_code" ], "properties": { "error_code": { "type": "string", "description": "Machine-readable error identifier. Switch on this.", "enum": [ "unauthorized", "forbidden", "invalid_request_body", "bad_request", "invalid_upload_job", "unsupported_file_type", "session_still_processing", "resource_not_found", "rate_limit_exceeded", "insufficient_credits", "internal_error" ] }, "ws_api_error_code": { "type": "string", "description": "Legacy alias for `error_code`; always identical. New integrations should read `error_code`." }, "message": { "type": "string", "description": "Human-readable detail. Not present on every error." } } }, "RateLimitError": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "retry_after_seconds": { "type": "integer", "description": "Seconds to wait before retrying. Matches the `Retry-After` header." }, "limit": { "type": "integer", "description": "Maximum operations allowed in the window." }, "limit_window_seconds": { "type": "integer", "description": "Length of the window, in seconds." }, "next_tier_with_more_credits": { "type": [ "string", "null" ], "description": "Higher plan with more headroom, when one exists." } } } ], "description": "429 body. The request was rejected before any work started, so retrying is always safe." }, "User": { "type": "object", "description": "The authenticated user and their organisation.", "required": [ "user_id", "customer_id", "user_email", "customer_name" ], "properties": { "user_id": { "type": "string", "format": "uuid", "description": "Unique identifier for the user." }, "customer_id": { "type": "string", "format": "uuid", "description": "Unique identifier for the customer organisation." }, "user_name": { "type": [ "string", "null" ], "description": "Display name of the user. May be null." }, "user_email": { "type": "string", "format": "email", "description": "Email address of the user." }, "customer_name": { "type": "string", "description": "Name of the customer organisation." } } }, "Assistant": { "type": "object", "description": "A legal AI specialist configured with its own playbooks and templates.", "required": [ "id", "name" ], "properties": { "id": { "type": "string", "description": "Identifier to pass as `assistant_id`. Use `default` for the general assistant." }, "name": { "type": "string", "description": "Display name of the assistant." }, "description": { "type": [ "string", "null" ], "description": "What this assistant specialises in." } } }, "Playbook": { "type": "object", "description": "A structured document-review workflow.", "required": [ "id", "name" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "Identifier to reference in a question." }, "name": { "type": "string", "description": "Display name of the playbook." }, "description": { "type": [ "string", "null" ], "description": "What the playbook reviews. May be null." } } }, "Template": { "type": "object", "description": "A reusable document structure with placeholders to fill.", "required": [ "id", "name" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "Identifier to reference in a question." }, "name": { "type": "string", "description": "Display name of the template." }, "description": { "type": [ "string", "null" ], "description": "What the template produces. May be null." } } }, "QuestionAttachmentInput": { "type": "object", "description": "A file to attach to a question. Provide exactly one of `upload_job_id` or `url`.", "properties": { "upload_job_id": { "type": "string", "description": "`job_id` returned by POST /files/upload-url, after the file has been PUT to the presigned URL." }, "url": { "type": "string", "format": "uri", "description": "Publicly accessible URL Wordsmith should download the file from." }, "unzip": { "type": "boolean", "default": false, "description": "Extract ZIP archives and process the files inside." } }, "anyOf": [ { "required": [ "upload_job_id" ] }, { "required": [ "url" ] } ] }, "GeneratedAttachment": { "type": "object", "description": "A file produced by the assistant, e.g. a redline or summary.", "required": [ "url" ], "properties": { "file_name": { "type": [ "string", "null" ], "description": "Name of the generated file." }, "content_type": { "type": [ "string", "null" ], "description": "MIME type of the file." }, "content_length": { "type": [ "integer", "null" ], "description": "Size of the file in bytes." }, "url": { "type": "string", "format": "uri", "description": "Presigned download URL. Expires after 24 hours." } } }, "QuestionRequest": { "type": "object", "description": "A question for the assistant, optionally with documents and a delivery mode.", "required": [ "question" ], "properties": { "question": { "type": "string", "maxLength": 10000, "description": "The question to ask. Be specific; include the playbook or template name or id when you want one applied." }, "attachments": { "type": "array", "maxItems": 10, "items": { "$ref": "#/components/schemas/QuestionAttachmentInput" }, "description": "Up to 10 files, 50 MB each." }, "session_id": { "type": "string", "format": "uuid", "description": "Add this question to an existing session, preserving conversation context. Omit to start a new session." }, "permissions": { "type": "object", "description": "Visibility of the chat session this question creates.", "required": [ "visibility" ], "properties": { "visibility": { "type": "string", "enum": [ "private", "organization", "public" ], "description": "`private`: only you. `organization`: anyone in your organisation. `public`: anyone with the link." } } }, "callback_url": { "type": "string", "format": "uri", "description": "Webhook to POST to when async processing completes. Signed with the webhook secret set on the API key; the signature is in the `Wordsmith-Signature` header." }, "sync_mode": { "type": "boolean", "default": false, "description": "`true` waits for the full answer (30-second timeout). `false` returns immediately with a session id." } } }, "QuestionResponse": { "type": "object", "description": "The state of one question within a session.", "required": [ "id", "session_id", "status" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "Identifier of this specific question. Equals `session_id` for the first question in a session." }, "session_id": { "type": "string", "format": "uuid", "description": "Identifier of the conversation session. Constant across follow-ups." }, "session_url": { "type": "string", "format": "uri", "description": "Link to the session in the Wordsmith web app." }, "status": { "type": "string", "enum": [ "in_progress", "completed", "error" ], "description": "Processing state of the question." }, "answer": { "type": [ "string", "null" ], "description": "The assistant's answer. Present only when `status` is `completed`." }, "attachments": { "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/GeneratedAttachment" }, "description": "Files the assistant generated. Present only when `status` is `completed`." } } }, "UploadUrlRequest": { "type": "object", "required": [ "file_name", "content_type" ], "description": "Describes the file you are about to upload.", "properties": { "file_name": { "type": "string", "description": "File name including extension." }, "content_type": { "type": "string", "description": "MIME type, e.g. `application/pdf`. Must match the type used in the subsequent PUT." } } }, "UploadUrlResponse": { "type": "object", "required": [ "upload_url", "job_id", "content_type" ], "description": "Where to PUT the file, and the handle to attach it by.", "properties": { "upload_url": { "type": "string", "format": "uri", "description": "Presigned URL to PUT the file to. Expires after 1 hour." }, "job_id": { "type": "string", "format": "uuid", "description": "Pass as `upload_job_id` when attaching the file to a question." }, "content_type": { "type": "string", "description": "The MIME type that was requested." } } }, "TaskStatus": { "type": "string", "enum": [ "not_started", "in_progress", "waiting_on_external", "completed" ], "description": "Where the task is in its workflow." }, "TaskPriority": { "type": "string", "enum": [ "no_priority", "urgent", "high", "medium", "low" ], "description": "Task priority." }, "LinkedItem": { "type": "object", "required": [ "type", "id" ], "description": "A chat, review, report or task linked to this task.", "properties": { "type": { "type": "string", "enum": [ "chat", "review", "report", "task" ], "description": "Kind of linked item." }, "id": { "type": "string", "format": "uuid", "description": "Identifier of the linked item. Ids are prefixless throughout this API." } } }, "Task": { "type": "object", "description": "A unit of legal work, optionally assigned to a person, an agent or a team.", "required": [ "id", "title" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique identifier." }, "display_id": { "type": "string", "description": "Human-facing key shown in the Wordsmith UI." }, "title": { "type": "string", "description": "Short summary of the work." }, "description": { "type": [ "string", "null" ], "description": "Primary instruction for whoever picks the task up." }, "additional_context": { "type": [ "string", "null" ], "description": "Supplementary context. The description wins on conflict." }, "status": { "$ref": "#/components/schemas/TaskStatus" }, "priority": { "$ref": "#/components/schemas/TaskPriority" }, "assigned_to": { "type": [ "string", "null" ], "format": "uuid", "description": "Person responsible." }, "assigned_agent": { "type": [ "string", "null" ], "format": "uuid", "description": "Agent executing the task. Independent of `assigned_to`." }, "assigned_team_id": { "type": [ "string", "null" ], "format": "uuid", "description": "Team the task is assigned to." }, "parent_task_id": { "type": [ "string", "null" ], "format": "uuid", "description": "Parent task, when this is a subtask." }, "matter_id": { "type": [ "string", "null" ], "format": "uuid", "description": "Matter the task is filed under." }, "complete_by": { "type": [ "string", "null" ], "format": "date-time", "description": "Due date, ISO 8601." }, "tags": { "type": "array", "items": { "type": "string" }, "description": "Free-form labels." }, "linked_items": { "type": "array", "items": { "$ref": "#/components/schemas/LinkedItem" }, "description": "Linked chats, reviews, reports and tasks." }, "archived": { "type": "boolean", "description": "Shelved. Orthogonal to `status` — an archived task keeps its status." }, "draft": { "type": "boolean", "description": "Staged for review rather than committed. Accept with `draft: false`; reject by deleting." }, "created_at": { "type": "string", "format": "date-time", "description": "Creation timestamp." }, "updated_at": { "type": "string", "format": "date-time", "description": "Last modification timestamp." } } }, "TaskPage": { "type": "object", "required": [ "tasks" ], "description": "One cursor-paginated page of tasks.", "properties": { "tasks": { "type": "array", "items": { "$ref": "#/components/schemas/Task" }, "description": "Tasks in this page, ordered by priority, then due date, then most recently created." }, "cursor": { "type": [ "string", "null" ], "description": "Pass as `cursor` to fetch the next page. Null means the end. Keep `limit` constant across a walk." } } }, "TaskComment": { "type": "object", "required": [ "id", "content" ], "description": "An internal comment on a task, visible to people with access to the task.", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique identifier." }, "content": { "type": "string", "description": "Comment body." }, "author_id": { "type": [ "string", "null" ], "format": "uuid", "description": "Author of the comment." }, "parent_comment_id": { "type": [ "string", "null" ], "format": "uuid", "description": "Set when this comment is a reply." }, "file_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "description": "Attached files." }, "created_at": { "type": "string", "format": "date-time", "description": "Creation timestamp." } } }, "ThreadMessage": { "type": "object", "required": [ "id", "content", "direction" ], "description": "One message in the conversation with whoever requested the task.", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique identifier." }, "content": { "type": "string", "description": "Message body." }, "direction": { "type": "string", "enum": [ "inbound", "outbound" ], "description": "`inbound` from the requester, `outbound` a reply sent back to them." }, "created_at": { "type": "string", "format": "date-time", "description": "Timestamp." } } }, "TaskSharing": { "type": "object", "required": [ "visibility" ], "description": "Who can see and edit a task.", "properties": { "visibility": { "type": "string", "enum": [ "private", "customer" ], "description": "`private`: only the people and teams listed. `customer`: anyone in your organisation." }, "users": { "type": "array", "description": "People with explicit access.", "items": { "type": "object", "required": [ "id", "access_level" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "User id." }, "access_level": { "type": "string", "enum": [ "read", "write" ], "description": "Level of access granted." } } } }, "teams": { "type": "array", "description": "Teams with explicit access.", "items": { "type": "object", "required": [ "id", "access_level" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "Team id." }, "access_level": { "type": "string", "enum": [ "read", "write" ], "description": "Level of access granted." } } } } } }, "DirectoryUser": { "type": "object", "required": [ "id", "kind" ], "description": "A person or agent in the organisation.", "properties": { "id": { "type": "string", "format": "uuid", "description": "Identifier to use in `assigned_to` or `assigned_agent`." }, "name": { "type": [ "string", "null" ], "description": "Display name." }, "email": { "type": [ "string", "null" ], "format": "email", "description": "Email address. Null for agents." }, "kind": { "type": "string", "enum": [ "human", "agent" ], "description": "`agent` accounts can be assigned tasks via `assigned_agent`." }, "active": { "type": "boolean", "description": "False for suspended accounts." } } }, "Team": { "type": "object", "required": [ "id", "name" ], "description": "A team, as expected by `assigned_team_id` and the sharing endpoints.", "properties": { "id": { "type": "string", "format": "uuid", "description": "Team identifier." }, "name": { "type": "string", "description": "Team name." }, "parent_team_id": { "type": [ "string", "null" ], "format": "uuid", "description": "Set on a sub-team." }, "member_count": { "type": "integer", "description": "Whole roster, including sub-teams." }, "direct_member_count": { "type": "integer", "description": "Only this team's own members." } } }, "FollowStatus": { "type": "object", "required": [ "following" ], "description": "Whether the authenticated user follows the task.", "properties": { "following": { "type": "boolean", "description": "True when following. Followers receive the task's notifications." } } } } }, "webhooks": { "questionCompleted": { "post": { "operationId": "questionCompletedWebhook", "summary": "Async question completed", "description": "Sent to the `callback_url` supplied on an async question once processing finishes. Signed with the webhook secret set when the API key was created; the signature is in the `Wordsmith-Signature` header. Using webhooks removes polling from your rate-limit budget entirely.", "externalDocs": { "description": "Webhook reference", "url": "https://docs.wordsmith.ai/webhooks" }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QuestionResponse" } } } }, "responses": { "200": { "description": "Return 2xx to acknowledge receipt." } } } } } }