BillDog API

openapi: 3.1.0
info:
  title: BillDog API
  version: '2026-11-02'
  description: 'GENERATED FROM DOCUMENTATION by API Evangelist on 2026-11-02: 41 operation(s) read from 13 public documentation page(s) (each
    operation names its page in x-source). This is not the provider''s published contract; BillDog has published no machine-readable contract
    that the pipeline could find. Engine: local.'
  x-evidence-tiers:
    code-example: 2
    documentation: 39
    pages-with-code: 6
    pages-read: 13
  x-generated-from: documentation
  x-provenance: generated
  x-authored-by: API Evangelist
  x-generated: '2026-11-02'
  x-generator: generate-contract-from-docs.py
  x-engine: local
  x-sources:
  - https://billdog.io/docs/auth/api-reference
  - https://billdog.io/docs/auth/api-reference.md
  - https://billdog.io/docs/ios
  - https://billdog.io/docs/web
  - https://billdog.io/docs/cli.md
  - https://billdog.io/docs/ios.md
  - https://billdog.io/docs/web.md
  - https://billdog.io/docs/android
  - https://billdog.io/docs/android.md
  - https://billdog.io/docs/product-analytics
  - https://billdog.io/docs/product-analytics.md
  - https://billdog.io/docs/cli
  - https://billdog.io/docs/web-checkout
