Clment Search API

Natural-language and filtered search across contracts.

GitHub OpenAPI

Operations 7

POST /ask Ask a question across your contracts #
GET /search Search contracts #
GET /chat-sessions Your saved conversations #
POST /chat-sessions Start a conversation #
GET /chat-sessions/{id} Read a conversation #
PATCH /chat-sessions/{id} Append messages or retitle a conversation #
DELETE /chat-sessions/{id} Delete a conversation #

Work with this as data

Every API here is available over the APIs.io API and to AI agents over MCP.

MCP server

One button, every client — Claude, Cursor, VS Code and the rest.

https://apis.io/mcp

Tools for apis

7 MCP tools reach this
  • 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.
All 92 tools →

Call it yourself

curl for this page
This API
curl "https://apis.io/api/v1/apis/clment-com:clment-com-search-api"
All apis
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.

Get an API 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 Specification

clment-com-search-api-openapi.yml Raw ↑
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**.

        '