hyreflow-ai Billing API

openapi: 3.2.0
info:
  title: hyreflow engine (local) Billing API
  version: 0.1.0
tags:
- name: Billing
paths:
  /billing/balance:
    get:
      summary: Billing Balance
      operationId: billing_balance_billing_balance_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
      security:
      - HTTPBearer: []
      tags:
      - Billing
  /api/v2/billing/plans:
    get:
      summary: Billing Plans
      description: 'PUBLIC — the plan table the pricing page and the CLI upsell render. No auth: these are list

        prices, and the page is read before anyone has an account. Prices are resolved live from

        reference/pricing-tiers.json, so this can never disagree with what checkout charges.'
      operationId: billing_plans_api_v2_billing_plans_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
      tags:
      - Billing
  /api/v2/billing/overview:
    get:
      summary: Billing Overview
      description: 'Everything the billing page renders in one shot: balance, 30-day spend + cap, usage series +

        breakdown, recent ledger, per-member usage, and whether Stripe is wired. `user` (a member''s user id,

        repeatable: `?user=a&user=b`) narrows the usage half to those members, summed.


        The owner sees every member: the full `members` rollup, any `user`, and who made each recent call.

        Any other member sees only their own usage: every figure is narrowed to their calls, `members`

        holds only their row, and `user` may only be their own id.'
      operationId: billing_overview_api_v2_billing_overview_get
      security:
      - HTTPBearer: []
      parameters:
      - name: days
        in: query
        required: false
        schema:
          type: integer
          default: 30
          title: Days
      - name: user
        in: query
        required: false
        schema:
          type: array
          items:
            type: string
          default: []
          title: User
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Billing
  /api/v2/billing/ledger.csv:
    get:
      summary: Billing Ledger Csv
      description: 'Stream the full ledger as CSV (same incremental-yield pattern as the dataset export). Names the

        member behind each call on the same terms as the overview: every call for the owner, only the

        viewer''s own calls for anyone else.'
      operationId: billing_ledger_csv_api_v2_billing_ledger_csv_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
      security:
      - HTTPBearer: []
      tags:
      - Billing
  /api/v2/billing/checkout:
    post:
      summary: Billing Checkout
      description: Create a Stripe Checkout Session for a credit top-up. Returns {url, session_id} to redirect to.
      operationId: billing_checkout_api_v2_billing_checkout_post
      requestBody:
        content:
          application/json:
            schema:
              additionalProperties: true
              type: object
              title: Body
              default: {}
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - HTTPBearer: []
      tags:
      - Billing
  /api/v2/billing/subscription/promo-code:
    post:
      summary: Billing Subscription Promo Code
      description: 'Check a promotion code for an upgrade before the customer confirms it, so the modal can show the

        discounted charge. Returns {code, percent_off, amount_off, currency, duration, duration_in_months}.

        Read-only: the code is redeemed only by `/subscription/change`.'
      operationId: billing_subscription_promo_code_api_v2_billing_subscription_promo_code_post
      requestBody:
        content:
          application/json:
            schema:
              additionalProperties: true
              type: object
              title: Body
              default: {}
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - HTTPBearer: []
      tags:
      - Billing
  /api/v2/billing/subscription/checkout:
    post:
      summary: Billing Subscription Checkout
      description: Create a `mode=subscription` Checkout Session for a plan. Returns {url} to redirect to.
      operationId: billing_subscription_checkout_api_v2_billing_subscription_checkout_post
      requestBody:
        content:
          application/json:
            schema:
              additionalProperties: true
              type: object
              title: Body
              default: {}
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - HTTPBearer: []
      tags:
      - Billing
  /api/v2/billing/subscription/change:
    post:
      summary: Billing Subscription Change
      description: 'Move an existing subscription to another plan or cadence.


        An UPGRADE applies immediately and RESTARTS the billing period: the customer is charged the full new

        plan price today, and the next renewal follows the new monthly or annual cadence (ENG-686). The sold

        terms are NOT written here: the first webhook to observe the paid restart (`customer.subscription.updated` or

        `invoice.paid`) writes the terms and grants the FULL new monthly allotment on top of the customer''s

        existing balance. The later webhook sees the new terms and grants nothing again. Writing terms here

        would make that diff see no change and the customer would pay for the new plan without its credits.


        A DOWNGRADE is only PARKED. `proration_behavior=none` would not defer it: that flag skips the

        proration credit while Stripe swaps the price immediately, dropping the customer''s credits

        the moment they click. The pending columns hold it until the next `invoice.paid`.


        An optional `promo_code` discounts an upgrade, starting with the invoice it raises today. A code that

        can''t be used answers 422 `{error, message}` before anything is charged.'
      operationId: billing_subscription_change_api_v2_billing_subscription_change_post
      requestBody:
        content:
          application/json:
            schema:
              additionalProperties: true
              type: object
              title: Body
              default: {}
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - HTTPBearer: []
      tags:
      - Billing
  /api/v2/billing/subscription/cancel:
    post:
      summary: Billing Subscription Cancel
      description: 'Cancel at the end of the paid period, or resume (`{"resume": true}`) a cancellation not yet due.


        Not an immediate cancel: the customer paid through the end of the period and keeps the plan — and its

        monthly grants — until Stripe fires `.deleted`.'
      operationId: billing_subscription_cancel_api_v2_billing_subscription_cancel_post
      requestBody:
        content:
          application/json:
            schema:
              additionalProperties: true
              type: object
              title: Body
              default: {}
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - HTTPBearer: []
      tags:
      - Billing
  /api/v2/billing/portal:
    post:
      summary: Billing Portal
      description: 'A hosted billing-portal session: invoices, receipts, the card on file, and plan switching.


        `pay=1` is the past-due banner''s button: a subscription waiting on a payment (`past_due`, or

        `unpaid` when Stripe''s dunning ends there with the invoice still payable) gets its unpaid invoice''s

        own page instead (pay with a new card, or approve the payment with the bank), one click instead of

        finding the invoice inside the portal. No open invoice, or Stripe unreachable: the portal.'
      operationId: billing_portal_api_v2_billing_portal_post
      security:
      - HTTPBearer: []
      parameters:
      - name: pay
        in: query
        required: false
        schema:
          type: boolean
          default: false
          title: Pay
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Billing
  /api/v2/billing/checkout/resume/{session_id}:
    get:
      summary: Billing Checkout Resume
      description: 'PUBLIC — the abandoned-checkout email''s button (ENG-666). Mail never links a foreign domain

        (engine.md), so it lands here and goes back into the Stripe session while it is still open, else to

        the billing page. The redirect target is only ever Stripe''s own session url. Per-IP capped: each hit

        is a Stripe call, and the Stripe rate limit is shared with real checkouts.'
      operationId: billing_checkout_resume_api_v2_billing_checkout_resume__session_id__get
      parameters:
      - name: session_id
        in: path
        required: true
        schema:
          type: string
          title: Session Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Billing
  /api/v2/billing/stripe/webhook:
    post:
      summary: Stripe Webhook
      description: 'PUBLIC — gated only by signature + event dedup (and a per-IP rate limit). On a paid checkout, grant

        the credits carried in server-set metadata (never trust client-controlled fields); on a refund or

        dispute, claw those credits back. Every branch dedups + mutates the ledger in a single transaction so

        a crash can''t half-apply.'
      operationId: stripe_webhook_api_v2_billing_stripe_webhook_post
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
      tags:
      - Billing
  /api/v2/billing/spending-cap:
    put:
      summary: Billing Set Cap
      operationId: billing_set_cap_api_v2_billing_spending_cap_put
      requestBody:
        content:
          application/json:
            schema:
              additionalProperties: true
              type: object
              title: Body
              default: {}
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - HTTPBearer: []
      tags:
      - Billing
    delete:
      summary: Billing Clear Cap
      operationId: billing_clear_cap_api_v2_billing_spending_cap_delete
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
      security:
      - HTTPBearer: []
      tags:
      - Billing
  /api/v2/billing/session-cap:
    put:
      summary: Billing Set Session Cap
      description: 'Set the workspace''s DEFAULT per-session dollar cap. Inherited by sessions created after this call —

        a live session keeps its own limit, and any session can override or clear it via /session/{sid}/limit.'
      operationId: billing_set_session_cap_api_v2_billing_session_cap_put
      requestBody:
        content:
          application/json:
            schema:
              additionalProperties: true
              type: object
              title: Body
              default: {}
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - HTTPBearer: []
      tags:
      - Billing
    delete:
      summary: Billing Clear Session Cap
      operationId: billing_clear_session_cap_api_v2_billing_session_cap_delete
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
      security:
      - HTTPBearer: []
      tags:
      - Billing
  /api/v2/billing/auto-top-up:
    get:
      summary: Billing Get Auto Top Up
      operationId: billing_get_auto_top_up_api_v2_billing_auto_top_up_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
      security:
      - HTTPBearer: []
      tags:
      - Billing
    put:
      summary: Billing Set Auto Top Up
      operationId: billing_set_auto_top_up_api_v2_billing_auto_top_up_put
      requestBody:
        content:
          application/json:
            schema:
              additionalProperties: true
              type: object
              title: Body
              default: {}
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - HTTPBearer: []
      tags:
      - Billing
  /api/v2/billing/payment-methods/setup-intent:
    post:
      summary: Billing Pm Setup Intent
      description: 'Create a Stripe SetupIntent so the browser can save a card off-session via Stripe Elements.

        Returns {client_secret}. The saved card is recorded server-side on the setup_intent.succeeded webhook.'
      operationId: billing_pm_setup_intent_api_v2_billing_payment_methods_setup_intent_post
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
      security:
      - HTTPBearer: []
      tags:
      - Billing
  /api/v2/billing/payment-methods:
    get:
      summary: Billing Pm List
      operationId: billing_pm_list_api_v2_billing_payment_methods_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
      security:
      - HTTPBearer: []
      tags:
      - Billing
  /api/v2/billing/payment-methods/{pm_id}:
    delete:
      summary: Billing Pm Delete
      description: 'Remove a saved card: detach it at Stripe and prune it from this workspace''s auto-top-up order.'
      operationId: billing_pm_delete_api_v2_billing_payment_methods__pm_id__delete
      security:
      - HTTPBearer: []
      parameters:
      - name: pm_id
        in: path
        required: true
        schema:
          type: string
          title: Pm Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Billing
  /api/v2/billing/promo:
    post:
      summary: Billing Promo
      description: Redeem a promo code → grant credits. Failure returns 400 with {reason} (the web reads .reason).
      operationId: billing_promo_api_v2_billing_promo_post
      requestBody:
        content:
          application/json:
            schema:
              additionalProperties: true
              type: object
              title: Body
              default: {}
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - HTTPBearer: []
      tags:
      - Billing
  /api/v2/billing/linkedin-post:
    post:
      summary: Billing Linkedin Post
      description: 'Submit a LinkedIn post that tags Hyreflow for the Free-plan reward. Ops reviews it before any

        credits land. Failure returns 400 with {reason}: invalid_url | not_free | already_approved |

        duplicate_url.'
      operationId: billing_linkedin_post_api_v2_billing_linkedin_post_post
      requestBody:
        content:
          application/json:
            schema:
              additionalProperties: true
              type: object
              title: Body
              default: {}
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - HTTPBearer: []
      tags:
      - Billing
components:
  schemas:
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
      - loc
      - msg
      - type
      title: ValidationError
  securitySchemes:
    HTTPBearer:
      type: http
      scheme: bearer