Common API workflows

This guide walks the full contract lifecycle through the REST API, the same flow the app and the MCP server drive. For the endpoint-by-endpoint reference, see the API reference; to authenticate, start with getting started.

Throughout, $KEY is your API key and $BASE is your region’s base URL (e.g. https://us.clment.com/v1).

How long-running work behaves

Uploads, reviews, and redlines run as background jobs. The start endpoint returns a jobId immediately; you poll a job endpoint until status is complete, then fetch the result. Each follows the same three-step shape:

Upload

1. Start — POST /contracts/upload
2. Poll — GET /contracts/upload/jobs/{jobId}
3. Result — GET /contracts/{id}

Review

1. Start — POST /contracts/{id}/review
2. Poll — GET /jobs/review/{id}
3. Result — GET /reviews/{reviewId}

Redline

1. Start — POST /contracts/{id}/generate-redline
2. Poll — GET /jobs/redline/{id}
3. Result — GET /contracts/download/{token}

(The review and redline endpoints can also stream live progress over Server-Sent Events if you send Accept: text/event-stream. For server-to-server work, skip that and poll — it’s simpler and survives dropped connections.)

1. Upload a contract

Upload the file’s bytes as multipart/form-data. Files are capped at 100 MB; PDF and DOCX are supported.

curl -X POST "$BASE/contracts/upload" \
  -H "Authorization: Bearer $KEY" \
  -F "file=@./acme-msa.pdf"
# → { "data": { "jobId": "job_abc…" } }

Poll until the upload finishes, then read the contract:

curl "$BASE/contracts/upload/jobs/job_abc…" -H "Authorization: Bearer $KEY"
# → { "data": { "status": "complete", "contractId": "c_123…" } }

curl "$BASE/contracts/c_123…" -H "Authorization: Bearer $KEY"

Already have the document at a public URL? Use POST /contracts/from-url with { "url": "…" } instead — same job lifecycle.

Re-uploads: attach as a new version

A DOCX you previously downloaded or redlined from Clment carries an embedded document id. On upload we detect it and report any match in the response (matchedContractId). To file the re-upload as a new version of that contract instead of creating a duplicate — the same thing the app offers when it recognises a document — pass onEmbeddedMatch:

curl -X POST "$BASE/contracts/upload" \
  -H "Authorization: Bearer $KEY" \
  -F "file=@./acme-msa-v2.docx" \
  -F "onEmbeddedMatch=auto"
# matched  → 200 { "data": { "attached": true, "contractId": "c_123…", "version": { "versionNumber": 2, … } } }
# no match → 202 { "data": { "jobId": "…" } }   (filed as a new contract)

• new (default) — always create a new contract; the match is still reported.
• attach — attach as a version; 422 if nothing matched.
• auto — attach if matched, otherwise create a new contract.

2. Run an AI review

Pick a playbook (GET /playbooks) and start a review. Omit the SSE header to get a job id back. The optional reviewStrategy sets how assertive the review is and what lands in the redline — see Choosing a review strategy.

curl -X POST "$BASE/contracts/c_123…/review" \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d '{ "playbookId": "pb_2e…", "mode": "standard", "reviewStrategy": "negotiation" }'
# → { "data": { "jobId": "rev_job_…" } }

curl "$BASE/jobs/review/rev_job_…" -H "Authorization: Bearer $KEY"
# → { "data": { "status": "complete", "reviewId": "rev_9d…" } }

Reviews consume credits on success (deep mode costs more than standard; both scale with page count). reviewStrategy is one of explore, negotiation, high_priority, or strict; omit it to use the playbook’s default (or explore).

3. Read findings and apply decisions

Fetch the review to see each finding, its AI recommendation, and whether it’s flagged for the redline:

curl "$BASE/reviews/rev_9d…" -H "Authorization: Bearer $KEY"

Record your verdict on a finding. This is the REST equivalent of the MCP set_finding_decision skill — four independent controls; send only what you’re changing:

curl -X PATCH "$BASE/reviews/rev_9d…/findings/fnd_3a…" \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "humanDecision": "disagree",
        "humanNote": "Cap is below our policy floor — push back.",
        "suggestedLanguage": "Liability shall not exceed 12 months of fees.",
        "includeInRedline": true
      }'

• humanDecision — agree / partial / disagree (or null to clear).
• humanNote — free text (≤ 5000 chars), may contain @mentions.
• suggestedLanguage — replacement clause text (≤ 10000 chars).
• includeInRedline — true/false to force in or out of the redline; null resets to the recommendation-derived default.

4. Generate a redline

Pass the findings you want applied (typically those with includeInRedline: true). Returns a job; download the DOCX once it’s done.

curl -X POST "$BASE/contracts/c_123…/generate-redline" \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d '{ "playbookName": "Standard SaaS — Buy-side", "sourceReviewId": "rev_9d…", "findings": [ … ] }'
# → { "data": { "jobId": "rl_job_…" } }

curl "$BASE/jobs/redline/rl_job_…" -H "Authorization: Bearer $KEY"
# → { "data": { "status": "complete", "appliedCount": 11 } }

# The job id is the download token:
curl "$BASE/contracts/download/rl_job_…" -H "Authorization: Bearer $KEY" -o acme-redline.docx

5. Download the review report

A formatted Word report of the whole review — summary, findings, recommendations, and your verdicts:

curl "$BASE/reviews/rev_9d…/report.docx" -H "Authorization: Bearer $KEY" -o acme-review.docx

Unlike MCP — where an agent follows a bare link with no auth header and therefore needs a signed one-time download token — the REST API authenticates every request with your key, so report and redline downloads are just ordinary authenticated GETs.

6. Sign it off

When the human review is done, record a sign-off. The first sign-off marks the review completed and fires the review.completed webhook:

curl -X POST "$BASE/reviews/rev_9d…/complete" -H "Authorization: Bearer $KEY"

Utility: convert a PDF to Word (no contract)

Need a one-off Word copy of a PDF that isn’t a contract? Conversion is powered by Adobe PDF Services, so layout, tables, and styles carry over into a high-fidelity .docx. Two ways, both returning a short-lived download token — no contract or version is created.

Upload the file (multipart/form-data, ≤ 100 MB):

curl -X POST "$BASE/convert/pdf-to-word" \
  -H "Authorization: Bearer $KEY" \
  -F "file=@./doc.pdf"
# → { "data": { "downloadToken": "tok_…", "expiresAt": "…", "pages": 12, "creditsCharged": 5 } }

curl "$BASE/contracts/download/tok_…" -H "Authorization: Bearer $KEY" -o doc.docx

Or point at a URL (POST /convert/pdf-url-to-word, ≤ 50 MB fetched server-side):

curl -X POST "$BASE/convert/pdf-url-to-word" \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d '{ "pdfUrl": "https://example.com/doc.pdf" }'

Charged per 50-page block (5 credits per block); re-converting identical bytes is free (cached). To convert a PDF that’s already a contract version and keep the result on the contract, use POST /contracts/{id}/versions/{versionId}/convert-to-word instead.