servers:
- url: https://api.billdog.io
paths:
  /auth-account:
    post:
      operationId: post_auth_account
      tags:
      - Auth Account
      summary: The signed-in user's own account view
      x-source: https://billdog.io/docs/auth/api-reference
      responses:
        '201':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /auth-attempt:
    post:
      operationId: post_auth_attempt
      tags:
      - Auth Attempt
      summary: Submit a factor. identifier is required for a first factor and optional for totp / backup_code , where mfa_token names the account
      x-source: https://billdog.io/docs/auth/api-reference
      responses:
        '201':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /auth-config:
    post:
      operationId: post_auth_config
      tags:
      - Auth Config
      summary: What this project requires before a sign-up is accepted
      x-source: https://billdog.io/docs/auth/api-reference
      responses:
        '201':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /auth-impersonate:
    post:
      operationId: post_auth_impersonate
      tags:
      - Auth Impersonate
      summary: Act as a user, for support
      x-source: https://billdog.io/docs/auth/api-reference
      responses:
        '201':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /auth-import:
    post:
      operationId: post_auth_import
      tags:
      - Auth Import
      summary: Import users from Clerk, Auth0 or Firebase
      x-source: https://billdog.io/docs/auth/api-reference
      responses:
        '201':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /auth-introspect:
    post:
      operationId: post_auth_introspect
      tags:
      - Auth Introspect
      summary: Is this token live right now?
      x-source: https://billdog.io/docs/auth/api-reference
      responses:
        '201':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /auth-jwks:
    get:
      operationId: get_auth_jwks
      tags:
      - Auth Jwks
      summary: Public keys for offline verification
      x-source: https://billdog.io/docs/auth/api-reference
      responses:
        '200':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /auth-oauth-bounce:
    post:
      operationId: post_auth_oauth_bounce
      tags:
      - Auth Oauth Bounce
      summary: Where a provider returns to — Apple's form POST, and every native flow — before being forwarded to where the flow began. Registered
        with the provider once; not called by your code
      x-source: https://billdog.io/docs/auth/api-reference
      responses:
        '201':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /auth-oauth-callback:
    post:
      operationId: post_auth_oauth_callback
      tags:
      - Auth Oauth Callback
      summary: Complete a redirect sign-in. Answers mfa_required + mfa_token with no session for an MFA-enrolled account, exactly like auth-attempt
      x-source: https://billdog.io/docs/auth/api-reference
      responses:
        '201':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /auth-oauth-start:
    post:
      operationId: post_auth_oauth_start
      tags:
      - Auth Oauth Start
      summary: Begin a redirect sign-in (PKCE)
      x-source: https://billdog.io/docs/auth/api-reference
      responses:
        '201':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /auth-oauth-verify:
    post:
      operationId: post_auth_oauth_verify
      tags:
      - Auth Oauth Verify
      summary: Exchange a provider ID token for a session
      x-source: https://billdog.io/docs/auth/api-reference
      responses:
        '201':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /auth-org:
    post:
      operationId: post_auth_org
      tags:
      - Auth Org
      summary: Organizations, members, invitations and domains
      x-source: https://billdog.io/docs/auth/api-reference
      responses:
        '201':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /auth-passkey:
    post:
      operationId: post_auth_passkey
      tags:
      - Auth Passkey
      summary: WebAuthn registration and sign-in
      x-source: https://billdog.io/docs/auth/api-reference
      responses:
        '201':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /auth-prepare:
    post:
      operationId: post_auth_prepare
      tags:
      - Auth Prepare
      summary: Send a one-time code
      x-source: https://billdog.io/docs/auth/api-reference
      responses:
        '201':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /auth-provision-keys:
    post:
      operationId: post_auth_provision_keys
      tags:
      - Auth Provision Keys
      summary: Provision or rotate signing keys
      x-source: https://billdog.io/docs/auth/api-reference
      responses:
        '201':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /auth-revoke:
    post:
      operationId: post_auth_revoke
      tags:
      - Auth Revoke
      summary: Sign out
      x-source: https://billdog.io/docs/auth/api-reference
      responses:
        '201':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /auth-sessions:
    post:
      operationId: post_auth_sessions
      tags:
      - Auth Sessions
      summary: List a user's sessions
      x-source: https://billdog.io/docs/auth/api-reference
      responses:
        '201':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /auth-set-password:
    post:
      operationId: post_auth_set_password
      tags:
      - Auth Set Password
      summary: Set a password — by reset code, or as a signed-in change
      x-source: https://billdog.io/docs/auth/api-reference
      responses:
        '201':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /auth-sign-up:
    post:
      operationId: post_auth_sign_up
      tags:
      - Auth Sign Up
      summary: Begin a sign-up
      x-source: https://billdog.io/docs/auth/api-reference
      responses:
        '201':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /auth-sso-acs/{connectionId}:
    post:
      operationId: post_auth_sso_acs_connectionId
      tags:
      - Auth Sso Acs
      summary: SAML assertion consumer service
      x-source: https://billdog.io/docs/auth/api-reference
      parameters:
      - name: connectionId
        in: path
        required: true
        schema:
          type: string
      responses:
        '201':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /auth-sso-acs/{connectionId}/metadata:
    get:
      operationId: get_auth_sso_acs_connectionId_metadata
      tags:
      - Auth Sso Acs
      summary: SP metadata for the IdP
      x-source: https://billdog.io/docs/auth/api-reference
      parameters:
      - name: connectionId
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /auth-sso-callback:
    post:
      operationId: post_auth_sso_callback
      tags:
      - Auth Sso Callback
      summary: Complete an OIDC enterprise sign-in
      x-source: https://billdog.io/docs/auth/api-reference
      responses:
        '201':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /auth-sso-start:
    post:
      operationId: post_auth_sso_start
      tags:
      - Auth Sso Start
      summary: Route a work email to its enterprise connection
      x-source: https://billdog.io/docs/auth/api-reference
      responses:
        '201':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /auth-token:
    post:
      operationId: post_auth_token
      tags:
      - Auth Token
      summary: Refresh a session
      x-source: https://billdog.io/docs/auth/api-reference
      responses:
        '201':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /auth-user-factors:
    post:
      operationId: post_auth_user_factors
      tags:
      - Auth User Factors
      summary: Manage second factors
      x-source: https://billdog.io/docs/auth/api-reference
      responses:
        '201':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /functions/v1/create-web-checkout:
    post:
      operationId: post_functions_v1_create_web_checkout
      tags:
      - Functions
      summary: Create Checkout Session (API)
      x-source: https://billdog.io/docs/web-checkout
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostFunctionsV1CreateWebCheckoutRequest'
      responses:
        '201':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostFunctionsV1CreateWebCheckoutResponse'
      x-evidence:
        kind: documentation
  /functions/v1/redeem-purchase:
    post:
      operationId: post_functions_v1_redeem_purchase
      tags:
      - Functions
      summary: Redeem Purchase
      x-source: https://billdog.io/docs/web-checkout
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostFunctionsV1RedeemPurchaseRequest'
      responses:
        '201':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostFunctionsV1RedeemPurchaseResponse'
      x-evidence:
        kind: documentation
  /health-check:
    get:
      operationId: get_health_check
      tags:
      - Health Check
      summary: API reachability check
      x-source: https://billdog.io/docs/cli.md
      responses:
        '200':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /manage-auth-settings:
    post:
      operationId: post_manage_auth_settings
      tags:
      - Manage Auth Settings
      summary: Project auth settings, SSO connections, SCIM tokens and signing keys
      x-source: https://billdog.io/docs/auth/api-reference
      responses:
        '201':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /manage-jwt-templates:
    post:
      operationId: post_manage_jwt_templates
      tags:
      - Manage Jwt Templates
      summary: JWT templates, programmatically
      x-source: https://billdog.io/docs/auth/api-reference
      responses:
        '201':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /scim-v2/Groups:
    get:
      operationId: get_scim_v2_Groups
      tags:
      - Scim V2
      summary: List directory groups
      x-source: https://billdog.io/docs/auth/api-reference
      responses:
        '200':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /scim-v2/ServiceProviderConfig:
    get:
      operationId: get_scim_v2_ServiceProviderConfig
      tags:
      - Scim V2
      summary: Advertised SCIM capabilities
      x-source: https://billdog.io/docs/auth/api-reference
      responses:
        '200':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /scim-v2/Users:
    get:
      operationId: get_scim_v2_Users
      tags:
      - Scim V2
      summary: List or filter provisioned users
      x-source: https://billdog.io/docs/auth/api-reference
      responses:
        '200':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
    post:
      operationId: post_scim_v2_Users
      tags:
      - Scim V2
      summary: Provision a user
      x-source: https://billdog.io/docs/auth/api-reference
      responses:
        '201':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /scim-v2/Users/{id}:
    delete:
      operationId: delete_scim_v2_Users_id
      tags:
      - Scim V2
      summary: Deprovision a user
      x-source: https://billdog.io/docs/auth/api-reference
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
    patch:
      operationId: patch_scim_v2_Users_id
      tags:
      - Scim V2
      summary: Update or deactivate a user
      x-source: https://billdog.io/docs/auth/api-reference
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /v1/create-stripe-portal-session:
    post:
      operationId: post_v1_create_stripe_portal_session
      tags:
      - Create Stripe Portal Session
      summary: Your server calls POST /v1/create-stripe-portal-session with the secret key to create a billing portal session.
      x-source: https://billdog.io/docs/web
      responses:
        '201':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /v1/ingest-events:
    post:
      operationId: post_v1_ingest_events
      tags:
      - Ingest Events
      summary: POST /v1/ingest-events
      x-source: https://billdog.io/docs/product-analytics
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostV1IngestEventsRequest'
      responses:
        '201':
          description: Success (status as documented)
      x-evidence:
        kind: code-example
        language: curl
        snippet: "curl (plain JSON) Field mapping reference Gzip batch curl -X POST https://api.billdog.io/v1/ingest-events  -H \"Content-Type:\
          \ application/json\"  -H \"X-BillDog-API-Key: bd_public_test_yourApiKey\"  -d '{\n \"api_key\": \"bd_public_test_yourApiKey\",\n \"\
          platform\": \"web\",\n \"sdk_version\": \"1.0.0\",\n \"events\": [\n {\n \"name\": \"checkout_completed\",\n \"timestamp\": 1718800000000,\n\
          \ \"session_id\": \"sess_abc\",\n \"anonymou"
  /v1/record-external-purchase:
    post:
      operationId: post_v1_record_external_purchase
      tags:
      - Record External Purchase
      summary: Record them from your server with your secret key ( POST /v1/record-external-purchase ).
      x-source: https://billdog.io/docs/ios
      responses:
        '201':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /v1/virtual-currency/transactions:
    post:
      operationId: post_v1_virtual_currency_transactions
      tags:
      - Virtual Currency
      summary: POST /v1/virtual-currency/transactions
      x-source: https://billdog.io/docs/ios
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostV1VirtualCurrencyTransactionsRequest'
      responses:
        '201':
          description: Success (status as documented)
      x-evidence:
        kind: code-example
        language: curl
        snippet: "curl -X POST https://api.billdog.io/v1/virtual-currency/transactions  -H \"X-BillDog-API-Key: $BILLDOG_SECRET_KEY\"  -H \"Content-Type:\
          \ application/json\"  -d '{\n \"app_user_id\": \"user_uuid_123\",\n \"currency_id\": \"YOUR_CURRENCY_ID\",\n \"amount\": 100,\n \"type\"\
          : \"GRANT\",\n \"reason\": \"onboarding_reward\"\n }' app_user_id is the id you passed to identify . The answer carries the new balance.\
          \ \U0001F510 Authentication (Bil"
  /validate-api-key:
    post:
      operationId: post_validate_api_key
      tags:
      - Validate Api Key
      summary: Validates your API key
      x-source: https://billdog.io/docs/cli.md
      responses:
        '201':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
