Add Check

Add a check to the end of a playbook.

POST /api/v1/playbooks/{playbook_id}/checks

cURL

curl -X POST "https://api.wordsmith.ai/api/v1/playbooks/3804d3f1-ba8c-4d5e-97f7-c16466d0ece9/checks" \
  -H "Authorization: Bearer sk-ws-api1-your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Non-solicitation",
    "instructions": "Check whether the agreement stops either party from hiring the staff of the other.",
    "severity": "low",
    "standard_position": "No non-solicitation clause."
  }'

Response

{
  "id": "a43c9368-519f-46f8-9dc3-7d76ab58837f",
  "name": "Non-solicitation",
  "instructions": "Check whether the agreement stops either party from hiring the staff of the other.",
  "severity": "low",
  "standard_position": "No non-solicitation clause.",
  "fallback_positions": []
}

Preview. This endpoint is available to organisations in the Wordsmith MCP pilot. Other organisations receive 403 mcp_not_enabled. See the preview overview.

Adds one check to a playbook. A check tells a review what to look for and which position you want the document to take. The new check goes to the end of the list, so reviews run it last.

Reviews that start after this call run the new check. Reviews already running or finished are not changed.

Fallback positions cannot be written through the API: fallback_positions comes back empty for a check you add. Negotiation playbooks built in the Wordsmith app keep their fallbacks, and Get Playbook returns them.

Authentication

Requires an API key, or an OAuth token with playbooks:write.

Path parameters

playbook_id · string · required

The playbook to add the check to.

Body parameters

name · string · required

A short label, such as Limitation of liability, up to 200 characters. Findings show it as check.name.

instructions · string · required

What the review should look for in the document.

severity · string · default: "medium"

high, medium or low. Sets the severity of a finding when the document misses the position.

standard_position · string

The position you want the document to take.

Response

Returns 201 with the new check.

cURL

curl -X POST "https://api.wordsmith.ai/api/v1/playbooks/3804d3f1-ba8c-4d5e-97f7-c16466d0ece9/checks" \
  -H "Authorization: Bearer sk-ws-api1-your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Non-solicitation",
    "instructions": "Check whether the agreement stops either party from hiring the staff of the other.",
    "severity": "low",
    "standard_position": "No non-solicitation clause."
  }'

Response

{
  "id": "a43c9368-519f-46f8-9dc3-7d76ab58837f",
  "name": "Non-solicitation",
  "instructions": "Check whether the agreement stops either party from hiring the staff of the other.",
  "severity": "low",
  "standard_position": "No non-solicitation clause.",
  "fallback_positions": []
}

Errors

Status	error_code	When
400	invalid_request_body	name or instructions is missing or empty, or severity is not high, medium or low.
403	forbidden	The caller can read the playbook but not edit it, or it is a global playbook.
404	resource_not_found	No playbook with this id, or the caller cannot read it.