Skip to content
Handinger
Get started
API Reference

Workers

Create, retrieve, and manage agent worker templates.

Create a worker template
POST/api/workers
Retrieve a worker
GET/api/workers/{workerId}
Update a worker template
PATCH/api/workers/{workerId}
Delete a worker template
DELETE/api/workers/{workerId}
Retrieve a worker email address
GET/api/workers/{workerId}/email
ModelsExpand Collapse
CreateWorker object { instructions, outputSchema, prompt, 3 more }
instructions: optional string

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

maxLength20000
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.

maxLength10000
summary: optional string

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

maxLength80
title: optional string

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

minLength1
maxLength200
visibility: optional "public" or "private"

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

One of the following:
"public"
"private"
DeleteWorkerResponse object { deleted }
deleted: boolean
UpdateWorker 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.

maxLength20000
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.

maxLength80
title: optional string

New display name for the worker.

minLength1
maxLength200
visibility: optional "public" or "private"

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

One of the following:
"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
minimum0
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"
One of the following:
"running"
"completed"
"pending"
structured_output: map[unknown]
url: string

Web URL of the worker in the Handinger dashboard.

usage: optional object { credits, durationMs }
credits: optional number
minimum0
durationMs: optional number
minimum0
WorkerTemplate 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"
One of the following:
"public"
"private"
WorkerRetrieveEmailResponse object { email }
email: string

WorkersSchedules

Manage future and recurring worker tasks.

List worker schedules
GET/api/workers/{workerId}/schedules
Create a worker schedule
POST/api/workers/{workerId}/schedules
Cancel a worker schedule
DELETE/api/workers/{workerId}/schedules/{scheduleId}
ModelsExpand Collapse
WorkerSchedule = 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 }
One of the following:
Scheduled object { id, budget, input, 2 more }
id: string
budget: "low" or "standard" or "high" or "unlimited"
One of the following:
"low"
"standard"
"high"
"unlimited"
input: string
nextRunAt: string
formatdate-time
type: "scheduled"
Delayed object { id, budget, delayInSeconds, 3 more }
id: string
budget: "low" or "standard" or "high" or "unlimited"
One of the following:
"low"
"standard"
"high"
"unlimited"
delayInSeconds: number
input: string
nextRunAt: string
formatdate-time
type: "delayed"
Cron object { id, budget, cron, 3 more }
id: string
budget: "low" or "standard" or "high" or "unlimited"
One of the following:
"low"
"standard"
"high"
"unlimited"
cron: string
input: string
nextRunAt: string
formatdate-time
type: "cron"
Interval object { id, budget, input, 3 more }
id: string
budget: "low" or "standard" or "high" or "unlimited"
One of the following:
"low"
"standard"
"high"
"unlimited"
input: string
intervalSeconds: number
nextRunAt: string
formatdate-time
type: "interval"
ScheduleListResponse object { schedules, workerId }
schedules: array of WorkerSchedule
One of the following:
Scheduled object { id, budget, input, 2 more }
id: string
budget: "low" or "standard" or "high" or "unlimited"
One of the following:
"low"
"standard"
"high"
"unlimited"
input: string
nextRunAt: string
formatdate-time
type: "scheduled"
Delayed object { id, budget, delayInSeconds, 3 more }
id: string
budget: "low" or "standard" or "high" or "unlimited"
One of the following:
"low"
"standard"
"high"
"unlimited"
delayInSeconds: number
input: string
nextRunAt: string
formatdate-time
type: "delayed"
Cron object { id, budget, cron, 3 more }
id: string
budget: "low" or "standard" or "high" or "unlimited"
One of the following:
"low"
"standard"
"high"
"unlimited"
cron: string
input: string
nextRunAt: string
formatdate-time
type: "cron"
Interval object { id, budget, input, 3 more }
id: string
budget: "low" or "standard" or "high" or "unlimited"
One of the following:
"low"
"standard"
"high"
"unlimited"
input: string
intervalSeconds: number
nextRunAt: string
formatdate-time
type: "interval"
workerId: string
ScheduleCancelResponse object { cancelled }
cancelled: boolean

WorkersWebhooks

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

Retrieve a worker webhook
GET/api/workers/{workerId}/webhook
Update a worker webhook
PUT/api/workers/{workerId}/webhook
Delete a worker webhook
DELETE/api/workers/{workerId}/webhook
Regenerate a worker webhook token
POST/api/workers/{workerId}/webhook/regenerate-token
List worker webhook executions
GET/api/workers/{workerId}/webhook/executions
ModelsExpand Collapse
UpdateWebhook object { url }
url: string

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

maxLength2048
formaturi
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.

WebhookExecution object { id, createdAt, durationMs, 7 more }
id: string
createdAt: string
formatdate-time
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.

One of the following:
"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
WebhookExecutionList object { logs, page, pageCount, totalCount }
logs: array of WebhookExecution { id, createdAt, durationMs, 7 more }
id: string
createdAt: string
formatdate-time
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.

One of the following:
"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.