Auxen Billing API

openapi: 3.2.0
info:
  title: Auxen Headless Billing API
  version: 1.3.0
  description: 'Programmatic API for Auxen: hire and manage AI workers (`/v1/workers`,

    `/v1/connections`, approvals; also over MCP and A2A), and deploy and

    manage private open-weight model endpoints. Anything a human can do in

    the dashboard, an agent can do via this API.


    **Two key types:**

    - `auxen_live_…` / `auxen_test_…` — your account-level **agent management**

    key. Authorizes deploying, switching models, and billing operations.

    - `auxk_…` — a per-deployment **inference** key returned in the `api_key`

    field of every deployment object. Authorizes inference calls on that

    deployment only. Hand it to downstream services without giving up

    management rights.


    **Billing:**

    All Auxen deployments are billed **pay-as-you-go** from a prepaid USD credit

    balance, per minute of active time; billing stops when a deployment is

    paused or deleted. Throughput levels (Standard, Double, Quad, Max)

    increase simultaneous request handling at the same model quality. Top up

    the balance with `POST /v1/billing/add-credits`.


    **2026 renames:** `/v1/provision` → `/v1/deploy`, `/v1/instances` →

    `/v1/deployments`, `/scale` → `/throughput`, `/wake` → `/resume`.

    Old routes keep working until 2027-04-02 and send `Deprecation`,

    `Sunset`, and `Link` headers. Responses carry new and old field names

    side by side (`deployment_id` + `instance_id`, `throughput` +

    `capacity`, `rate_per_hour` + `hourly_rate`, `ready_estimate` +

    `estimated_ready_at`). Migration guide: https://auxen.ai/docs/api/migration'
  contact:
    email: hello@auxen.ai
    url: https://auxen.ai/contact
servers:
- url: https://api.auxen.ai
  description: Production
tags:
- name: Billing
paths:
  /v1/deployments/{deploymentId}/spending-cap:
    patch:
      summary: Set or clear a per-deployment spending cap
      tags:
      - Billing
      security:
      - AgentKey: []
      parameters:
      - name: deploymentId
        in: path
        required: true
        schema:
          type: string
          pattern: ^inst_[0-9a-f]+$
        example: inst_07d7eab4fabc
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                cap_usd:
                  type: number
                  nullable: true
                  description: USD cap. When accumulated_cost crosses it, the deployment is suspended. Pass null to clear.
      responses:
        '200':
          description: OK
      operationId: patchV1DeploymentsByDeploymentIdSpendingCap
      x-operation-id-source: derived
  /v1/billing/balance:
    get:
      summary: Get account billing snapshot
      tags:
      - Billing
      security:
      - AgentKey: []
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    const: true
                  data:
                    type: object
                    properties:
                      credits:
                        type: object
                        properties:
                          balance:
                            type: number
                          currency:
                            const: USD
                      subscriptions:
                        type: object
                        properties:
                          active_count:
                            type: integer
                          monthly_total:
                            type: number
                      on_demand:
                        type: object
                        properties:
                          active_deployments:
                            type: integer
                          active_instances:
                            type: integer
                            deprecated: true
                            description: Deprecated alias of `active_deployments`; returned until 2027-04-02.
                          month_to_date:
                            type: number
                  meta:
                    $ref: '#/components/schemas/Meta'
                required:
                - success
                - data
                - meta
      operationId: getV1BillingBalance
      x-operation-id-source: derived
  /v1/billing/add-credits:
    post:
      summary: Top up USD credits
      description: Returns a Stripe Checkout URL. Open it in a browser to complete payment; the balance updates after the webhook fires. Minimum $10, maximum $10,000 per checkout.
      tags:
      - Billing
      security:
      - AgentKey: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - amount
              properties:
                amount:
                  type: number
                  minimum: 10
                  maximum: 10000
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    const: true
                  data:
                    type: object
                    properties:
                      checkout_url:
                        type: string
                        format: uri
                      session_id:
                        type: string
                      amount_usd:
                        type: number
                  meta:
                    $ref: '#/components/schemas/Meta'
                required:
                - success
                - data
                - meta
        '400':
          description: Amount out of bounds.
      operationId: postV1BillingAddCredits
      x-operation-id-source: derived
  /v1/billing/auto-recharge:
    get:
      summary: Read auto-recharge settings
      tags:
      - Billing
      security:
      - AgentKey: []
      responses:
        '200':
          description: OK
      operationId: getV1BillingAutoRecharge
      x-operation-id-source: derived
    patch:
      summary: Update auto-recharge settings
      description: Requires a saved Stripe payment method (collected on the first POST /v1/billing/add-credits Checkout completion).
      tags:
      - Billing
      security:
      - AgentKey: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                enabled:
                  type: boolean
                threshold_usd:
                  type: number
                amount_usd:
                  type: number
                max_monthly_usd:
                  type: number
      responses:
        '200':
          description: OK
      operationId: patchV1BillingAutoRecharge
      x-operation-id-source: derived
components:
  schemas:
    Meta:
      type: object
      properties:
        requestId:
          type: string
          example: req_abcdef0123456789
        timestamp:
          type: string
          format: date-time
  securitySchemes:
    AgentKey:
      type: http
      scheme: bearer
      bearerFormat: auxen_live_xxx | auxen_test_xxx
      description: Account-level key. Generate at /dashboard/api-keys.
    DeploymentKey:
      type: http
      scheme: bearer
      bearerFormat: auxk_xxx
      description: Per-deployment key from the `api_key` field of a deployment object.