InfoLang Inc. Usage API

openapi: 3.2.0
info:
  title: InfoLang Usage API
  version: 2.0.0
  description: 'The InfoLang gateway. `/v2` is the console + runtime API; the raw Kairos runtime surface stays proxied at `/v1` and `/mcp`, and **Canon** — the coordination layer — at `/coord/v1` where the deployment serves it (`capabilities.canon` on `GET /v2/me`). ## Three credential lanes


    Every `/v2` request carries a bearer token, and its prefix decides the lane:


    | Lane | Credential | For |

    |---|---|---|

    | **session** (`sessionAuth`) | Supabase session JWT | the website / console |

    | **oauth** (`oauthTokenAuth`) | `il_oauth_…` | a HUMAN who connected an MCP client (Claude, an IDE) |

    | **key** (`apiKeyAuth`) | `il_live_…` / `il_test_…` | MACHINES — SDKs, servers, CI |


    The gateway verifies only the session lane, minting a separate Kairos runtime token for upstream calls; the two `il_*` credentials are classified and forwarded verbatim, and Kairos verifies them and enforces the credential↔workspace binding. ## Which lanes a route accepts


    The general rule: **anything scoped to a workspace accepts all three lanes; the routes with no workspace in the path are session-only.** Concretely —


    - **All three lanes:** the runtime ops (`Runtime`), memories and namespaces (`Memories`), `GET /v2/whoami`, the read-only `Usage` and `Activity` views, and — since credential scoping — every `/v2/workspaces/{id}/…` route: keys, members, workspace CRUD, billing, ingest, webhooks, plus `GET /v2/me`. - **Session-only:** `POST /v2/bootstrap`, the workspace collection (`GET`/`POST /v2/workspaces`), the principal-keyed `/v2/billing` routes, and the console''s playground. These answer 403 `lane_not_supported` to an `il_*` credential: with no workspace in the path there is nothing for the gateway to bind the credential to. Each route''s `security` block is authoritative. **Accepting a lane is not granting access** — an `il_*` credential also has to carry the route''s scope (below). ## Scopes


    A credential may carry LESS authority than the principal behind it. Scopes are how you say so, and they are written `resource:action`:


    - `write` on a resource implies `read` on the same resource — `memories:write` covers recall. `workspace:delete` implies nothing else. - The resources are `memories`, `coord`, `compute`, `ingest`, `usage`, `activity`, `keys`, `members`, `workspace`, `billing` and `webhooks`. `compute:read` (encode, similarity) is stateless — it touches no stored data. `coord:read`/`coord:write` cover **Canon**, the coordination layer, and are enforced by Kairos on `/coord/v1/*` rather than by the gateway. - Wildcards (`*`, `:*`, `*:read`) are accepted **when creating** a credential and are resolved right then, into the concrete set. A wildcard will NOT silently widen to cover resources InfoLang adds later; to pick up a new resource, create a new credential. - A credential can be restricted to specific workspaces and given `not_before` and/or `expires_at`. Outside `[not_before, expires_at)` it is rejected with 401 `credential_expired`. - A credential can also be restricted to specific **namespaces** — the resource axis below workspace. See below; it has consequences worth reading before you grant one. - A credential minted before scoping shipped carries no scope record and resolves to a fixed legacy default, so nothing broke when scopes arrived. Each scoped route says below whether that default covers it. ### Two ceilings


    A request is allowed only if **both** hold:


    1. the credential''s scopes permit the operation, **and**

    2. the role of the principal behind the credential permits it on that workspace (Owner > Admin > Member > ReadOnly). **Neither ceiling can raise the other.** A key carrying `keys:write` held by a principal whose role is ReadOnly cannot manage keys; equally, an Owner presenting a key scoped only to `memories:read` cannot manage keys with it.'
servers:
- url: https://api.infolang.ai
  description: Production
tags:
- name: Usage
  description: Metered usage and plan inclusions. Read-only — all three lanes.
