Notyfi billing API

openapi: 3.1.0
info:
  title: Notyfi account billing API
  version: 1.2.0
  description: 'Track anything in a sentence and get notified the moment it happens -- by email, REST API, or MCP. Authenticate every request with a Notyfi API key (`Authorization: Bearer notyfi_mk_...`). Manage keys in your dashboard.'
servers:
- url: https://api.notyfi.com
security:
- bearerAuth: []
- apiKeyAuth: []
tags:
- name: billing
paths:
  /api/v1/billing:
    get:
      tags:
      - billing
      summary: Current plan, limits, and tracker usage
      operationId: billing_status_api_v1_billing_get
      parameters:
      - name: X-Notyfi-ID-Token
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Notyfi-Id-Token
      - name: authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      - name: x-api-key
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Api-Key
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BillingStatus'
        '401':
          description: Missing or invalid Cognito access token.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: API keys cannot manage a human billing account.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '409':
          description: Account identity or billing-state conflict.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Rate limit exceeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '503':
          description: Stripe is unavailable or not configured.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/billing/checkout:
    post:
      tags:
      - billing
      summary: Create or resume a Stripe-hosted Pro Checkout session
      operationId: billing_checkout_api_v1_billing_checkout_post
      parameters:
      - name: X-Notyfi-ID-Token
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Notyfi-Id-Token
      - name: authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      - name: x-api-key
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Api-Key
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BillingCheckoutCreate'
      responses:
        '201':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BillingCheckoutSession'
        '401':
          description: Missing or invalid Cognito access token.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: API keys cannot manage a human billing account.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '409':
          description: Account identity or billing-state conflict.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Rate limit exceeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '503':
          description: Stripe is unavailable or not configured.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/billing/portal:
    post:
      tags:
      - billing
      summary: Create a short-lived Stripe Customer Portal session
      operationId: billing_portal_api_v1_billing_portal_post
      parameters:
      - name: X-Notyfi-ID-Token
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Notyfi-Id-Token
      - name: authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      - name: x-api-key
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Api-Key
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BillingPortalSession'
        '401':
          description: Missing or invalid Cognito access token.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: API keys cannot manage a human billing account.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '409':
          description: Account identity or billing-state conflict.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Rate limit exceeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '503':
          description: Stripe is unavailable or not configured.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    NotyfiNotificationEmailInfo:
      properties:
        id:
          type: integer
          title: Id
        email:
          type: string
          title: Email
        enabled:
          type: boolean
          title: Enabled
          default: true
        verified:
          type: boolean
          title: Verified
          default: false
        primary:
          type: boolean
          title: Primary
          default: false
        verification_expires_at:
          anyOf:
          - type: string
          - type: 'null'
          title: Verification Expires At
      type: object
      required:
      - id
      - email
      title: NotyfiNotificationEmailInfo
    ErrorBody:
      properties:
        code:
          type: string
          title: Code
          description: Stable machine-readable error code.
        message:
          type: string
          title: Message
          description: Human-readable detail.
        request_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Request Id
          description: Correlation id, when available.
      type: object
      required:
      - code
      - message
      title: ErrorBody
    BillingUsage:
      properties:
        active_trackers:
          type: integer
          title: Active Trackers
          default: 0
        creations_last_24h:
          type: integer
          title: Creations Last 24H
          default: 0
      type: object
      title: BillingUsage
    BillingPortalSession:
      properties:
        url:
          type: string
          title: Url
      type: object
      required:
      - url
      title: BillingPortalSession
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    BillingCheckoutCreate:
      properties:
        plan:
          $ref: '#/components/schemas/BillingPlan'
          default: pro
      type: object
      title: BillingCheckoutCreate
      description: 'Start hosted Checkout for the one public paid plan.


        The client chooses a logical plan, never a Stripe Price ID or redirect URL; both are server-owned.'
    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
    NotyfiWorkspaceFolder:
      properties:
        id:
          type: string
          maxLength: 64
          minLength: 1
          pattern: ^[A-Za-z0-9][A-Za-z0-9_-]*$
          title: Id
        name:
          type: string
          maxLength: 80
          minLength: 1
          title: Name
        tracker_ids:
          items:
            type: string
          type: array
          maxItems: 500
          title: Tracker Ids
      additionalProperties: false
      type: object
      required:
      - id
      - name
      title: NotyfiWorkspaceFolder
    NotyfiWorkspace:
      properties:
        folders:
          items:
            $ref: '#/components/schemas/NotyfiWorkspaceFolder'
          type: array
          maxItems: 100
          title: Folders
        tracker_labels:
          additionalProperties:
            type: string
          type: object
          title: Tracker Labels
      additionalProperties: false
      type: object
      title: NotyfiWorkspace
    NotyfiAccountInfo:
      properties:
        tenant_id:
          type: integer
          title: Tenant Id
        email:
          anyOf:
          - type: string
          - type: 'null'
          title: Email
        email_verified:
          type: boolean
          title: Email Verified
          default: false
        display_name:
          anyOf:
          - type: string
          - type: 'null'
          title: Display Name
        workspace_revision:
          type: integer
          minimum: 0.0
          title: Workspace Revision
          default: 0
        workspace:
          $ref: '#/components/schemas/NotyfiWorkspace'
        notification_emails:
          items:
            $ref: '#/components/schemas/NotyfiNotificationEmailInfo'
          type: array
          title: Notification Emails
      type: object
      required:
      - tenant_id
      title: NotyfiAccountInfo
      description: 'The consumer identity bound to the access-token subject.


        ``email`` is populated only from a separately verified, same-sub Cognito ID token.  It is never

        accepted from an ordinary request body or copied back from Stripe.'
    BillingPlan:
      type: string
      enum:
      - free
      - pro
      - enterprise
      title: BillingPlan
    Error:
      properties:
        error:
          $ref: '#/components/schemas/ErrorBody'
      type: object
      required:
      - error
      title: Error
      description: The single error response shape for every 4xx/5xx on the contract.
      example:
        error:
          code: not_found
          message: lead not found
    BillingCheckoutSession:
      properties:
        url:
          type: string
          title: Url
        expires_at:
          anyOf:
          - type: string
          - type: 'null'
          title: Expires At
      type: object
      required:
      - url
      title: BillingCheckoutSession
    BillingStatus:
      properties:
        plan:
          $ref: '#/components/schemas/BillingPlan'
        subscription_status:
          anyOf:
          - type: string
          - type: 'null'
          title: Subscription Status
        cancel_at_period_end:
          type: boolean
          title: Cancel At Period End
          default: false
        current_period_end:
          anyOf:
          - type: string
          - type: 'null'
          title: Current Period End
        has_billing_customer:
          type: boolean
          title: Has Billing Customer
          default: false
        account:
          $ref: '#/components/schemas/NotyfiAccountInfo'
        limits:
          $ref: '#/components/schemas/BillingLimits'
        usage:
          $ref: '#/components/schemas/BillingUsage'
      type: object
      required:
      - plan
      - account
      - limits
      - usage
      title: BillingStatus
    BillingLimits:
      properties:
        max_active_trackers:
          anyOf:
          - type: integer
          - type: 'null'
          title: Max Active Trackers
          description: Tracker cap for this plan; null means contract-defined/unlimited Enterprise.
        max_tracker_creations_24h:
          anyOf:
          - type: integer
          - type: 'null'
          title: Max Tracker Creations 24H
          description: Rolling 24-hour creation cap; null means contract-defined/unlimited Enterprise.
        allowed_cadences:
          items:
            $ref: '#/components/schemas/BillingCadence'
          type: array
          title: Allowed Cadences
      type: object
      required:
      - max_active_trackers
      - max_tracker_creations_24h
      - allowed_cadences
      title: BillingLimits
    BillingCadence:
      type: string
      enum:
      - instant
      - hourly
      - daily
      - weekly
      title: BillingCadence
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: 'Notyfi API key: `Authorization: Bearer notyfi_mk_...`'
    apiKeyAuth:
      type: apiKey
      in: header
      name: X-Api-Key
      description: Notyfi API key as X-Api-Key.