Clment Jobs API
Poll the status of long-running upload / review / redline jobs.
Poll the status of long-running upload / review / redline jobs.
Every API here is available over the APIs.io API and to AI agents over MCP.
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.curl "https://apis.io/api/v1/apis/clment-com:clment-com-jobs-api"
curl "https://apis.io/api/v1/apis?limit=25"
Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
openapi: 3.2.0
info:
title: Clment REST Jobs API
version: 1.0.0
termsOfService: https://clment.com/terms-of-service
contact:
name: Clment developer support
url: https://clment.com/developers
description: 'The Clment REST API gives your services programmatic access to the
same contract workspace you use in the app — contracts, AI reviews,
rulebooks, key dates, and search. ## Authentication
Every request carries a bearer token in the `Authorization` header:
```
Authorization: Bearer clm_REDACTED_STRIPE_KEY
```
Generate a key in the app under **Settings → API & Integrations →
API keys**. The secret is shown **once** at creation — store it in a
secret manager. A key is scoped to the organization it was created
in and inherits that workspace''s data residency region. ## What a key can and can''t do
An API key can read and write everything a member can in the app:
upload contracts, run reviews, edit rulebooks, manage key dates,
search. It **cannot** touch settings — billing, members, SSO,
integrations, organization config, or webhook subscriptions. Those
require a human admin signed in to the app. ## Regions & base URL
Use your organization''s home region''s base URL. A key only works
against the region it belongs to — calling another region returns
401. (This is the same list as the **Servers** dropdown above; both
are generated from our live region catalog.)
| Region | Base URL |
|----------------|--------------------------------|
| United States | `https://api-us.clment.com/v1` |
| European Union | `https://api-eu.clment.com/v1` |
| Australia | `https://api-au.clment.com/v1` |
| New Zealand | `https://api-nz.clment.com/v1` |
| United Kingdom | `https://api-uk.clment.com/v1` |
| Canada | `https://api-ca.clment.com/v1` |
## Response envelope
Successful responses wrap their payload in a `data` object:
```json
{ "data": { "contract": { "id": "…" } } }
```
Errors return an `error` object with a stable machine-readable
`code` and a human `message`:
```json
{ "error": { "code": "NOT_FOUND", "message": "Contract not found" } }
```
## Pagination
List endpoints page with `skip` and `take` (max 100). The response
carries the page plus a `total` count so you can compute whether
more pages remain. ## Long-running operations (jobs)
Uploads, reviews, and redlines run as background jobs. The kick-off
endpoint returns a **job id** immediately; poll the matching job
endpoint until it reports `complete`, then fetch the result. | Action | Start | Poll | Result |
|--------|-------|------|--------|
| Upload | `POST /contracts/upload` | `GET /contracts/upload/jobs/{jobId}` | `GET /contracts/{id}` |
| Review | `POST /contracts/{id}/review` | `GET /jobs/review/{id}` | `GET /reviews/{reviewId}` |
| Redline | `POST /contracts/{id}/generate-redline` | `GET /jobs/redline/{id}` | `GET /contracts/download/{token}` |
An API key always gets the job id back as JSON — the live
Server-Sent Events variant of the review and redline start
endpoints belongs to first-party app sessions. Polling is the
right shape for a server-to-server integration anyway: simpler
than holding a stream open, and it survives the process that
started the job going away. ## Rate limits & credits
Two independent limits apply:
- **Credits.** AI operations (reviews, redlines, conversions) consume
credits from your plan''s monthly allowance, then any credit packs. Read operations are free. A `402 INSUFFICIENT_CREDITS` indicates an
exhausted balance. - **Request rate.** Requests are rate-limited per organization on a
rolling hourly window sized to your plan. Every AUTHENTICATED
response carries `X-RateLimit-Limit` and `X-RateLimit-Remaining`
(the limiter is per-organization, so it runs only once the key has
resolved to one — a 401 carries neither); exceed the window
and you get a `429 RATE_LIMITED` with a `Retry-After` header (in
seconds) — back off for that long, then retry. ## Plan & access
The API is available on the **Business** and **Enterprise** plans. A
call from an org without API access returns `403 API_ACCESS_NOT_IN_PLAN`;
a call from an org whose subscription has lapsed returns
`403 SUBSCRIPTION_SUSPENDED`.'
servers:
- url: https://api-us.clment.com/v1
description: United States
- url: https://api-eu.clment.com/v1
description: European Union
- url: https://api-au.clment.com/v1
description: Australia
- url: https://api-nz.clment.com/v1
description: New Zealand
- url: https://api-uk.clment.com/v1
description: United Kingdom
- url: https://api-ca.clment.com/v1
description: Canada
security:
- bearerAuth: []
tags:
- name: Jobs
description: Poll the status of long-running upload / review / redline jobs.
paths:
/jobs/review/{id}:
get:
tags:
- Jobs
operationId: getReviewJob
summary: Get review job status
description: 'Poll a review job started by `POST /contracts/{id}/review`. When
`status` is `complete`, `reviewId` points at the produced review
(fetch it with `GET /reviews/{reviewId}`).'
parameters:
- name: id
in: path
required: true
schema:
type: string
description: The review job id.
responses:
'200':
description: Job status.
content:
application/json:
schema:
type: object
properties:
data:
type: object
properties:
status:
$ref: '#/components/schemas/JobStatus'
reviewId:
type:
- string
- 'null'
description: The review this job produced. Explicitly null until `status` is `complete`, not absent — the route lifts it with `?? null` so a poller can read one shape throughout.
error:
type: string
description: Present when `status` is `error`.
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'429':
$ref: '#/components/responses/TooManyRequests'
'404':
$ref: '#/components/responses/NotFound'
/jobs/redline/{id}:
get:
tags:
- Jobs
operationId: getRedlineJob
summary: Get redline job status
description: 'Poll a redline job started by
`POST /contracts/{id}/generate-redline`. When `status` is
`complete`, download the DOCX from
`GET /contracts/download/{token}` using this job id as the token.'
parameters:
- name: id
in: path
required: true
schema:
type: string
description: The redline job id (also the download token).
responses:
'200':
description: Job status.
content:
application/json:
schema:
type: object
properties:
data:
type: object
properties:
status:
$ref: '#/components/schemas/JobStatus'
versionId:
type:
- string
- 'null'
description: The saved redline version, once complete.
appliedCount:
type:
- integer
- 'null'
description: Number of findings applied as tracked changes. Null until the job completes.
error:
type:
- string
- 'null'
description: Present when `status` is `error`.
result:
type:
- object
- 'null'
description: 'Populated once the job finishes. **Check `result.outcome.ok` before downloading.** A job can reach `status: complete` having produced nothing to download — the model may propose no change that survives validation, which is a normal outcome on a document that already meets the rulebook. In that case `GET /contracts/download/{token}` returns 404, and this object is the only place that says why.'
properties:
outcome:
type: object
properties:
ok:
type: boolean
description: True when a document was produced and is downloadable. False when nothing was.
summary:
type: string
description: Plain-language account of what the redline did, or why it did nothing.
appliedCount:
type: integer
description: Changes actually written into the document. Can be 0 on a successful redline whose changes were all comments.
totalChanges:
type: integer
description: Changes the model proposed, before validation.
noChanges:
type: boolean
description: True when `ok` is false because nothing was proposed that survived validation — an informational result, not a failure.
error:
type: string
description: Present when `ok` is false and the cause was a fault rather than an empty result.
step:
type: string
enum:
- convert
- generate
- apply
description: Which stage produced the failure, when one did.
skipped:
type: array
description: 'Proposed CHANGES that did not make it into the document, each with the reason. Note the unit: these are edits the model proposed, not findings — a finding has no skipped state (its status is pass, fail, warning or not_applicable). One finding can produce several changes, or none.
This is what lets a client say "1 of 5 changes was not applied, because the clause it targeted was not found" instead of showing a bare count.'
items:
type: object
properties:
findingId:
type: string
description: The finding this change came from, when the proposal carried one. Use it to attribute a skipped change back to the finding a reader already knows about.
section:
type: string
description: The clause or section the change was proposed against. For `no_change_generated` this is the finding's title instead.
rationale:
type: string
description: Why the model thought the change mattered. For `no_change_generated` this is the finding's note instead.
originalSnippet:
type: string
description: The first ~120 characters of the verbatim text the change tried to anchor on. The practical way to see why an anchor failed.
reason:
type: string
description: 'Why it was not applied. Branch on this rather than on the prose above: `no_change_generated` means the model produced nothing for that finding, which is an outcome rather than a fault. The other five are anchoring or application failures.'
enum:
- no_change_generated
- no_original_text
- original_not_found_in_document
- apply_step_failed
- conflicted_with_applied_change
- pure_renumbering_stripped
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'429':
$ref: '#/components/responses/TooManyRequests'
'404':
$ref: '#/components/responses/NotFound'
components:
responses:
Unauthorized:
description: Missing, malformed, revoked, or wrong-region key.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
unauthorized:
value:
error:
code: UNAUTHORIZED
message: Invalid API key
NotFound:
description: The resource doesn't exist in this organization.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
notFound:
value:
error:
code: NOT_FOUND
message: Contract not found
Forbidden:
description: "The request isn't allowed — one of three cases, told apart by the\nerror `code`:\n - `API_ACCESS_NOT_IN_PLAN` — the API is a Business / Enterprise\n feature and this organization isn't on a qualifying plan.\n - `SUBSCRIPTION_SUSPENDED` — the org's subscription has lapsed;\n API access is paused until billing is resolved.\n - `API_KEY_FORBIDDEN` — an API key tried to reach a settings\n surface (billing, members, SSO, integrations, org config,\n webhooks); those require a human admin signed in to the app.\n"
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
notInPlan:
value:
error:
code: API_ACCESS_NOT_IN_PLAN
message: The Clment API is available on the Business and Enterprise plans.
suspended:
value:
error:
code: SUBSCRIPTION_SUSPENDED
message: API access requires an active subscription.
settingsBlocked:
value:
error:
code: API_KEY_FORBIDDEN
message: API keys cannot access settings
TooManyRequests:
description: 'The per-organization request rate limit was exceeded. Wait the
number of seconds in the `Retry-After` header, then retry. Every
authenticated response (not just this one) carries
`X-RateLimit-Limit` and `X-RateLimit-Remaining` so you can pace
yourself before hitting it.
'
headers:
Retry-After:
description: Seconds to wait before retrying.
schema:
type: integer
X-RateLimit-Limit:
description: Requests allowed per window.
schema:
type: integer
X-RateLimit-Remaining:
description: Requests remaining in the current window.
schema:
type: integer
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
rateLimited:
value:
error:
code: RATE_LIMITED
message: Too many requests. Please try again in a few minutes.
schemas:
Error:
type: object
required:
- error
properties:
error:
type: object
required:
- code
- message
properties:
code:
type: string
description: Stable machine-readable error code.
message:
type: string
description: Human-readable explanation.
JobStatus:
type: string
description: Lifecycle of a background job. `complete` means the job finished, NOT that it produced a downloadable artefact — a redline can complete having applied no changes.
enum:
- queued
- processing
- complete
- failed
securitySchemes:
bearerAuth:
type: http
scheme: bearer
bearerFormat: clm_sk_live_*
description: 'A Clment API key. Format `clm_sk_live_` followed by a
URL-safe-base64 random string. Created in **Settings → API &
Integrations**.
'