majr-app Usage API

openapi: 3.2.0
info:
  title: Dispatch Usage API
  description: 'Turns a raw development log (commit subjects + merged PR titles) into customer-facing

    release-notes Markdown. **Drafting only** — distribution and human approval stay with the

    caller, and request/response bodies are never persisted (logs carry counts, not content).


    - **Auth:** `Authorization: Bearer ` on every `/v1/*` call.

    - **Voice:** your account''s brand-voice floor is composed beneath your `voice` server-side —

    pass persona/tone only. Read it at `GET /v1/voice`.

    - **Errors:** RFC 7807 `application/problem+json`; request content is never echoed back.

    - **Agent quickstart:** `GET /llms.txt`.'
  version: 1.6.2
servers:
- url: https://dispatch.majr.app
tags:
- name: Usage
  description: Your metered usage (drafts + token counts).
paths:
  /v1/usage:
    get:
      tags:
      - Usage
      summary: 'Your usage: month-to-date and lifetime drafts + token counts'
      operationId: getUsage
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UsageResponse'
        '401':
          description: Missing or invalid bearer token
          content:
            application/problem+json:
              schema:
                properties:
                  type:
                    type: string
                    title: Type
                    default: about:blank
                  title:
                    type: string
                    title: Title
                  status:
                    type: integer
                    title: Status
                  detail:
                    anyOf:
                    - type: string
                    - type: 'null'
                    title: Detail
                type: object
                required:
                - title
                - status
                title: Problem
                description: RFC 7807 error body, served as application/problem+json.
        '403':
          description: API key is valid but not scoped for this service — use a key scoped for `required_scope` (do not rotate); `granted_scopes` lists where this key works
          content:
            application/problem+json:
              schema:
                properties:
                  type:
                    type: string
                    title: Type
                    default: about:blank
                  title:
                    type: string
                    title: Title
                  status:
                    type: integer
                    title: Status
                  detail:
                    anyOf:
                    - type: string
                    - type: 'null'
                    title: Detail
                  code:
                    type: string
                    title: Code
                    default: insufficient_service_scope
                  required_scope:
                    type: string
                    title: Required Scope
                  granted_scopes:
                    items:
                      type: string
                    type: array
                    title: Granted Scopes
                type: object
                required:
                - title
                - status
                - required_scope
                - granted_scopes
                title: InsufficientScopeProblem
                description: 'The 403 shape (per-service key scopes): valid key, not scoped for THIS service. The

                  extension members make remediation deterministic for agents — `code` to dispatch on without

                  parsing English, `required_scope` = the service refusing, `granted_scopes` = where the key

                  does work. Emitted with `WWW-Authenticate: Bearer error="insufficient_scope", scope="..."`.

                  Distinct from 401 (rotate the key) and 503 (retry): the fix is a key scoped for this

                  service, never rotation.'
        '429':
          description: 'Back off for `Retry-After` seconds; the key is valid and needs no rotation. Either the account reached its draft ceiling for the current window (app/spend_cap.py; no `code`), or — `code: free_tier_quota` — the key is over the platform''s free-tier quota: `reason` (`account_quota` | `fleet_quota`) and `resets_at` say why, and until when'
          headers:
            Retry-After:
              description: Seconds to wait before retrying — for the free-tier quota, until `resets_at`.
              schema:
                type: integer
          content:
            application/problem+json:
              schema:
                properties:
                  type:
                    type: string
                    title: Type
                    default: about:blank
                  title:
                    type: string
                    title: Title
                  status:
                    type: integer
                    title: Status
                  detail:
                    anyOf:
                    - type: string
                    - type: 'null'
                    title: Detail
                  code:
                    anyOf:
                    - type: string
                    - type: 'null'
                    title: Code
                  reason:
                    anyOf:
                    - type: string
                    - type: 'null'
                    title: Reason
                  resets_at:
                    anyOf:
                    - type: string
                    - type: 'null'
                    title: Resets At
                type: object
                required:
                - title
                - status
                title: QuotaProblem
                description: 'The 429 shape. The platform''s free-tier meter (`code: free_tier_quota`) adds `reason` —

                  `account_quota` (this builder''s calls for the month are used) or `fleet_quota` (every

                  self-serve key is paused for the day) — and `resets_at` (ISO-8601 UTC), with Retry-After

                  counting down to it. This service''s own draft ceiling (app/spend_cap.py) is a plain Problem

                  on the same status: no `code`, Retry-After only. Either way the key is valid: never rotate.'
        '503':
          description: Auth not configured / auth or usage store unavailable
          content:
            application/problem+json:
              schema:
                properties:
                  type:
                    type: string
                    title: Type
                    default: about:blank
                  title:
                    type: string
                    title: Title
                  status:
                    type: integer
                    title: Status
                  detail:
                    anyOf:
                    - type: string
                    - type: 'null'
                    title: Detail
                type: object
                required:
                - title
                - status
                title: Problem
                description: RFC 7807 error body, served as application/problem+json.
      security:
      - HTTPBearer: []
components:
  schemas:
    UsagePeriod:
      properties:
        drafts:
          type: integer
          title: Drafts
        input_tokens:
          type: integer
          title: Input Tokens
        output_tokens:
          type: integer
          title: Output Tokens
      type: object
      required:
      - drafts
      - input_tokens
      - output_tokens
      title: UsagePeriod
    UsageResponse:
      properties:
        account:
          type: string
          title: Account
        product:
          type: string
          title: Product
        tenant:
          type: string
          title: Tenant
          description: DEPRECATED alias of `product` (pre-accounts contract); will be removed in v2
          deprecated: true
        month:
          $ref: '#/components/schemas/UsagePeriod'
          description: UTC calendar month-to-date (drafting)
        lifetime:
          $ref: '#/components/schemas/UsagePeriod'
        services:
          additionalProperties:
            $ref: '#/components/schemas/ServiceUsage'
          type: object
          title: Services
          description: Cross-service breakdown for this product — every platform service that metered usage for it (only services with recorded events appear). Drafting appears as 'dispatch' with the same numbers as month/lifetime.
      type: object
      required:
      - account
      - product
      - tenant
      - month
      - lifetime
      title: UsageResponse
    ServiceUsage:
      properties:
        month:
          additionalProperties:
            anyOf:
            - type: integer
            - type: number
          type: object
          title: Month
        lifetime:
          additionalProperties:
            anyOf:
            - type: integer
            - type: number
          type: object
          title: Lifetime
      type: object
      required:
      - month
      - lifetime
      title: ServiceUsage
      description: 'Per-service totals: `events` plus that service''s own quantity sums (bytes, seconds, ...).'
  securitySchemes:
    HTTPBearer:
      type: http
      description: Service API key (`rn_...`), minted per product on the platform Control Plane.
      scheme: bearer