Submit Decisions

curl -X POST "https://api.wordsmith.ai/api/v1/reviews/d87cb8f9-a92d-4955-881d-2386545cb19f/decisions" \
  -H "Authorization: Bearer sk-ws-api1-your_api_key_here" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 1e6a4c8b-3f7d-4b29-8a51-d0c9e2b7f346" \
  -d '{
    "decisions": [
      {
        "finding_id": "2c0afcb9-8d68-4340-87ca-ed6dd5ddc60e",
        "decision": "counter",
        "counter_text": "within 45 days of receipt"
      },
      {
        "finding_id": "1bce01c3-11ff-4a9e-8244-9816386908d8",
        "decision": "accept"
      },
      {
        "finding_id": "6deae027-f536-4a0d-95a1-e1084c54f524",
        "decision": "reject"
      }
    ]
  }'

{
  "id": "4ae0de09-7ef8-4dcf-941a-b4d038009288",
  "type": "review_decisions",
  "status": "running",
  "progress": { "stage": "apply", "completed": 0, "total": 3 },
  "resource": { "type": "review", "id": "d87cb8f9-a92d-4955-881d-2386545cb19f" },
  "result": null,
  "error": null,
  "poll_after_seconds": 5,
  "created_at": "2026-10-13T10:20:00Z",
  "updated_at": "2026-10-13T10:20:01Z",
  "completed_at": null
}

{
  "id": "4ae0de09-7ef8-4dcf-941a-b4d038009288",
  "type": "review_decisions",
  "status": "succeeded",
  "progress": { "stage": "apply", "completed": 3, "total": 3 },
  "resource": { "type": "review", "id": "d87cb8f9-a92d-4955-881d-2386545cb19f" },
  "result": { "file_id": "e04f8d68-60d7-40bd-bce1-7edebdd2a4aa" },
  "error": null,
  "poll_after_seconds": null,
  "created_at": "2026-10-13T10:20:00Z",
  "updated_at": "2026-10-13T10:24:18Z",
  "completed_at": "2026-10-13T10:24:18Z"
}

curl -X POST "https://api.wordsmith.ai/api/v1/reviews/d87cb8f9-a92d-4955-881d-2386545cb19f/decisions" \
  -H "Authorization: Bearer sk-ws-api1-your_api_key_here" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 1e6a4c8b-3f7d-4b29-8a51-d0c9e2b7f346" \
  -d '{
    "decisions": [
      {
        "finding_id": "2c0afcb9-8d68-4340-87ca-ed6dd5ddc60e",
        "decision": "counter",
        "counter_text": "within 45 days of receipt"
      },
      {
        "finding_id": "1bce01c3-11ff-4a9e-8244-9816386908d8",
        "decision": "accept"
      },
      {
        "finding_id": "6deae027-f536-4a0d-95a1-e1084c54f524",
        "decision": "reject"
      }
    ]
  }'

{
  "id": "4ae0de09-7ef8-4dcf-941a-b4d038009288",
  "type": "review_decisions",
  "status": "running",
  "progress": { "stage": "apply", "completed": 0, "total": 3 },
  "resource": { "type": "review", "id": "d87cb8f9-a92d-4955-881d-2386545cb19f" },
  "result": null,
  "error": null,
  "poll_after_seconds": 5,
  "created_at": "2026-10-13T10:20:00Z",
  "updated_at": "2026-10-13T10:20:01Z",
  "completed_at": null
}

{
  "id": "4ae0de09-7ef8-4dcf-941a-b4d038009288",
  "type": "review_decisions",
  "status": "succeeded",
  "progress": { "stage": "apply", "completed": 3, "total": 3 },
  "resource": { "type": "review", "id": "d87cb8f9-a92d-4955-881d-2386545cb19f" },
  "result": { "file_id": "e04f8d68-60d7-40bd-bce1-7edebdd2a4aa" },
  "error": null,
  "poll_after_seconds": null,
  "created_at": "2026-10-13T10:20:00Z",
  "updated_at": "2026-10-13T10:24:18Z",
  "completed_at": "2026-10-13T10:24:18Z"
}

Proposed — not available yet. This endpoint is part of a design under review.

Records your decision on each of the counterparty’s tracked changes, then writes them into a response draft. It works only on counterparty_edits reviews. Each finding in such a review is one tracked change. Read them, with Wordsmith’s recommendation, through List Findings. The response draft is a new DOCX:

