Clment Conversion API

openapi: 3.2.0
info:
  title: Clment REST Conversion 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: Conversion
  description: Standalone document conversion utilities (not tied to a contract). PDF-to-Word conversion is high-fidelity — layout, tables, and styles are preserved.
paths:
  /convert/pdf-to-word:
    post:
      tags:
      - Conversion
      operationId: convertPdfToWord
      summary: Convert a PDF (file) to Word
      description: 'Convert an uploaded PDF to a Word (.docx) document — a one-off

        conversion that does **not** create a contract or version.

        Conversion produces a high-fidelity `.docx`, preserving

        layout, tables, and styles.

        Upload the bytes as `multipart/form-data` (field `file`,

        **≤ 100 MB** — the same cap as contract uploads).


        Returns a short-lived `downloadToken`; fetch the DOCX with

        `GET /contracts/download/{downloadToken}` (bearer-authenticated).

        Charged per 50-page block (5 credits per block); re-converting

        identical bytes is free (cached).


        The URL-based twin (`POST /convert/pdf-url-to-word`) is handy

        when the PDF already lives at a reachable address.'
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required:
              - file
              properties:
                file:
                  type: string
                  format: binary
                  description: The PDF to convert (≤ 100 MB).
                filename:
                  type: string
                  maxLength: 200
                  description: Optional name for the resulting DOCX. Defaults to the upload's name with a .docx extension.
      responses:
        '200':
          description: Conversion complete; download with the token.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      downloadToken:
                        type: string
                        description: Use with GET /contracts/download/{downloadToken}.
                      expiresAt:
                        type: string
                        format: date-time
                      pages:
                        type: integer
                      ocrApplied:
                        type: boolean
                      creditsCharged:
                        type: integer
                        description: 0 when served from the conversion cache.
        '400':
          description: No file, or the upload isn't a PDF.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '413':
          description: File exceeds the 100 MB limit.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /convert/pdf-url-to-word:
    post:
      tags:
      - Conversion
      operationId: convertPdfUrlToWord
      summary: Convert a PDF (from URL) to Word
      description: 'Convert a PDF at a public HTTPS URL to a Word (.docx) document —

        a one-off conversion that does **not** create a contract or any

        document version. Like its file-upload twin, it produces a high-fidelity

        `.docx` (layout, tables, and styles preserved). (To convert a PDF that''s

        already a contract version and store the result on the contract,

        use `POST /contracts/{id}/versions/{versionId}/convert-to-word`.)


        The API downloads the PDF server-side (so the URL must be

        reachable from our infrastructure, ≤ 50 MB), converts it, and

        returns a short-lived `downloadToken`. Fetch the DOCX with

        `GET /contracts/download/{downloadToken}` (bearer-authenticated,

        same as redline downloads); the token is valid for 30 minutes.


        Charged per 50-page block: 5 credits up to 50 pages, +5 per

        additional 50. Same SHA-256 cache as the rest of the platform —

        re-converting identical bytes is free (`creditsCharged: 0`).'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - pdfUrl
              properties:
                pdfUrl:
                  type: string
                  format: uri
                  description: Public HTTPS URL of the PDF (≤ 50 MB, reachable from our servers).
                filename:
                  type: string
                  maxLength: 200
                  description: Optional name for the resulting DOCX (path components stripped). Defaults to "converted.docx".
      responses:
        '200':
          description: Conversion complete; download with the token.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      downloadToken:
                        type: string
                        description: Use with GET /contracts/download/{downloadToken}.
                      expiresAt:
                        type: string
                        format: date-time
                        description: After this the token stops working (~30 min).
                      pages:
                        type: integer
                      ocrApplied:
                        type: boolean
                        description: Whether OCR was applied (image-only PDF).
                      creditsCharged:
                        type: integer
                        description: 0 when served from the conversion cache.
        '400':
          description: Bad input, fetch failed, or the URL didn't return a PDF.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '413':
          description: PDF exceeds the 50 MB limit.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
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)
    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.
  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**.

        '