API Reference

Copy Markdown

Open in Claude

Open in ChatGPT

Open in Cursor

---

Copy Markdown

View as Markdown

Workers

Create, retrieve, and manage agent worker templates.

Create a worker template

$ handinger workers create

POST/api/workers

Retrieve a worker

$ handinger workers retrieve

GET/api/workers/{workerId}

Update a worker template

$ handinger workers update

PATCH/api/workers/{workerId}

Delete a worker template

$ handinger workers delete

DELETE/api/workers/{workerId}

Retrieve a worker email address

$ handinger workers retrieve-email

GET/api/workers/{workerId}/email

ModelsExpand Collapse

create_worker: object { instructions, outputSchema, prompt, 3 more }

instructions: optional string

Persistent system prompt the worker uses for every task it runs.

outputSchema: optional map[unknown]

Optional JSON Schema (Draft-07) describing the structured object the worker must produce. When set, every task response is validated against the schema and exposed as structuredOutput.

prompt: optional string

Natural-language description of the worker to use for AI-generated instructions when instructions is omitted.

summary: optional string

Short one-line description of the worker’s purpose. Auto-generated when omitted and a prompt is provided.

title: optional string

Optional display name. When omitted, Handinger assigns a random dog-themed name.

visibility: optional "public" or "private"

public (default) is visible to all org members. private is only visible to invited members.

"public"

"private"

delete_worker_response: object { deleted }

deleted: boolean

update_worker: object { instructions, outputSchema, summary, 2 more }

instructions: optional string

Replaces the persistent system prompt. Subsequent tasks pick up the new instructions immediately; in-flight tasks keep using the previous version.

outputSchema: optional map[unknown]

Replace the worker’s structured output schema. Pass null to clear it and return to free-form text responses.

summary: optional string

Replaces the worker’s short one-line summary.

title: optional string

New display name for the worker.

visibility: optional "public" or "private"

Change visibility between public (any org member can run tasks) and private (only invited members).

"public"

"private"

worker: object { id, created_at, error, 13 more }

id: string

created_at: number

error: unknown

files: array of object { filename, mediaType, url, size }

filename: string

mediaType: string

url: string

size: optional number

incomplete_details: unknown

messages: array of unknown

metadata: map[unknown]

object: "worker"

output: array of object { id, content, role, 2 more }

id: string

content: array of object { text, type }

text: string

type: "output_text"

role: "assistant"

status: "completed"

type: "message"

output_text: string

running: boolean

sources: array of object { id, title, type, url }

id: string

title: string

type: "url"

url: string

status: "running" or "completed" or "pending"

"running"

"completed"

"pending"

structured_output: map[unknown]

url: string

Web URL of the worker in the Handinger dashboard.

usage: optional object { durationMs }

durationMs: optional number

worker_template: object { id, createdAt, instructions, 8 more }

id: string

createdAt: string

instructions: string

organizationId: string

outputSchema: map[unknown]

summary: string

title: string

updatedAt: string

url: string

Web URL of the worker in the Handinger dashboard.

userId: string

visibility: "public" or "private"

"public"

"private"

WorkersSchedules

Manage future and recurring worker tasks.

List worker schedules

$ handinger workers:schedules list

GET/api/workers/{workerId}/schedules

Create a worker schedule

$ handinger workers:schedules create

POST/api/workers/{workerId}/schedules

Cancel a worker schedule

$ handinger workers:schedules cancel

DELETE/api/workers/{workerId}/schedules/{scheduleId}

ModelsExpand Collapse

worker_schedule: object { id, budget, input, 2 more } or object { id, budget, delayInSeconds, 3 more } or object { id, budget, cron, 3 more } or object { id, budget, input, 3 more }

scheduled: object { id, budget, input, 2 more }

id: string

budget: "low" or "standard" or "high" or "unlimited"

"low"

"standard"

"high"

"unlimited"

input: string

nextRunAt: string

type: "scheduled"

delayed: object { id, budget, delayInSeconds, 3 more }

id: string

budget: "low" or "standard" or "high" or "unlimited"

"low"

"standard"

"high"

"unlimited"

delayInSeconds: number

input: string

nextRunAt: string

type: "delayed"

cron: object { id, budget, cron, 3 more }

id: string

budget: "low" or "standard" or "high" or "unlimited"

"low"

"standard"

"high"

"unlimited"

cron: string

input: string

nextRunAt: string

type: "cron"

interval: object { id, budget, input, 3 more }

id: string

budget: "low" or "standard" or "high" or "unlimited"

"low"

"standard"

"high"

"unlimited"

input: string

intervalSeconds: number

nextRunAt: string

type: "interval"

WorkersWebhooks

Configure outbound webhooks delivered when a worker’s tasks complete.

Retrieve a worker webhook

$ handinger workers:webhooks retrieve

GET/api/workers/{workerId}/webhook

Update a worker webhook

$ handinger workers:webhooks update

PUT/api/workers/{workerId}/webhook

Delete a worker webhook

$ handinger workers:webhooks delete

DELETE/api/workers/{workerId}/webhook

Regenerate a worker webhook token

$ handinger workers:webhooks regenerate-token

POST/api/workers/{workerId}/webhook/regenerate-token

List worker webhook executions

$ handinger workers:webhooks list-executions

GET/api/workers/{workerId}/webhook/executions

ModelsExpand Collapse

update_webhook: object { url }

url: string

HTTPS endpoint Handinger should POST to when a task finishes. Pass null to remove the webhook and clear its token.

webhook: object { token, url }

token: string

Shared secret sent in the X-Handinger-Token header on each delivery. null when no webhook is configured.

url: string

HTTPS endpoint that receives webhook deliveries when a task completes. null when no webhook is configured.

webhook_execution: object { id, createdAt, durationMs, 7 more }

id: string

createdAt: string

durationMs: number

Wall-clock time spent on the delivery attempt.

errorMessage: string

Failure reason when requestStatus is error.

requestStatus: "success" or "error"

success when the endpoint returned a 2xx response, error otherwise.

"success"

"error"

responseStatus: number

HTTP status returned by the endpoint, when reachable.

taskId: string

Task that triggered the delivery, when available.

taskTitle: string

Title of the originating task, when available.

url: string

Endpoint Handinger attempted to deliver to.

workerId: string

webhook_execution_list: object { logs, page, pageCount, totalCount }

logs: array of WebhookExecution { id, createdAt, durationMs, 7 more }

id: string

createdAt: string

durationMs: number

Wall-clock time spent on the delivery attempt.

errorMessage: string

Failure reason when requestStatus is error.

requestStatus: "success" or "error"

success when the endpoint returned a 2xx response, error otherwise.

"success"

"error"

responseStatus: number

HTTP status returned by the endpoint, when reachable.

taskId: string

Task that triggered the delivery, when available.

taskTitle: string

Title of the originating task, when available.

url: string

Endpoint Handinger attempted to deliver to.

workerId: string

page: number

Current page number.

pageCount: number

Total number of pages available.

totalCount: number

Total number of executions recorded.