An accepted change is applied and no longer tracked.
A rejected change is reverted.
A countered change is reverted and replaced by your counter_text, as a new tracked change.
A finding without a decision stays as the counterparty’s tracked change, for you to settle in Word.

Applying decisions runs as an operation. See Long-running operations.

Authentication

Requires an API key, or an OAuth token with reviews:write and files:read.

Path parameters

string

required

The id of a counterparty_edits review. The review must be completed.

Headers

string

A unique key for this request, such as a UUID. A repeat with the same key within 30 days returns the same operation and makes no second draft.

Body parameters

object[]

required

One entry per finding you are deciding. You can send decisions over several calls. A later decision on the same finding replaces the earlier one.

Show properties

string

required

A finding of this review.

string

required

accept, reject or counter.

string

The wording you propose instead. Required when decision is counter, and rejected otherwise.

boolean

default:"true"

Produce the response draft from every decision recorded so far. With false, the decisions are saved and no draft is made. The operation then comes back already succeeded, with file_id: null.

integer

default:"0"

Seconds to wait for the draft before responding, from 0 to 20.

string

An HTTPS URL that receives a signed operation.succeeded, operation.failed or operation.cancelled event when the draft is ready.

Response

Returns 202 with an operation of type review_decisions. Its resource is the review. A repeat with the same Idempotency-Key returns 200 with the same operation. When status is succeeded, result is { "file_id" }: the response draft. The review’s response_file_id is set to the same id, and each decided finding’s decision is filled in.

curl -X POST "https://api.wordsmith.ai/api/v1/reviews/d87cb8f9-a92d-4955-881d-2386545cb19f/decisions" \
  -H "Authorization: Bearer sk-ws-api1-your_api_key_here" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 1e6a4c8b-3f7d-4b29-8a51-d0c9e2b7f346" \
  -d '{
    "decisions": [
      {
        "finding_id": "2c0afcb9-8d68-4340-87ca-ed6dd5ddc60e",
        "decision": "counter",
        "counter_text": "within 45 days of receipt"
      },
      {
        "finding_id": "1bce01c3-11ff-4a9e-8244-9816386908d8",
        "decision": "accept"
      },
      {
        "finding_id": "6deae027-f536-4a0d-95a1-e1084c54f524",
        "decision": "reject"
      }
    ]
  }'

{
  "id": "4ae0de09-7ef8-4dcf-941a-b4d038009288",
  "type": "review_decisions",
  "status": "running",
  "progress": { "stage": "apply", "completed": 0, "total": 3 },
  "resource": { "type": "review", "id": "d87cb8f9-a92d-4955-881d-2386545cb19f" },
  "result": null,
  "error": null,
  "poll_after_seconds": 5,
  "created_at": "2026-10-13T10:20:00Z",
  "updated_at": "2026-10-13T10:20:01Z",
  "completed_at": null
}

{
  "id": "4ae0de09-7ef8-4dcf-941a-b4d038009288",
  "type": "review_decisions",
  "status": "succeeded",
  "progress": { "stage": "apply", "completed": 3, "total": 3 },
  "resource": { "type": "review", "id": "d87cb8f9-a92d-4955-881d-2386545cb19f" },
  "result": { "file_id": "e04f8d68-60d7-40bd-bce1-7edebdd2a4aa" },
  "error": null,
  "poll_after_seconds": null,
  "created_at": "2026-10-13T10:20:00Z",
  "updated_at": "2026-10-13T10:24:18Z",
  "completed_at": "2026-10-13T10:24:18Z"
}

Errors

Status	`error_code`	When
400	`invalid_request_body`	`decisions` is empty, a `decision` is not allowed, or `counter_text` is missing for `counter` or set for another decision.
400	`unknown_finding`	A `finding_id` does not belong to this review.
402	`insufficient_credits`	Your account does not have enough credits to apply the decisions.
404	`resource_not_found`	No review with this id, or the caller cannot read it.
409	`unsupported_review_type`	The review is not a `counterparty_edits` review. Use Generate Redline for the others.
409	`review_not_completed`	The review is still running, or it failed or was cancelled.
409	`idempotency_key_reused`	The `Idempotency-Key` was used within 30 days with a different body.

Proposal

MCP server

Reviews

Authentication

Path parameters

Headers

Body parameters

Response

Errors

​Authentication

​Path parameters

​Headers

​Body parameters

​Response

​Errors

Authentication

Path parameters

Headers

Body parameters

Response

Errors