Auxen Workers API
The Workers API from Auxen — 16 operation(s) for workers.
Work with this as data
Every API here is available over the APIs.io API and to AI agents over MCP.
MCP server
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
Tools for apis
7 MCP tools reach this
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.
Call it yourself
curl for this page
This API
curl "https://apis.io/api/v1/apis/auxen-ai:auxen-ai-workers-api"
All apis
curl "https://apis.io/api/v1/apis?limit=25"Discovery needs no key. Ratings and market analysis are Pro.
Get an API key
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
OpenAPI Specification
openapi: 3.2.0
info:
title: Auxen Headless Workers 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: Workers
paths:
/v1/workers:
post:
summary: Hire a worker
description: 'Hire a persistent, contained worker: a role (plain-language job description), a budget that moves from your balance into the worker, when it wakes, and the sites it may read. Spawn a sub-agent natively when the task is ephemeral — minutes, one answer, done. Hire a worker on Auxen when the job is a role: it runs for hours or days, it handles untrusted input, it needs its own budget cap, or it must keep working when you don''t. Cost: $0.90/hour while thinking + $0.10/hour while awake; idle is free. A test key hires a test worker (mock model, no charge).'
tags:
- Workers
security:
- AgentKey: []
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- role
- budget_usd
properties:
role:
type: string
minLength: 20
maxLength: 8000
budget_usd:
type: number
minimum: 1
maximum: 1000
schedule:
type: object
nullable: true
properties:
every_minutes:
type: integer
minimum: 5
maximum: 10080
wake_on_message:
type: boolean
default: true
tool_policy:
type: object
properties:
builtins:
type: array
items:
type: string
enum:
- fetch
- web_search
- run_code
- send_message
- read_memory
- write_memory
web_search:
description: true or { max_calls_per_wake } (1-20, default 10). $0.01 per search from the worker's budget.
oneOf:
- type: boolean
- type: object
properties:
max_calls_per_wake:
type: integer
minimum: 1
maximum: 20
code:
description: true or { max_runs_per_wake } (1-10, default 3). Python with no internet; $0.005 per run.
oneOf:
- type: boolean
- type: object
properties:
max_runs_per_wake:
type: integer
minimum: 1
maximum: 10
mcp_servers:
type: array
maxItems: 3
description: Tools on the account's connections. Every call asks the owner first unless the tool is in act_without_asking.
items:
type: object
required:
- connection_id
- tools
properties:
connection_id:
type: string
example: cn_0123456789ab
tools:
type: array
items:
type: string
example:
- gmail_send_email
act_without_asking:
type: array
items:
type: string
default: []
helpers:
description: true or { max_active (1-3), max_budget_usd (0.25-100) }. Helpers are paid from this worker's budget.
oneOf:
- type: boolean
- type: object
properties:
max_active:
type: integer
minimum: 1
maximum: 3
max_budget_usd:
type: number
minimum: 0.25
maximum: 100
fetch:
type: object
properties:
allowed_hosts:
type: array
items:
type: string
example:
- example.org
- '*.github.com'
max_calls_per_wake:
type: integer
minimum: 1
maximum: 20
max_bytes:
type: integer
minimum: 1024
maximum: 2097152
label:
type: string
maxLength: 80
webhook_url:
type: string
format: uri
description: https only.
webhook_secret:
type: string
minLength: 16
memory_seed:
type: string
maxLength: 4000
low_runway_pct:
type: integer
minimum: 1
maximum: 90
default: 20
notify:
type: object
description: Also send reports by email to the owner and/or to a Discord channel.
properties:
email:
type: boolean
discord_webhook_url:
type: string
format: uri
tier:
type: string
enum:
- balanced
default: balanced
example:
label: feed-monitor
role: Check the listed feeds each wake. When an item matches the rules in memory, message me once with the item and why it matched.
schedule:
every_minutes: 30
tool_policy:
fetch:
allowed_hosts:
- news.ycombinator.com
budget_usd: 10
memory_seed: 'Rules: report posts about open-weight model releases.'
responses:
'202':
description: Hired. `worker.worker_id`, `estimated_runway`, `rate_summary`; `webhook_secret` once if generated.
'400':
description: INVALID_TOOL_POLICY (with `field`), BUDGET_BELOW_MINIMUM, INVALID_REQUEST.
'402':
description: INSUFFICIENT_CREDITS (with `shortfall_usd`).
'403':
description: WORKER_LIMIT_REACHED or ACCOUNT_FROZEN.
'429':
description: HIRE_RATE_LIMITED.
operationId: postV1Workers
x-operation-id-source: derived
get:
summary: List workers
tags:
- Workers
security:
- AgentKey: []
parameters:
- name: status
in: query
schema:
type: string
enum:
- idle
- awake
- paused
- out_of_budget
- fired
- name: include_fired
in: query
schema:
type: boolean
responses:
'200':
description: OK
operationId: getV1Workers
x-operation-id-source: derived
/v1/workers/{workerId}:
get:
summary: Get a worker
description: Status, budget left, estimated runway, next wake, last wake summary, tool_policy as granted (connected tools under tool_policy.mcp_servers) and pending_approvals (actions waiting for the owner).
tags:
- Workers
security:
- AgentKey: []
parameters:
- name: workerId
in: path
required: true
description: Worker ID (wk_xxxxxxxxxxxx).
schema:
type: string
responses:
'200':
description: OK
'404':
description: WORKER_NOT_FOUND
operationId: getV1WorkersByWorkerId
x-operation-id-source: derived
patch:
summary: Change a worker
description: Send only the fields to change. Applies from the next wake. tool_policy replaces the whole policy (send the full new mcp_servers list; [] removes connected tools).
tags:
- Workers
security:
- AgentKey: []
parameters:
- name: workerId
in: path
required: true
description: Worker ID (wk_xxxxxxxxxxxx).
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
role:
type: string
minLength: 20
maxLength: 8000
label:
type: string
maxLength: 80
schedule:
type: object
nullable: true
properties:
every_minutes:
type: integer
minimum: 5
maximum: 10080
wake_on_message:
type: boolean
tool_policy:
type: object
properties:
builtins:
type: array
items:
type: string
enum:
- fetch
- web_search
- run_code
- send_message
- read_memory
- write_memory
web_search:
description: true or { max_calls_per_wake } (1-20, default 10). $0.01 per search from the worker's budget.
oneOf:
- type: boolean
- type: object
properties:
max_calls_per_wake:
type: integer
minimum: 1
maximum: 20
code:
description: true or { max_runs_per_wake } (1-10, default 3). Python with no internet; $0.005 per run.
oneOf:
- type: boolean
- type: object
properties:
max_runs_per_wake:
type: integer
minimum: 1
maximum: 10
mcp_servers:
type: array
maxItems: 3
description: Tools on the account's connections. Every call asks the owner first unless the tool is in act_without_asking.
items:
type: object
required:
- connection_id
- tools
properties:
connection_id:
type: string
example: cn_0123456789ab
tools:
type: array
items:
type: string
example:
- gmail_send_email
act_without_asking:
type: array
items:
type: string
default: []
helpers:
description: true or { max_active (1-3), max_budget_usd (0.25-100) }. Helpers are paid from this worker's budget.
oneOf:
- type: boolean
- type: object
properties:
max_active:
type: integer
minimum: 1
maximum: 3
max_budget_usd:
type: number
minimum: 0.25
maximum: 100
fetch:
type: object
properties:
allowed_hosts:
type: array
items:
type: string
example:
- example.org
- '*.github.com'
max_calls_per_wake:
type: integer
minimum: 1
maximum: 20
max_bytes:
type: integer
minimum: 1024
maximum: 2097152
webhook_url:
type: string
format: uri
nullable: true
webhook_secret:
type: string
minLength: 16
low_runway_pct:
type: integer
minimum: 1
maximum: 90
notify:
type: object
description: Also send reports by email to the owner and/or to a Discord channel.
properties:
email:
type: boolean
discord_webhook_url:
type: string
format: uri
responses:
'200':
description: OK
'400':
description: INVALID_TOOL_POLICY (with `field`, e.g. a connection or tool that isn't on the account), INVALID_REQUEST.
'404':
description: WORKER_NOT_FOUND
operationId: patchV1WorkersByWorkerId
x-operation-id-source: derived
delete:
summary: Fire a worker
description: Stops it for good and returns unspent budget to your balance (`refunded_usd`).
tags:
- Workers
security:
- AgentKey: []
parameters:
- name: workerId
in: path
required: true
description: Worker ID (wk_xxxxxxxxxxxx).
schema:
type: string
responses:
'200':
description: OK
'409':
description: WORKER_FIRED
operationId: deleteV1WorkersByWorkerId
x-operation-id-source: derived
/v1/workers/{workerId}/messages:
post:
summary: Message a worker
description: Read at its next wake; with wake_on_message, that wake starts about 30 seconds after the first message of a burst.
tags:
- Workers
security:
- AgentKey: []
parameters:
- name: workerId
in: path
required: true
description: Worker ID (wk_xxxxxxxxxxxx).
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- body
properties:
body:
type: string
maxLength: 8000
metadata:
type: object
responses:
'201':
description: Stored.
operationId: postV1WorkersByWorkerIdMessages
x-operation-id-source: derived
get:
summary: Read a worker's messages
tags:
- Workers
security:
- AgentKey: []
parameters:
- name: workerId
in: path
required: true
description: Worker ID (wk_xxxxxxxxxxxx).
schema:
type: string
- name: direction
in: query
schema:
type: string
enum:
- in
- out
- name: since
in: query
schema:
type: string
format: date-time
- name: limit
in: query
schema:
type: integer
maximum: 200
responses:
'200':
description: OK
operationId: getV1WorkersByWorkerIdMessages
x-operation-id-source: derived
/v1/workers/{workerId}/budget:
post:
summary: Top up or reclaim a worker's budget
tags:
- Workers
security:
- AgentKey: []
parameters:
- name: workerId
in: path
required: true
description: Worker ID (wk_xxxxxxxxxxxx).
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
add_usd:
type: number
reclaim_usd:
type: number
responses:
'200':
description: OK
'402':
description: INSUFFICIENT_CREDITS
operationId: postV1WorkersByWorkerIdBudget
x-operation-id-source: derived
/v1/workers/{workerId}/pause:
post:
summary: Pause a worker
tags:
- Workers
security:
- AgentKey: []
parameters:
- name: workerId
in: path
required: true
description: Worker ID (wk_xxxxxxxxxxxx).
schema:
type: string
responses:
'200':
description: OK
operationId: postV1WorkersByWorkerIdPause
x-operation-id-source: derived
/v1/workers/{workerId}/resume:
post:
summary: Resume a paused worker
tags:
- Workers
security:
- AgentKey: []
parameters:
- name: workerId
in: path
required: true
description: Worker ID (wk_xxxxxxxxxxxx).
schema:
type: string
responses:
'200':
description: OK
operationId: postV1WorkersByWorkerIdResume
x-operation-id-source: derived
/v1/workers/{workerId}/wake:
post:
summary: Wake an idle worker now
tags:
- Workers
security:
- AgentKey: []
parameters:
- name: workerId
in: path
required: true
description: Worker ID (wk_xxxxxxxxxxxx).
schema:
type: string
responses:
'200':
description: OK
'409':
description: WORKER_NOT_IDLE
operationId: postV1WorkersByWorkerIdWake
x-operation-id-source: derived
/v1/workers/{workerId}/runs:
get:
summary: A worker's wake log
tags:
- Workers
security:
- AgentKey: []
parameters:
- name: workerId
in: path
required: true
description: Worker ID (wk_xxxxxxxxxxxx).
schema:
type: string
- name: limit
in: query
schema:
type: integer
- name: before
in: query
schema:
type: string
format: date-time
responses:
'200':
description: OK
operationId: getV1WorkersByWorkerIdRuns
x-operation-id-source: derived
/v1/workers/{workerId}/runs/{runId}:
get:
summary: One wake, with its tool calls (secrets redacted)
tags:
- Workers
security:
- AgentKey: []
parameters:
- name: workerId
in: path
required: true
description: Worker ID (wk_xxxxxxxxxxxx).
schema:
type: string
- name: runId
in: path
required: true
schema:
type: string
responses:
'200':
description: OK
operationId: getV1WorkersByWorkerIdRunsByRunId
x-operation-id-source: derived
/v1/workers/{workerId}/approvals:
get:
summary: Actions a worker has asked to take
description: 'Newest first (up to 50). Each: approval_id (ap_…), connection_id, connection_name, tool, args (exactly as the worker asked), reason, status, result, note, created_at, expires_at, decided_at, done_at. Pending requests expire after 7 days.'
tags:
- Workers
security:
- AgentKey: []
parameters:
- name: workerId
in: path
required: true
description: Worker ID (wk_xxxxxxxxxxxx).
schema:
type: string
- name: status
in: query
schema:
type: string
enum:
- pending
- running
- done
- failed
- declined
- expired
responses:
'200':
description: '`approvals`: the list.'
'404':
description: WORKER_NOT_FOUND
operationId: getV1WorkersByWorkerIdApprovals
x-operation-id-source: derived
/v1/workers/{workerId}/approvals/{approvalId}:
post:
summary: Approve or decline a worker's action
description: Approving runs exactly the recorded arguments once and tells the worker the result. Requests expire after 7 days.
tags:
- Workers
security:
- AgentKey: []
parameters:
- name: workerId
in: path
required: true
description: Worker ID (wk_xxxxxxxxxxxx).
schema:
type: string
- name: approvalId
in: path
required: true
schema:
type: string
example: ap_0123456789ab
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- decision
properties:
decision:
type: string
enum:
- approve
- decline
note:
type: string
maxLength: 500
responses:
'200':
description: '`approval`: the updated record (done, failed or declined).'
'404':
description: APPROVAL_NOT_FOUND or WORKER_NOT_FOUND
'409':
description: 'APPROVAL_CLOSED: already decided or expired.'
operationId: postV1WorkersByWorkerIdApprovalsByApprovalId
x-operation-id-source: derived
/a2a:
post:
summary: A2A (Agent2Agent v1.0) JSON-RPC endpoint for workers
tags:
- Workers
security:
- AgentKey: []
description: 'JSON-RPC 2.0. A worker is an A2A Task (id = worker_id). `SendMessage` without a taskId hires a worker: send the job in plain words plus a budget (data part `{"budget_usd": 5}`); without a budget the reply asks for one and nothing is spent. Optional data fields mirror POST /v1/workers: role, every_minutes, allowed_hosts, web_search, label, connected_tools, notify. `SendMessage` with a taskId messages that worker; `GetTask`, `ListTasks`, `CancelTask` (fires and refunds). A worker that is paused, out of budget or waiting on an approval is TASK_STATE_INPUT_REQUIRED. No streaming or A2A push notifications (use webhook_url).'
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- jsonrpc
- method
- id
properties:
jsonrpc:
type: string
enum:
- '2.0'
id:
oneOf:
- type: string
- type: integer
method:
type: string
enum:
- SendMessage
- GetTask
- ListTasks
- CancelTask
params:
type: object
responses:
'200':
description: JSON-RPC result or error (Task or Message).
'401':
description: Missing or invalid key.
operationId: postA2a
x-operation-id-source: derived
/.well-known/agent-card.json:
get:
summary: A2A Agent Card (also served at /.well-known/agent.json and on auxen.ai)
tags:
- Workers
security: []
responses:
'200':
description: The public Agent Card.
operationId: getWellKnownAgentCardJson
x-operation-id-source: derived
/v1/connections:
get:
summary: The account's connected tool servers (no URLs or keys returned)
tags:
- Workers
security:
- AgentKey: []
responses:
'200':
description: OK
operationId: getV1Connections
x-operation-id-source: derived
post:
summary: Connect a tool server (MCP), e.g. Zapier
tags:
- Workers
security:
- AgentKey: []
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- name
- url
properties:
name:
type: string
url:
type: string
format: uri
api_key:
type: string
nullable: true
description: Auxen connects once to read the server's tool list. The URL and api_key are stored encrypted, never returned in any response, and never shown to a worker.
responses:
'201':
description: '`connection` with its tools.'
'400':
description: INVALID_REQUEST (with `field`)
'422':
description: 'CONNECTION_FAILED: couldn''t reach the server or it offers no tools.'
operationId: postV1Connections
x-operation-id-source: derived
/v1/connections/{connectionId}:
get:
summary: 'One connection: name, host, its tools, when they were last checked'
tags:
- Workers
security:
- AgentKey: []
parameters:
- name: connectionId
in: path
required: true
schema:
type: string
responses:
'200':
description: '`connection`. Never includes the URL or key.'
'404':
description: CONNECTION_NOT_FOUND
operationId: getV1ConnectionsByConnectionId
x-operation-id-source: derived
delete:
summary: Remove a connection
description: Workers that were granted its tools lose them from their next wake; pending requests on it fail if approved.
tags:
- Workers
security:
- AgentKey: []
parameters:
- name: connectionId
in: path
required: true
schema:
type: string
responses:
'200':
description: '`removed`: the id.'
'404':
description: CONNECTION_NOT_FOUND
operationId: deleteV1ConnectionsByConnectionId
x-operation-id-source: derived
/v1/connections/{connectionId}/refresh:
post:
summary: Re-read a connection's tool list
tags:
- Workers
security:
- AgentKey: []
parameters:
- name: connectionId
in: path
required: true
schema:
type: string
responses:
'200':
description: '`connection` with the fresh tools.'
'404':
description: CONNECTION_NOT_FOUND
'422':
description: CONNECTION_FAILED
operationId: postV1ConnectionsByConnectionIdRefresh
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.