LogBrew Billing API

openapi: 3.2.0
info:
  contact:
    email: support@logbrew.co
    name: LogBrew support
    url: https://logbrew.co
  description: 'Send `Authorization: Bearer ` with an account access token or a project key. `logbrew login` signs in and stores an access token; `logbrew projects keys create` makes project keys. A read key reads one project''s telemetry and nothing else. Without the CLI, get an access token with device sign-in (RFC 8628): `POST /api/auth/device` with a form-encoded `client_id`, show the person the `user_code` and `verification_uri`, then poll `POST /api/auth/device/token` until they approve.


    Every error has the same JSON shape: a stable `code`, a readable `error`, and a `next` step that says how to recover. A `429` response carries `Retry-After`.


    Some operations have several response versions. This document describes the newest one, so send the `response_version` it requires. List operations return pages with `pagination=cursor`. Older versions keep their exact shape for clients that already use them.


    To test an integration without touching production data, create a separate project for it: each project has its own keys and data, and the free plan covers it. `load_sample_data` fills a new project with a connected example issue, logs, and trace that never count toward usage, `remove_sample_data` removes exactly those rows, and `send_test_event` checks a key end to end.'
  summary: Read and manage LogBrew projects, issues, logs, traces, actions, metrics, releases, and product analytics.
  title: LogBrew Billing API
  version: '1'
servers:
- description: LogBrew API
  url: https://api.logbrew.co
tags:
- description: Plans, checkout, and the billing portal.
  name: Billing
paths:
  /api/billing/catalog:
    get:
      description: List the plans and their prices. Needs no bearer credential.
      operationId: get_billing_catalog
      parameters: []
      responses:
        '200':
          content:
            application/json:
              example:
                checkout_available: false
                currency: string
                interval: month
                plans:
                - activation: included
                  limits:
                    issue_events: 1
                    log_bytes: 1
                    metric_bytes: 1
                    retention_days: 1
                    trace_spans: 1
                    unlimited_projects: false
                  monthly_price_cents: 1
                  quote_email: string
                  tier: developer
                response_version: 1
              schema:
                $ref: '#/components/schemas/BillingCatalogResponse'
          description: Success.
        '429':
          $ref: '#/components/responses/RateLimited'
        default:
          $ref: '#/components/responses/Error'
      security: []
      summary: List the plans and their prices
      tags:
      - Billing
  /api/billing/checkout:
    post:
      description: Start checkout for a plan. A person opens the returned link to pay. Needs an account access token.
      operationId: create_checkout
      parameters: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BillingCheckoutRequest'
        required: true
      responses:
        '200':
          content:
            application/json:
              example:
                url: string
              schema:
                $ref: '#/components/schemas/BillingSessionResponse'
          description: Success.
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimited'
        default:
          $ref: '#/components/responses/Error'
      security:
      - accessToken: []
      summary: Start checkout for a plan. A person opens the returned link to pay
      tags:
      - Billing
  /api/billing/overview:
    get:
      description: Read your plan, billing status, and usage per signal. Needs an account access token.
      operationId: get_billing_overview
      parameters: []
      responses:
        '200':
          content:
            application/json:
              example:
                checkout_available: false
                management_available: false
                meters:
                - included: 1
                  kind: issue_events
                  state: ok
                  unit: events
                  used: 1
                offer:
                  ends_at: '2026-10-27T12:00:00Z'
                  kind: public_beta
                  starts_at: '2026-10-27T12:00:00Z'
                  tier: developer
                period_end: '2026-10-27T12:00:00Z'
                period_start: '2026-10-27T12:00:00Z'
                pro_trial_available: false
                response_version: 1
                state: free
                tier: developer
                warning_threshold_basis_points: 1
              schema:
                $ref: '#/components/schemas/BillingOverviewResponse'
          description: Success.
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimited'
        default:
          $ref: '#/components/responses/Error'
      security:
      - accessToken: []
      summary: Read your plan, billing status, and usage per signal
      tags:
      - Billing
  /api/billing/portal:
    post:
      description: Get a billing portal link where a person manages payment and invoices. Needs an account access token.
      operationId: open_billing_portal
      parameters: []
      responses:
        '200':
          content:
            application/json:
              example:
                url: string
              schema:
                $ref: '#/components/schemas/BillingSessionResponse'
          description: Success.
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimited'
        default:
          $ref: '#/components/responses/Error'
      security:
      - accessToken: []
      summary: Get a billing portal link where a person manages payment and invoices
      tags:
      - Billing
