Auxen Webhooks API

openapi: 3.2.0
info:
  title: Auxen Headless Webhooks 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: Webhooks
paths:
  /v1/webhooks:
    get:
      summary: List registered webhooks
      tags:
      - Webhooks
      security:
      - AgentKey: []
      responses:
        '200':
          description: OK
      operationId: getV1Webhooks
      x-operation-id-source: derived
    post:
      summary: Register a webhook
      description: 'Returns the webhook record + a one-time `secret` (HMAC-SHA256 over the raw body, header `x-auxen-signature: sha256=…`). Each delivery includes a unique `delivery_id` for replay protection. Deliveries carry the event name you subscribed with in `event` and the `X-Auxen-Event` header. Pre-2026 event names remain valid until 2027-04-02 (listed as deprecated in the schema); the migration guide maps each to its deployment.* name: https://auxen.ai/docs/api/migration'
      tags:
      - Webhooks
      security:
      - AgentKey: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - url
              - events
              properties:
                url:
                  type: string
                  format: uri
                events:
                  type: array
                  items:
                    anyOf:
                    - enum:
                      - deployment.ready
                      - deployment.error
                      - deployment.deleted
                      - deployment.throughput_changed
                      - deployment.relocated
                      - deployment.suspended
                      - deployment.resumed
                      - deployment.idle
                      - deployment.paused
                      - deployment.warming
                      - deployment.schedule_changed
                      - billing.low_credits
                      - billing.auto_recharge_succeeded
                      - billing.auto_recharge_failed
                      - billing.spending_limit_alert
                      - knowledge_base.indexed
                      - model.update_available
                    - enum:
                      - instance.ready
                      - instance.error
                      - instance.destroyed
                      - instance.auto_scaled
                      - instance.host_migrated
                      - instance.suspended
                      - instance.resumed
                      - instance.idle
                      - instance.paused
                      - instance.warming
                      - instance.schedule_changed
                      deprecated: true
                      description: Pre-2026 event names; accepted until 2027-04-02.
                secret:
                  type: string
      responses:
        '201':
          description: Created
      operationId: postV1Webhooks
      x-operation-id-source: derived
  /v1/webhooks/{webhookId}:
    delete:
      summary: Delete a webhook
      tags:
      - Webhooks
      security:
      - AgentKey: []
      parameters:
      - name: webhookId
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK
      operationId: deleteV1WebhooksByWebhookId
      x-operation-id-source: derived
  /v1/webhooks/{webhookId}/deliveries:
    get:
      summary: List recent webhook deliveries
      tags:
      - Webhooks
      security:
      - AgentKey: []
      parameters:
      - name: webhookId
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK
      operationId: getV1WebhooksByWebhookIdDeliveries
      x-operation-id-source: derived
  /v1/webhooks/{webhookId}/test:
    post:
      summary: Fire a test delivery
      description: Sends a synthetic event. Defaults to the first event name the webhook subscribes to.
      tags:
      - Webhooks
      security:
      - AgentKey: []
      parameters:
      - name: webhookId
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Delivered or queued for retry.
      operationId: postV1WebhooksByWebhookIdTest
      x-operation-id-source: derived
components:
  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.