Clment Search API
Natural-language and filtered search across contracts.
Natural-language and filtered search across contracts.
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-search-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 Search 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: Search
description: Natural-language and filtered search across contracts.
paths:
/ask:
post:
tags:
- Search
operationId: askQuestion
summary: Ask a question across your contracts
description: 'A natural-language answer drawn from the organization''s
contracts, with citations.
The answer is grounded in a RELEVANCE SAMPLE, not a sweep: the
retriever fetches the passages most likely to bear on the
question and answers from those. `retrievalNote` and
`answerScope` say how many contracts that was out of how many
exist — quote them rather than presenting the answer as
portfolio-wide. When you need every match, use `GET /search`.
Costs 1 credit.'
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- question
properties:
question:
type: string
maxLength: 2000
scope:
type: object
description: Narrow the contracts considered.
properties:
contractIds:
type: array
items:
type: string
status:
type: array
items:
type: string
tags:
type: array
items:
type: string
verbosity:
type: string
enum:
- minimal
- standard
- detailed
default: standard
responses:
'200':
description: The answer, its citations, and what it was drawn from.
content:
application/json:
schema:
type: object
properties:
data:
type: object
properties:
answer:
type: string
description: Markdown. Render it or strip it — it is written for a person to read.
citations:
type: array
items:
type: object
properties:
contractId:
type: string
clmNumber:
type:
- integer
- 'null'
contractName:
type: string
excerpt:
type: string
page:
type: integer
url:
type: string
consideredContracts:
type: array
description: 'The contracts whose text the retriever pulled
in. A sample, NOT the portfolio.
'
items:
type: object
properties:
contractId:
type: string
clmNumber:
type:
- integer
- 'null'
contractName:
type: string
retrievalNote:
type: string
description: A sentence you can show the user verbatim about what the answer covers.
answerScope:
type: object
properties:
consideredContracts:
type: integer
totalContractsInOrg:
type: integer
creditsCharged:
type: integer
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'402':
$ref: '#/components/responses/PaymentRequired'
'403':
$ref: '#/components/responses/Forbidden'
'429':
$ref: '#/components/responses/TooManyRequests'
/search:
get:
tags:
- Search
operationId: searchContracts
summary: Search contracts
description: 'Natural-language + hybrid search across the organization''s
contracts. Returns ranked matches with the contract id and a
relevance score.'
parameters:
- name: q
in: query
required: true
schema:
type: string
description: The search query.
- name: take
in: query
schema:
type: integer
default: 20
maximum: 100
responses:
'200':
description: Ranked search hits.
content:
application/json:
schema:
type: object
properties:
data:
type: object
properties:
results:
type: array
description: 'One entry per matching CONTRACT, best match
first. The index is passage-level, so a
contract matching in several passages appears
once, carrying its strongest passage as the
snippet.
'
items:
type: object
properties:
contractId:
type: string
title:
type: string
description: The contract's title, or its file name when untitled.
score:
type: number
snippet:
type: string
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'429':
$ref: '#/components/responses/TooManyRequests'
'503':
description: 'The search index is not reachable for this deployment.
Distinct from an empty result set — this one is worth
retrying.
'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
/chat-sessions:
get:
tags:
- Search
operationId: listChatSessions
summary: Your saved conversations
description: '`POST /ask` is stateless — each question stands alone. A chat
session is where a multi-turn conversation lives, so an
integration can keep a thread the way the app does.'
responses:
'200':
description: The caller's sessions, newest first.
content:
application/json:
schema:
type: object
properties:
data:
type: object
properties:
items:
type: array
items:
$ref: '#/components/schemas/ChatSessionSummary'
total:
type: integer
skip:
type: integer
take:
type: integer
hasMore:
type: boolean
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'429':
$ref: '#/components/responses/TooManyRequests'
post:
tags:
- Search
operationId: createChatSession
summary: Start a conversation
requestBody:
required: false
content:
application/json:
schema:
type: object
properties:
title:
type: string
description: Defaults to "New Chat".
responses:
'201':
description: The new session.
content:
application/json:
schema:
type: object
properties:
data:
$ref: '#/components/schemas/ChatSession'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'429':
$ref: '#/components/responses/TooManyRequests'
/chat-sessions/{id}:
get:
tags:
- Search
operationId: getChatSession
summary: Read a conversation
parameters:
- name: id
in: path
required: true
schema:
type: string
responses:
'200':
description: The session and its messages.
content:
application/json:
schema:
type: object
properties:
data:
$ref: '#/components/schemas/ChatSession'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
'429':
$ref: '#/components/responses/TooManyRequests'
patch:
tags:
- Search
operationId: updateChatSession
summary: Append messages or retitle a conversation
description: 'The message array is REPLACED, not appended to — send the whole
thread, the way the app does after each turn.'
parameters:
- name: id
in: path
required: true
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
title:
type: string
messages:
type: array
description: The full conversation, replacing what is stored.
items:
type: object
additionalProperties: true
responses:
'200':
description: The updated session.
content:
application/json:
schema:
type: object
properties:
data:
$ref: '#/components/schemas/ChatSession'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
'429':
$ref: '#/components/responses/TooManyRequests'
delete:
tags:
- Search
operationId: deleteChatSession
summary: Delete a conversation
parameters:
- name: id
in: path
required: true
schema:
type: string
responses:
'204':
description: Deleted.
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
'429':
$ref: '#/components/responses/TooManyRequests'
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
PaymentRequired:
description: "Payment-gated failure, told apart by the error `code`:\n - `INSUFFICIENT_CREDITS` — the org's credit balance can't cover\n this AI operation. Top up or upgrade, then retry.\n - `USAGE_LIMIT_EXCEEDED` — a plan stock cap was hit (e.g. the\n plan's contract limit on upload). Upgrade the plan.\n"
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
insufficientCredits:
value:
error:
code: INSUFFICIENT_CREDITS
message: Not enough credits
usageLimitExceeded:
value:
error:
code: USAGE_LIMIT_EXCEEDED
message: Contract limit reached (25/25)
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.
BadRequest:
description: The request body or query failed validation.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
badRequest:
value:
error:
code: INVALID_INPUT
message: url is required
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
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.
ChatSessionSummary:
type: object
description: A saved conversation as it appears in a list. The list projection omits the messages and reports a count instead — read one session to get its messages.
properties:
id:
type: string
organizationId:
type: string
userId:
type: string
title:
type: string
messageCount:
type: integer
createdAt:
type: string
format: date-time
updatedAt:
type: string
format: date-time
ChatSession:
type: object
description: A saved conversation, with its messages.
properties:
id:
type: string
organizationId:
type: string
userId:
type: string
title:
type: string
messages:
type: array
items:
$ref: '#/components/schemas/ChatSessionMessage'
createdAt:
type: string
format: date-time
updatedAt:
type: string
format: date-time
ChatSessionMessage:
type: object
description: One turn in a saved conversation. First-party app clients attach further fields for in-app rendering; per the versioning policy, ignore any field you do not recognise.
properties:
id:
type: string
role:
type: string
enum:
- user
- assistant
content:
type: string
timestamp:
type: string
format: date-time
mode:
type: string
enum:
- full-context
- rag
description: How the answer was produced.
citations:
type: array
description: The contracts surfaced alongside the answer.
items:
type: object
properties:
contractId:
type: string
contractNumber:
type:
- integer
- 'null'
contractName:
type: string
excerpt:
type: string
page:
type: integer
discussedContracts:
type: array
description: Every contract the reply considered — usually wider than `citations`, which is curated for display.
items:
type: object
properties:
contractId:
type: string
contractNumber:
type:
- integer
- 'null'
contractName:
type: string
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**.
'