Auxen Scheduling API

openapi: 3.2.0
info:
  title: Auxen Headless Scheduling 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: Scheduling
paths:
  /v1/deployments/{deploymentId}/pause:
    post:
      summary: Pause a deployment
      description: Stops active-time billing immediately. The model and knowledge base are kept for resume.
      tags:
      - Scheduling
      security:
      - AgentKey: []
      parameters:
      - name: deploymentId
        in: path
        required: true
        schema:
          type: string
          pattern: ^inst_[0-9a-f]+$
        example: inst_07d7eab4fabc
      responses:
        '200':
          description: 'OK — `status: paused`.'
        '400':
          description: Not ready.
      operationId: postV1DeploymentsByDeploymentIdPause
      x-operation-id-source: derived
  /v1/deployments/{deploymentId}/resume:
    post:
      summary: Resume a paused deployment
      description: Returns 202 with `ready_at` estimate (about 3 minutes of warm-up). Poll `GET /v1/deployments/{deploymentId}` or subscribe to `deployment.resumed`. Idempotent on a ready deployment.
      tags:
      - Scheduling
      security:
      - AgentKey: []
      parameters:
      - name: deploymentId
        in: path
        required: true
        schema:
          type: string
          pattern: ^inst_[0-9a-f]+$
        example: inst_07d7eab4fabc
      responses:
        '200':
          description: Already ready.
        '202':
          description: Warming up.
      operationId: postV1DeploymentsByDeploymentIdResume
      x-operation-id-source: derived
  /v1/deployments/{deploymentId}/schedule:
    get:
      summary: Get a deployment's schedule
      tags:
      - Scheduling
      security:
      - AgentKey: []
      parameters:
      - name: deploymentId
        in: path
        required: true
        schema:
          type: string
          pattern: ^inst_[0-9a-f]+$
        example: inst_07d7eab4fabc
      responses:
        '200':
          description: OK
      operationId: getV1DeploymentsByDeploymentIdSchedule
      x-operation-id-source: derived
    put:
      summary: Set a deployment's schedule
      tags:
      - Scheduling
      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
              required:
              - mode
              properties:
                mode:
                  enum:
                  - always_on
                  - business_hours
                  - as_needed
                config:
                  type: object
      responses:
        '200':
          description: OK
      operationId: putV1DeploymentsByDeploymentIdSchedule
      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.