Clment Insights API

openapi: 3.2.0
info:
  title: Clment REST Insights 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: Insights
  description: Portfolio-level numbers behind the Insights dashboard.
paths:
  /dashboard/insights/summary:
    get:
      tags:
      - Insights
      operationId: getInsights
      summary: Portfolio KPIs
      description: 'The headline numbers behind the Insights dashboard — contract

        counts by status, value under management, risk spread, review

        throughput. Free, and computed over the whole organization.'
      responses:
        '200':
          description: The KPI summary.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/Insights'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '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
    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.
    Insights:
      type: object
      description: Dashboard KPI summary for a window.
      properties:
        range:
          type: string
          description: The window requested, e.g. "30d".
        scope:
          type: string
          description: Whose contracts the numbers cover.
        windowStart:
          type: string
          format: date-time
        windowEnd:
          type: string
          format: date-time
        kpis:
          type: array
          items:
            type: object
            properties:
              key:
                type: string
                description: Stable identifier for the metric. New keys appear as the dashboard grows, so treat an unrecognised one as data rather than an error.
              value:
                type: number
              priorValue:
                type: number
                description: The same metric over the preceding window, for comparison.
              percentChange:
                type:
                - number
                - 'null'
              sparkline:
                type: array
                description: Per-day values across the window, oldest first.
                items:
                  type: object
                  properties:
                    date:
                      type: string
                      format: date-time
                    value:
                      type: number
  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**.

        '