components:
  schemas:
    PostFunctionsV1CreateWebCheckoutRequest:
      type: object
      properties:
        source:
          type: string
          description: app_to_web | web_paywall
        product_id:
          type: string
          description: products.id, or the product_identifier
        success_url:
          type: string
          description: required for web_paywall; app_to_web defaults to the app's scheme
        cancel_url:
          type: string
        app_user_id:
          type: string
          description: a secret key names its customer with this (or customer_id)
        region:
          type: string
          description: ISO 3166-1 alpha-2; required when the project gates web checkout by region
        platform:
          type: string
        gateway:
          type: string
          description: optional; Stripe is the only merchant gateway
        placement_id:
          type: string
          description: optional attribution
        metadata:
          type: object
          description: optional, string values
    PostFunctionsV1CreateWebCheckoutResponse:
      type: object
      properties:
        success:
          type: boolean
        data:
          type: object
          description: Stripe response data
        data.kind:
          type: string
        data.url:
          type: string
        data.session_id:
          type: string
        data.pending_checkout_id:
          type: string
        data.redemption_token:
          type: string
          description: 'app_to_web only: pre-linked to this checkout, valid 7 days'
        meta:
          type: object
        meta.request_id:
          type: string
        meta.api_version:
          type: string
        meta.timestamp:
          type: string
    PostFunctionsV1RedeemPurchaseRequest:
      type: object
      properties:
        token:
          type: string
          description: token-from-the-return-link
      required:
      - token
    PostFunctionsV1RedeemPurchaseResponse:
      type: object
      properties:
        success:
          type: boolean
        data:
          type: object
        data.redeemed:
          type: boolean
        data.customer_id:
          type: string
        data.product:
          type: object
        data.product.id:
          type: string
        data.product.identifier:
          type: string
        data.product.name:
          type: string
        data.product.type:
          type: string
        data.entitlements:
          type: array
          description: list of entitlements
        data.entitlements[].id:
          type: string
        data.entitlements[].identifier:
          type: string
        data.entitlements[].name:
          type: string
        data.subscription:
          type: object
        data.subscription.stripe_subscription_id:
          type: string
        data.subscription.current_period_end:
          type: string
        meta:
          type: object
        meta.request_id:
          type: string
    PostV1IngestEventsRequest:
      type: object
      properties:
        api_key:
          type: string
        platform:
          type: string
        sdk_version:
          type: string
        events:
          type: array
          items:
            type: object
            properties:
              name:
                type: string
              timestamp:
                type: integer
              session_id:
                type: string
              anonymous_id:
                type: string
              properties:
                type: object
                properties:
                  $user_id:
                    type: string
                  amount:
                    type: number
                  $currency:
                    type: string
                  $insert_id:
                    type: string
    PostV1VirtualCurrencyTransactionsRequest:
      type: object
      properties:
        app_user_id:
          type: string
        currency_id:
          type: string
        amount:
          type: integer
        type:
          type: string
        reason:
          type: string
  securitySchemes:
    apiKey:
      type: apiKey
      in: header
      name: X-BillDog-API-Key
security:
- apiKey: []
tags:
- name: Auth Account
- name: Auth Attempt
- name: Auth Config
- name: Auth Impersonate
- name: Auth Import
- name: Auth Introspect
- name: Auth Jwks
- name: Auth Oauth Bounce
- name: Auth Oauth Callback
- name: Auth Oauth Start
- name: Auth Oauth Verify
- name: Auth Org
- name: Auth Passkey
- name: Auth Prepare
- name: Auth Provision Keys
- name: Auth Revoke
- name: Auth Sessions
- name: Auth Set Password
- name: Auth Sign Up
- name: Auth Sso Acs
- name: Auth Sso Callback
- name: Auth Sso Start
- name: Auth Token
- name: Auth User Factors
- name: Create Stripe Portal Session
- name: Functions
- name: Health Check
- name: Ingest Events
- name: Manage Auth Settings
- name: Manage Jwt Templates
- name: Record External Purchase
- name: Scim V2
- name: Validate Api Key
- name: Virtual Currency