paths:
  /v2/workspaces/{id}/usage:
    get:
      tags:
      - Usage
      summary: Monthly usage
      description: 'Metered usage for the month (default: current). `meters` breaks the period down per canonical meter — recall, memorize, ingest, storage, egress — each row carrying used/included/overage against the workspace''s plan inclusions, plus the informational `chunks_ingested` row. `egress` (tokens returned) has no plan allowance yet, so its `included`/`overage` are `0`; render those columns as — rather than as a zero-sized inclusion. Also carries point-in-time gauges: namespace count and key counts by env.


        **Quota pools at the billing account.** Each row''s `used` is THIS workspace''s own quantity; the number quota is enforced against is the account total in `meters[].account.used`, summed over the workspaces listed in the top-level `account.workspaces`. A bar drawn from `used` against `included` shows a multi-workspace customer a healthy figure and is then contradicted by a refusal — draw `account.used` against `account.included`. `overage` is likewise account-scoped. The four capped meters carry an `account` block; `egress` and `chunks_ingested` do not, because nothing caps them. When the pooled read is unavailable the top-level `account` says so (`status: "unavailable"`) and no row carries a pooled figure — the per-workspace number is never substituted for it.


        **Per-workspace breakdown.** Each `account` block MAY carry `by_workspace`: the pooled `used` segmented by contributing workspace, sorted descending and summing exactly to `account.used`. It is computed upstream and forwarded unchanged — do not re-sum or re-sort it. It is OPTIONAL and its absence carries no information: it is omitted both when the upstream reports no breakdown and when THE CALLER MAY NOT SEE EVERY WORKSPACE THE ACCOUNT OWNS. Per-workspace figures are a disclosure the pooled total is not — a credential scoped to some of an account''s workspaces can learn the size of the pool it is measured against, but not which siblings make it up — so the field appears only when the caller''s workspace visibility is a superset of `account.workspaces` (a session-lane owner, or a credential scoped to `*`). The two omissions are indistinguishable on purpose; treat a missing `by_workspace` as "no segmentation available" and render the pooled bar unsegmented.


        Class B read-only — all three lanes, via the IDOR-safe Kairos preflight. The `namespaces` gauge degrades to `0` rather than failing the response when the underlying memories scan cannot be computed, so a usage read does not 502 just because Kairos is down.


        Requires the `usage:read` scope. Accepts all three lanes: a session JWT (bounded by the caller''s role on this workspace) or an `il_*` machine credential whose own scope set, workspace set and validity window cover it — both ceilings apply and neither can raise the other, so a credential carrying `usage:read` is still refused where the role does not permit it.


        A credential with no scope record resolves to `LEGACY_DEFAULT`, which INCLUDES `usage:read` — every key minted before scoping keeps working here.'
      security:
      - sessionAuth: []
      - apiKeyAuth: []
      - oauthTokenAuth: []
      parameters:
      - schema:
          type: string
        required: true
        name: id
        in: path
      - schema:
          type: string
          pattern: ^\d{4}-\d{2}$
        required: false
        name: month
        in: query
      responses:
        '200':
          description: Usage for the month
          content:
            application/json:
              schema:
                type: object
                properties:
                  workspace_id:
                    type: string
                  month:
                    type: string
                    pattern: ^\d{4}-\d{2}$
                  used:
                    type: integer
                    minimum: 0
                  included:
                    type: integer
                    minimum: 0
                  hard_cap:
                    type: integer
                    nullable: true
                    minimum: 0
                  overage:
                    type: object
                    properties:
                      spend_cents_to_date:
                        type: integer
                        minimum: 0
                      budget_cents:
                        type: integer
                        minimum: 0
                      by_meter:
                        type: array
                        items:
                          type: object
                          properties:
                            meter:
                              type: string
                              enum:
                              - storage
                              - recall
                            over_units:
                              type: integer
                              minimum: 0
                            cents:
                              type: integer
                              minimum: 0
                          required:
                          - meter
                          - over_units
                          - cents
                    required:
                    - spend_cents_to_date
                    - budget_cents
                    - by_meter
                  account:
                    oneOf:
                    - type: object
                      properties:
                        status:
                          type: string
                          enum:
                          - pooled
                        account_id:
                          type: string
                        workspaces:
                          type: array
                          items:
                            type: string
                        tier:
                          type: string
                      required:
                      - status
                      - account_id
                      - workspaces
                      - tier
                    - type: object
                      properties:
                        status:
                          type: string
                          enum:
                          - unavailable
                        reason:
                          type: string
                          enum:
                          - not_configured
                          - not_supported
                          - upstream_error
                      required:
                      - status
                      - reason
                  meters:
                    type: array
                    items:
                      type: object
                      properties:
                        meter:
                          type: string
                          enum:
                          - recall
                          - memorize
                          - ingest
                          - storage
                          - egress
                          - chunks_ingested
                        used:
                          type: integer
                          minimum: 0
                        included:
                          type: integer
                          minimum: 0
                        overage:
                          type: integer
                          minimum: 0
                        account:
                          type: object
                          properties:
                            used:
                              type: integer
                              minimum: 0
                            included:
                              type: integer
                              nullable: true
                              minimum: 0
                            hard_cap:
                              type: boolean
                            period:
                              type: string
                            is_stock:
                              type: boolean
                            by_workspace:
                              type: array
                              items:
                                type: object
                                properties:
                                  workspace_id:
                                    type: string
                                  used:
                                    type: integer
                                    minimum: 0
                                required:
                                - workspace_id
                                - used
                          required:
                          - used
                          - included
                          - hard_cap
                          - period
                          - is_stock
                      required:
                      - meter
                      - used
                      - included
                      - overage
                  pricing:
                    type: object
                    properties:
                      currency:
                        type: string
                      per_unit:
                        type: number
                        minimum: 0
                      amount:
                        type: number
                        minimum: 0
                    required:
                    - currency
                    - per_unit
                    - amount
                  namespaces:
                    type: integer
                    minimum: 0
                  keys:
                    type: object
                    properties:
                      live:
                        type: integer
                        minimum: 0
                      test:
                        type: integer
                        minimum: 0
                      total:
                        type: integer
                        minimum: 0
                    required:
                    - live
                    - test
                    - total
                required:
                - workspace_id
                - month
                - used
                - included
                - account
                - meters
                - pricing
                - namespaces
                - keys
        '401':
          description: The credential itself is invalid — absent, unverifiable on the session lane, or rejected by the Kairos preflight on the `il_live_`/`il_test_`/`il_oauth_` lanes — or `credential_expired`, outside its `[not_before, expires_at)` window
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                      message:
                        type: string
                    required:
                    - code
                    - message
                required:
                - error
        '403':
          description: '`forbidden` — the credential is valid but holds NO grant on this workspace, or is not scoped to it. On the il_* lanes this is the IDOR guard: the preflight bound the presented credential to the path `{id}` and it did not match, so no workspace data was read. Or `insufficient_scope` — the credential''s scope set or the caller''s role does not cover the scope this route requires (named in the message)'
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                      message:
                        type: string
                    required:
                    - code
                    - message
                required:
                - error
        '422':
          description: month must be YYYY-MM
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                      message:
                        type: string
                    required:
                    - code
                    - message
                required:
                - error
      operationId: getV2WorkspacesByIdUsage
      x-operation-id-source: derived