components:
  schemas:
    BillingPlanLimitsResponse:
      description: Fixed included usage for one plan.
      properties:
        issue_events:
          description: Included issue/error events per billing period.
          format: uint64
          minimum: 0
          type:
          - integer
          - 'null'
        log_bytes:
          description: Included normalized log bytes per billing period.
          format: uint64
          minimum: 0
          type:
          - integer
          - 'null'
        metric_bytes:
          description: Included normalized application-metric bytes per billing period.
          format: uint64
          minimum: 0
          type:
          - integer
          - 'null'
        retention_days:
          description: Retention in days.
          format: uint16
          maximum: 65535
          minimum: 0
          type:
          - integer
          - 'null'
        trace_spans:
          description: Included trace spans per billing period.
          format: uint64
          minimum: 0
          type:
          - integer
          - 'null'
        unlimited_projects:
          description: Projects are unlimited for this plan.
          type: boolean
      required:
      - issue_events
      - log_bytes
      - metric_bytes
      - trace_spans
      - retention_days
      - unlimited_projects
      type: object
    BillingOfferKind:
      description: Offer kinds.
      oneOf:
      - const: public_beta
        description: 'The new-account offer: Pro (`team`) allowances for 6 months from sign-up (from

          2026-10-22 for accounts that existed at launch). Sign-up no longer grants it; accounts

          that hold it keep it until it ends, and new accounts try Pro through the checkout trial.'
        type: string
    BillingSubscriptionState:
      description: Canonical subscription lifecycle state.
      oneOf:
      - const: free
        description: Developer plan.
        type: string
      - const: active
        description: Paid access is active.
        type: string
      - const: past_due
        description: Payment needs attention.
        type: string
      - const: paused
        description: Paid access is paused.
        type: string
      - const: canceled
        description: Subscription ended.
        type: string
    BillingActivation:
      description: How a plan is activated.
      oneOf:
      - const: included
        description: Active without checkout.
        type: string
      - const: checkout
        description: Fixed-price Stripe checkout.
        type: string
      - const: quote
        description: Email quote.
        type: string
    BillingCheckoutRequest:
      additionalProperties: false
      description: Fixed-price checkout request.
      properties:
        locale:
          $ref: '#/components/schemas/BillingLocale'
          description: User-visible locale preserved through return navigation.
        request_id:
          description: Caller-owned retry identity.
          format: uuid
          type: string
        tier:
          $ref: '#/components/schemas/BillingTier'
          description: Only `team` (Pro) or `business` is accepted.
      required:
      - tier
      - locale
      - request_id
      type: object
    BillingSessionResponse:
      description: Hosted provider-session response.
      properties:
        url:
          description: Short-lived HTTPS destination owned by Stripe.
          type: string
      required:
      - url
      type: object
    BillingOfferResponse:
      description: Plan allowances granted for a fixed time, apart from a paid subscription.
      properties:
        ends_at:
          description: Exclusive end; the account falls back to its own plan afterwards.
          format: date-time
          type: string
        kind:
          $ref: '#/components/schemas/BillingOfferKind'
          description: Why the allowances apply.
        starts_at:
          description: Inclusive start.
          format: date-time
          type: string
        tier:
          $ref: '#/components/schemas/BillingTier'
          description: Plan whose allowances apply while the offer lasts.
      required:
      - kind
      - tier
      - starts_at
      - ends_at
      type: object
    BillingPlanResponse:
      description: One fixed plan.
      properties:
        activation:
          $ref: '#/components/schemas/BillingActivation'
          description: How this plan is activated.
        limits:
          $ref: '#/components/schemas/BillingPlanLimitsResponse'
          description: Fixed included usage.
        monthly_price_cents:
          description: Monthly price in USD cents; absent for quoted Enterprise contracts.
          format: uint32
          minimum: 0
          type:
          - integer
          - 'null'
        quote_email:
          description: Quote mailbox for Enterprise; absent for self-serve plans.
          type:
          - string
          - 'null'
        tier:
          $ref: '#/components/schemas/BillingTier'
          description: Stable plan identifier.
      required:
      - tier
      - monthly_price_cents
      - activation
      - quote_email
      - limits
      type: object
    BillingMeterState:
      description: Derived meter state.
      oneOf:
      - const: ok
        description: Below 80%.
        type: string
      - const: warning
        description: At or above 80% but below the hard limit.
        type: string
      - const: blocked
        description: At or above the hard limit.
        type: string
      - const: quoted
        description: Defined by a quoted Enterprise contract outside this fixed catalog.
        type: string
    BillingMeterUnit:
      description: Meter units.
      oneOf:
      - const: events
        description: Event count.
        type: string
      - const: bytes
        description: Byte count.
        type: string
      - const: spans
        description: Span count.
        type: string
    BillingInterval:
      description: Fixed billing interval.
      oneOf:
      - const: month
        description: Calendar or provider-owned monthly period.
        type: string
    BillingOverviewResponse:
      description: Authenticated billing and per-signal usage overview.
      properties:
        checkout_available:
          description: Whether fixed-price checkout is connected.
          type: boolean
        management_available:
          description: Whether a provider management session can be created.
          type: boolean
        meters:
          description: Complete fixed-order metering receipt.
          items:
            $ref: '#/components/schemas/BillingMeterResponse'
          type: array
        offer:
          anyOf:
          - $ref: '#/components/schemas/BillingOfferResponse'
          - type: 'null'
          default: null
          description: Active offer whose plan allowances the meters include; absent when none applies.
        period_end:
          description: Exclusive usage-period end and reset time.
          format: date-time
          type: string
        period_start:
          description: Inclusive usage-period start.
          format: date-time
          type: string
        pro_trial_available:
          default: false
          description: 'Whether a Pro checkout now starts the 1-month free trial: checkout is connected and the

            account never had a subscription.'
          type: boolean
        response_version:
          description: Contract version.
          format: uint8
          maximum: 255
          minimum: 0
          type: integer
        state:
          $ref: '#/components/schemas/BillingSubscriptionState'
          description: Current subscription lifecycle state.
        tier:
          $ref: '#/components/schemas/BillingTier'
          description: Current canonical plan.
        warning_threshold_basis_points:
          description: Warning threshold in basis points.
          format: uint16
          maximum: 65535
          minimum: 0
          type: integer
      required:
      - response_version
      - tier
      - state
      - period_start
      - period_end
      - checkout_available
      - management_available
      - pro_trial_available
      - warning_threshold_basis_points
      - meters
      - offer
      type: object
    BillingTier:
      description: Canonical subscription tier.
      oneOf:
      - const: developer
        description: Free individual plan.
        type: string
      - const: team
        description: Fixed $25 monthly plan.
        type: string
      - const: business
        description: Fixed $80 monthly plan.
        type: string
      - const: enterprise
        description: Quoted contract.
        type: string
    BillingMeterKind:
      description: Fixed metered resources.
      oneOf:
      - const: issue_events
        description: Issue/error event count.
        type: string
      - const: log_bytes
        description: Normalized log bytes.
        type: string
      - const: metric_bytes
        description: Normalized application-metric bytes.
        type: string
      - const: trace_spans
        description: Trace span count.
        type: string
    BillingLocale:
      description: Supported Website locale.
      oneOf:
      - const: en
        description: English.
        type: string
      - const: tr
        description: Turkish.
        type: string
      - const: de
        description: German.
        type: string
      - const: es
        description: Spanish.
        type: string
      - const: ja
        description: Japanese.
        type: string
    BillingMeterResponse:
      description: One per-signal usage meter.
      properties:
        included:
          description: Included units; absent only for a quoted Enterprise contract.
          format: uint64
          minimum: 0
          type:
          - integer
          - 'null'
        kind:
          $ref: '#/components/schemas/BillingMeterKind'
          description: Meter identity.
        state:
          $ref: '#/components/schemas/BillingMeterState'
          description: Derived utilization state.
        unit:
          $ref: '#/components/schemas/BillingMeterUnit'
          description: Meter unit.
        used:
          description: Used units in the current period.
          format: uint64
          minimum: 0
          type: integer
      required:
      - kind
      - unit
      - used
      - included
      - state
      type: object
    BillingCatalogResponse:
      description: Public fixed-plan catalog.
      properties:
        checkout_available:
          description: Whether self-serve checkout is available.
          type: boolean
        currency:
          description: ISO currency used by every self-serve price.
          type: string
        interval:
          $ref: '#/components/schemas/BillingInterval'
          description: Fixed billing interval used by every self-serve price.
        plans:
          description: Ordered Developer, Team, Business, and Enterprise plans.
          items:
            $ref: '#/components/schemas/BillingPlanResponse'
          type: array
        response_version:
          description: Contract version.
          format: uint8
          maximum: 255
          minimum: 0
          type: integer
      required:
      - response_version
      - currency
      - interval
      - checkout_available
      - plans
      type: object
  responses:
    Error:
      content:
        application/json:
          schema:
            properties:
              code:
                description: Stable reason, such as `unauthorized`, `forbidden`, `not_found`, `validation_failed`, `rate_limited`, or `usage_limit_exceeded`.
                type: string
              deleted_at:
                description: When the account was deleted, on `account_recovery_available`.
                type: string
              error:
                description: What went wrong, in words.
                type: string
              limit:
                description: The limit that was reached.
                type: string
              next:
                description: How to recover.
                type: string
              next_action:
                description: The recovery as stable codes.
                properties:
                  code:
                    description: Stable recovery action, such as `sign_in` or `retry_later`.
                    type: string
                  target:
                    description: Where the recovery happens, such as `auth` or `billing`.
                    type: string
                required:
                - code
                - target
                type: object
              recovery_token:
                description: Token for restore_account, on `account_recovery_available`.
                type: string
              reset_at:
                description: When the limit resets, as an RFC 3339 time.
                type: string
              retry_after_seconds:
                description: Seconds to wait, on `rate_limited`.
                minimum: 0
                type: integer
            required:
            - error
            - code
            - next
            - next_action
            type: object
      description: The request failed. `code` names the reason and `next` says how to recover.
    RateLimited:
      content:
        application/json:
          schema:
            properties:
              code:
                description: Stable reason, such as `unauthorized`, `forbidden`, `not_found`, `validation_failed`, `rate_limited`, or `usage_limit_exceeded`.
                type: string
              deleted_at:
                description: When the account was deleted, on `account_recovery_available`.
                type: string
              error:
                description: What went wrong, in words.
                type: string
              limit:
                description: The limit that was reached.
                type: string
              next:
                description: How to recover.
                type: string
              next_action:
                description: The recovery as stable codes.
                properties:
                  code:
                    description: Stable recovery action, such as `sign_in` or `retry_later`.
                    type: string
                  target:
                    description: Where the recovery happens, such as `auth` or `billing`.
                    type: string
                required:
                - code
                - target
                type: object
              recovery_token:
                description: Token for restore_account, on `account_recovery_available`.
                type: string
              reset_at:
                description: When the limit resets, as an RFC 3339 time.
                type: string
              retry_after_seconds:
                description: Seconds to wait, on `rate_limited`.
                minimum: 0
                type: integer
            required:
            - error
            - code
            - next
            - next_action
            type: object
      description: Too many requests. Wait the `Retry-After` seconds, then retry.
      headers:
        Retry-After:
          description: Seconds to wait before retrying.
          schema:
            minimum: 0
            type: integer
    Unauthorized:
      content:
        application/json:
          schema:
            properties:
              code:
                description: Stable reason, such as `unauthorized`, `forbidden`, `not_found`, `validation_failed`, `rate_limited`, or `usage_limit_exceeded`.
                type: string
              deleted_at:
                description: When the account was deleted, on `account_recovery_available`.
                type: string
              error:
                description: What went wrong, in words.
                type: string
              limit:
                description: The limit that was reached.
                type: string
              next:
                description: How to recover.
                type: string
              next_action:
                description: The recovery as stable codes.
                properties:
                  code:
                    description: Stable recovery action, such as `sign_in` or `retry_later`.
                    type: string
                  target:
                    description: Where the recovery happens, such as `auth` or `billing`.
                    type: string
                required:
                - code
                - target
                type: object
              recovery_token:
                description: Token for restore_account, on `account_recovery_available`.
                type: string
              reset_at:
                description: When the limit resets, as an RFC 3339 time.
                type: string
              retry_after_seconds:
                description: Seconds to wait, on `rate_limited`.
                minimum: 0
                type: integer
            required:
            - error
            - code
            - next
            - next_action
            type: object
      description: The credential is missing, expired, or revoked, or this operation does not accept it.
  securitySchemes:
    accessToken:
      bearerFormat: JWT
      description: Account access token. It acts as your account in every project you can reach. `logbrew login` creates one; renew it with refresh_access_token before it expires.
      scheme: bearer
      type: http
    projectKey:
      description: 'Project key. A key reaches only its own project and has one kind: `read` keys (prefix `lbw_read_`) read telemetry; `sdk`, `server`, `browser`, and `cli` keys (prefix `lbw_ingest_`) send telemetry; `artifact` keys upload debug files. Each operation''s security requirement lists the kinds it accepts.'
      scheme: bearer
      type: http