Clment Rulebooks API

openapi: 3.2.0
info:
  title: Clment REST Rulebooks 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: Rulebooks
  description: The rulebooks AI reviews evaluate contracts against (sometimes known as playbooks).
paths:
  /rulebooks:
    get:
      tags:
      - Rulebooks
      operationId: listRulebooks
      summary: List rulebooks
      parameters:
      - name: status
        in: query
        schema:
          $ref: '#/components/schemas/RulebookStatus'
      responses:
        '200':
          description: Rulebooks for the organization.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      rulebooks:
                        type: array
                        items:
                          $ref: '#/components/schemas/Rulebook'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/TooManyRequests'
    post:
      tags:
      - Rulebooks
      operationId: createRulebook
      summary: Create a rulebook
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - name
              - instructions
              properties:
                name:
                  type: string
                description:
                  type: string
                instructions:
                  type: string
                  description: The review rulebook, in markdown.
                status:
                  allOf:
                  - $ref: '#/components/schemas/RulebookStatus'
                  default: draft
                tags:
                  type: array
                  items:
                    type: string
      responses:
        '201':
          description: The created rulebook.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      rulebook:
                        $ref: '#/components/schemas/Rulebook'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/TooManyRequests'
  /rulebooks/{id}:
    get:
      tags:
      - Rulebooks
      operationId: getRulebook
      summary: Get a rulebook
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: The rulebook.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      rulebook:
                        $ref: '#/components/schemas/Rulebook'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '404':
          $ref: '#/components/responses/NotFound'
    delete:
      tags:
      - Rulebooks
      operationId: deleteRulebook
      summary: Delete a rulebook
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '204':
          description: Deleted.
        '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
    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
    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.
    Rulebook:
      type: object
      required:
      - id
      - name
      - description
      - instructions
      - status
      - version
      - tags
      - createdAt
      - updatedAt
      properties:
        id:
          type: string
        name:
          type: string
        description:
          type:
          - string
          - 'null'
        instructions:
          type: string
        status:
          $ref: '#/components/schemas/RulebookStatus'
        version:
          type: integer
        tags:
          type: array
          items:
            type: string
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
    RulebookStatus:
      type: string
      description: Whether a rulebook is a working draft or available to run reviews against.
      enum:
      - draft
      - published
  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**.

        '