components:
  securitySchemes:
    sessionAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: '**Use this when the caller is a signed-in person in the InfoLang console (the website).** Not for anything you deploy: a session token belongs to a browser session, cannot be minted programmatically, and expires with the session. For a server or CI job use `apiKeyAuth`; for an end user connecting a tool to their own workspace use `oauthTokenAuth`.


        Supabase session JWT — the website lane. Accepted on EVERY /v2 route, and the ROOT of authority: it carries no scope ceiling of its own (the caller''s role on each workspace is the only limit) and it is what mints every attenuated machine credential. The gateway verifies the session and mints a separate Kairos runtime token for upstream calls — session JWTs are never forwarded to Kairos.'
    apiKeyAuth:
      type: http
      scheme: bearer
      description: '**Use this for machines — SDKs, your backend, cron jobs, CI.** Create one per workspace in the console, restricted to the scopes that job actually needs (and, if you want, to specific workspaces and a validity window). `il_test_` and `il_live_` are separate environments. This is the credential to reach for whenever there is no human in the loop; if a human IS in the loop and connecting their own tool, use `oauthTokenAuth` instead so the action is attributed to them.


        InfoLang API key (il_live_… / il_test_…) — the machine lane, for SDKs, servers and CI. Used by the /v1 and /mcp passthrough surface and by the /v2 routes it carries the scope for; verified by Kairos, not the gateway. Authority is carried by the key — an explicit `(scopes × workspaces × TTL)` policy set at mint time and never wider than the credential that minted it. A key minted before scoping carries no policy and resolves to the named `LEGACY_DEFAULT` set (`memories:*`, `compute:read`, `usage:read`, `activity:read`, `ingest:write`, all workspaces its principal holds).'
    oauthTokenAuth:
      type: http
      scheme: bearer
      description: '**Use this when a PERSON is connecting a tool to their own workspace** — an MCP client, an IDE, a third-party app acting on their behalf. The token is issued to that person, so what it can do is bounded by their role on the workspace, and revoking the connection revokes the access. Do not ask an end user to paste an API key into a tool to achieve this; that hands the tool a machine credential and attributes its writes to whoever created the key.


        OAuth access token (il_oauth_…) — the human lane: a token issued to a PERSON who connected an MCP client (Claude, an IDE) rather than to a machine. Opaque; verified by Kairos, not the gateway. Issuance (authorization server, consent, PKCE, DCR) is a separate build — this documents the credential''s acceptance on the routes that already take it.'