Skip to main content
POST
Review a contract against a playbook

Authorizations

​
Authorization
string
header
required

Workspace credential issued from the automation console at /automation. Send it as Authorization: Bearer vq_ws_.... This is NOT a Data API key: a vq_key_ credential is refused here and names the other product in the error.

Headers

​
Idempotency-Key
string | null

A unique value of your choosing, so a retried launch returns the FIRST operation instead of starting a second billable job. Reusing one with a different body is refused. Retrying with the same key and the same body is free and is the intended way to recover from a timeout.

Path Parameters

​
matterId
string
required

mat_ identifier of the matter to work inside. Everything in this API hangs off a matter, and the matter in the path is what the authorization boundary is checked against. Take it from GET /v1/matters.

Body

application/json

Start a review of one contract against one playbook.

contractType and userSide are the internal enums by REFERENCE rather than by copy. They are the taxonomy the whole product is built on, guarded in both directions by app/tests/unit/test_contract_type_taxonomy.py, and a second hand-maintained copy here would be a fourth layer for that guard to police. Widening the taxonomy widens this API additively, which is correct.

​
documentText
string
required

The full contract text to review, 100 to 200,000 characters. Text rather than a document id: a review reads one contract end to end and the caller usually has it in hand.

Required string length: 100 - 200000
Example:

"MASTER SERVICES AGREEMENT\n\nThis Master Services Agreement is entered into as of 1 September 2026 between Acme Corporation, a Delaware corporation, and the Supplier identified on the signature page.\n\n8. LIMITATION OF LIABILITY. Supplier's total liability shall be unlimited for any claim arising out of this Agreement.\n\n12. GOVERNING LAW. This Agreement is governed by the laws of the State of Delaware."

​
contractType
enum<string>
required

What kind of contract this is. Determines which playbook and which default positions resolve.

Available options:
saas,
professional_services,
msa,
sow,
consulting,
license,
sale,
partnership,
procurement,
vendor_agreement,
reseller_distribution,
supply,
lease,
loan,
eula,
terms_of_service,
baa,
order_form,
nda,
dpa,
ip_assignment,
employment,
executive_employment,
independent_contractor,
offer_letter,
severance_agreement,
non_compete,
asset_purchase,
stock_purchase,
merger_agreement,
shareholders_agreement,
operating_agreement,
safe,
term_sheet,
settlement_agreement,
engagement_letter,
protective_order,
joint_defense,
other
Example:

"saas"

​
userSide
enum<string>
required

Which side of the deal you are on. The review argues for this side.

Available options:
vendor,
customer,
licensor,
licensee,
partner,
supplier,
reseller,
employer,
employee,
buyer,
seller,
company,
investor,
lender,
borrower,
disclosing_party,
receiving_party,
plaintiff,
defendant,
other
Example:

"vendor"

​
playbookId
string | null

pbk_ identifier of the playbook to review against. Omit to run against the built-in default positions for jurisdiction, which is a real answer rather than a degraded one.

Example:

"pbk_9f2c8b1e4a7d43c9b6e0f1a2c3d4e5f6"

​
jurisdiction
string
default:US

Two-letter uppercase jurisdiction code, or INTL. Selects the default positions when no playbook is named.

Pattern: ^([A-Z]{2}|INTL)$
Example:

"US"

​
focusAreas
string[] | null

Narrow the review to these areas of concern. Omit to review the whole contract.

Maximum array length: 50
Required string length: 1 - 80
Example:
​
reviewInstructions
string | null

Extra instructions for this review only, layered on top of the playbook.

Maximum string length: 2000
Example:

"Pay particular attention to the indemnity carve-outs."

​
markupLevel
enum<string>
default:standard

How aggressively to mark up. light flags only escalation triggers, standard marks up gaps to the preferred position, firm hard-lines every deviation.

Available options:
light,
standard,
firm
Example:

"light"

​
paperSide
enum<string> | null

Whose paper this is. own defends your drafted positions; counterparty marks up their form assertively. Orthogonal to userSide. Omit if unknown, which costs only prompt specificity.

Available options:
own,
counterparty
Example:

"own"

​
round
integer
default:1

Negotiation round. 2 and above tells the reviewer the counterparty has already responded, so it proposes minimal edits toward the fallback rather than restating the preferred position.

Required range: 1 <= x <= 10
Example:

1

​
priorRoundText
string | null

Your last sent version, at round 2 and above, so the reviewer can compute a real diff instead of guessing what changed and undoing settled language.

Maximum string length: 200000
Example:

"8. LIMITATION OF LIABILITY. Supplier's total liability shall not exceed the fees paid in the preceding twelve months."

​
counterpartyResponseText
string | null

The counterparty's response, when it differs from documentText. Most callers paste the response straight into documentText, in which case leave this out.

Maximum string length: 200000
Example:

"8. LIMITATION OF LIABILITY. Supplier's total liability shall not exceed three times the fees paid in the preceding twelve months."

​
dealContext
ReviewDealContext · object | null

Deal attributes the playbook's conditional escalation rules evaluate.

​
depth
enum<string>
default:standard

standard runs the first-pass review. deep additionally re-drafts every flagged clause with the deep model, grounds each quote against the contract, drops first-pass false positives and stamps a sign-off level, so each redline's grounding is a fact rather than a default. It takes several times as long and verifies at most 40 flagged clauses. focusAreas, reviewInstructions, markupLevel, round, priorRoundText and counterpartyResponseText are not supported at this depth and are refused rather than ignored.

Available options:
standard,
deep
Example:

"standard"

Response

Successful Response

One long-running operation, whatever kind of work it is.

Readable for OPERATION_RETENTION_DAYS after creation, per AIP-151.

​
id
string
required

Public identifier, op_ followed by 32 hex characters. Poll GET /v1/operations/{operationId} with it.

Example:

"op_9f2c8b1e4a7d43c9b6e0f1a2c3d4e5f6"

​
type
string
required

What kind of work this is, for example matrix.run or draft.generate.

Example:

"matrix.run"

​
status
enum<string>
required

One of five values: queued, running, succeeded, failed, cancelled. There is no sixth and there are no synonyms. Stop polling once it is succeeded, failed or cancelled.

Available options:
queued,
running,
succeeded,
failed,
cancelled
Example:

"succeeded"

​
createdAt
string<date-time>
required

When the operation was accepted (RFC 3339).

Example:

"2026-08-19T14:32:10Z"

​
completedAt
string<date-time> | null

When the operation reached a terminal status (RFC 3339). Present if and only if the status is terminal.

Example:

"2026-08-19T14:32:10Z"

​
matterId
string | null

mat_ identifier of the matter this work belongs to, when it belongs to one.

Example:

"mat_9f2c8b1e4a7d43c9b6e0f1a2c3d4e5f6"

​
resource
OperationResource · object | null

What the operation produced. Absent until the underlying job row exists, which an idempotent replay can briefly observe, so treat absence as 'not yet' rather than 'never'.

​
error
OperationError · object | null

Why the work failed. Present only when status is failed. Partial success is succeeded with progress.done < progress.total, never an error.

​
progress
OperationProgress · object | null

How far along the work is, when the underlying job reports it. Absent does not mean no progress.

​
requestId
string | null

The X-Request-ID of the request that created this operation. Quote it in a support ticket.

Example:

"req_5f2c8b1e4a7d43c9b6e0f1a2c3d4e5f6"

Last modified on August 23, 2026