openapi: 3.1.0
info:
  title: CallOnline API
  version: 0.1.0
servers:
  - url: https://callonline.app
paths:
  /v1/calls:
    post:
      operationId: placeCall
      summary: Place an outbound AI voice call
      description: Runs compliance preflight before any future dial attempt. Missing consent, stale DNC attestation, quiet-hours violations, or entity DNC matches return 403.
      responses:
        "201":
          description: Call accepted and dialed through Telnyx
        "403":
          description: Compliance blocked
        "503":
          description: Telnyx dialing configuration missing
  /v1/calls/{callId}:
    get:
      operationId: getCall
      summary: Get call status
      parameters:
        - name: callId
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Call status and audit events
        "404":
          description: Call not found
  /v1/calls/{callId}/cancel:
    post:
      operationId: cancelCall
      summary: Cancel an outbound AI voice call
      parameters:
        - name: callId
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Cancel request accepted
        "404":
          description: Call not found
  /v1/voices:
    get:
      operationId: listVoices
      summary: List available CallOnline voice tiers
      responses:
        "200":
          description: Voice tier list
  /v1/pricing:
    get:
      operationId: getCallOnlinePricing
      summary: Get App9 Account-derived CallOnline pricing
      description: Returns bundled connected-minute pricing calculated from App9 credit packages and CallOnline rate-card rows.
      responses:
        "200":
          description: Dynamic pricing, credit packages, and generic market benchmark
        "502":
          description: App9 Account pricing source is temporarily unavailable
  /v1/agent-commerce/plans:
    get:
      operationId: listAgentCommercePlans
      summary: List App9 credit plans available for agent commerce
      responses:
        "200":
          description: Agent commerce plans
  /v1/agent-commerce/stripe:
    get:
      operationId: getStripeAgentCommerceCapabilities
      summary: Get Stripe agent-commerce capabilities for CallOnline
      description: Describes the current App9 Account Stripe Checkout bridge and future Stripe UCP/ACP/SPT plus MPP/x402 readiness for direct agent purchases.
      responses:
        "200":
          description: Stripe agent-commerce capability document
  /v1/agent-commerce/purchase-session:
    post:
      operationId: createAgentCommercePurchaseSession
      summary: Create a human-approved App9 checkout session for CallOnline usage
      description: Agents can request a purchase session, but a human must approve payment, terms, spend caps, and compliance obligations before calls can be placed.
      responses:
        "201":
          description: Purchase session created
        "403":
          description: Agent commerce disabled or API key lacks billing scope
        "503":
          description: App9 Account billing integration is not configured
  /v1/agent-commerce/direct-payment-session:
    post:
      operationId: createAgentCommerceDirectPaymentSession
      summary: Create an App9 Account direct agent-payment session for one-time credits
      description: Agents can request a direct-payment URL, then satisfy the App9 Account MPP Payment challenge with a Stripe Shared Payment Token. CallOnline never handles Stripe secrets or payment credentials.
      responses:
        "201":
          description: Direct payment session created
        "403":
          description: Agent commerce disabled or API key lacks billing scope
        "503":
          description: Direct agent payments are disabled or App9 Account is not configured
  /v1/agent-commerce/billing-status:
    get:
      operationId: getAgentCommerceBillingStatus
      summary: Check billing readiness for agent calling
      responses:
        "200":
          description: Billing readiness, credit balance, spend cap, and required next steps
  /v1/agent-commerce/usage-balance:
    get:
      operationId: getAgentCommerceUsageBalance
      summary: Get the App9 credit balance for the current CallOnline account
      responses:
        "200":
          description: App9 credit balance
  /v1/webhooks:
    get:
      operationId: listWebhooks
      summary: List outbound webhook subscriptions
      responses:
        "200":
          description: Webhook subscription list
    post:
      operationId: createWebhook
      summary: Create an outbound webhook subscription
      responses:
        "201":
          description: Webhook subscription created
  /v1/webhooks/{webhookId}:
    delete:
      operationId: deleteWebhook
      summary: Delete an outbound webhook subscription
      parameters:
        - name: webhookId
          in: path
          required: true
          schema:
            type: integer
      responses:
        "200":
          description: Webhook subscription deleted