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

client.workers.create(WorkerCreateParams { instructions, outputSchema, prompt, 3 more } body, RequestOptionsoptions?): WorkerTemplate { id, createdAt, instructions, 8 more }

POST/api/workers

Retrieve a worker

client.workers.retrieve(stringworkerID, WorkerRetrieveParams { taskId } query?, RequestOptionsoptions?): Worker { id, created_at, error, 13 more }

GET/api/workers/{workerId}

Update a worker template

client.workers.update(stringworkerID, WorkerUpdateParams { instructions, outputSchema, summary, 2 more } body, RequestOptionsoptions?): WorkerTemplate { id, createdAt, instructions, 8 more }

PATCH/api/workers/{workerId}

Delete a worker template

client.workers.delete(stringworkerID, RequestOptionsoptions?): DeleteWorkerResponse { deleted }

DELETE/api/workers/{workerId}

Retrieve a worker email address

client.workers.retrieveEmail(stringworkerID, RequestOptionsoptions?): WorkerRetrieveEmailResponse { email }

GET/api/workers/{workerId}/email

ModelsExpand Collapse

CreateWorker { instructions, outputSchema, prompt, 3 more }

instructions?: string

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

maxLength20000

outputSchema?: Record<string, 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?: string

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

maxLength10000

summary?: string

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

maxLength80

title?: string

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

minLength1

maxLength200

visibility?: "public" | "private"

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

One of the following:

"public"

"private"

DeleteWorkerResponse { deleted }

deleted: boolean

UpdateWorker { instructions, outputSchema, summary, 2 more }

instructions?: string

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

maxLength20000

outputSchema?: Record<string, unknown> | null

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

summary?: string

Replaces the worker’s short one-line summary.

maxLength80

title?: string

New display name for the worker.

minLength1

maxLength200

visibility?: "public" | "private"

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

One of the following:

"public"

"private"

Worker { id, created_at, error, 13 more }

id: string

created_at: number | null

error: unknown

files: Array<File>

filename: string | null

mediaType: string

url: string

formaturi

size?: number

minimum0

incomplete_details: unknown

messages: Array<unknown>

metadata: Record<string, unknown>

object: "worker"

output: Array<Output>

id: string

content: Array<Content>

text: string

type: "output_text"

role: "assistant"

status: "completed"

type: "message"

output_text: string

running: boolean

sources: Array<Source>

id: string

title: string | null

type: "url"

url: string

status: "running" | "completed" | "pending"

One of the following:

"running"

"completed"

"pending"

structured_output: Record<string, unknown> | null

url: string

Web URL of the worker in the Handinger dashboard.

usage?: Usage { durationMs }

durationMs?: number

minimum0

WorkerTemplate { id, createdAt, instructions, 8 more }

id: string

createdAt: string | null

instructions: string

organizationId: string

outputSchema: Record<string, unknown> | null

summary: string

title: string

updatedAt: string | null

url: string

Web URL of the worker in the Handinger dashboard.

userId: string

visibility: "public" | "private"

One of the following:

"public"

"private"

WorkerRetrieveEmailResponse { email }

email: string

WorkersSchedules

Manage future and recurring worker tasks.

List worker schedules

client.workers.schedules.list(stringworkerID, RequestOptionsoptions?): ScheduleListResponse { schedules, timezone, workerId }

GET/api/workers/{workerId}/schedules

Create a worker schedule

client.workers.schedules.create(stringworkerID, ScheduleCreateParams { input, when, budget } body, RequestOptionsoptions?): WorkerSchedule

POST/api/workers/{workerId}/schedules

Cancel a worker schedule

client.workers.schedules.cancel(stringscheduleID, ScheduleCancelParams { workerId } params, RequestOptionsoptions?): ScheduleCancelResponse { cancelled }

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

ModelsExpand Collapse

WorkerSchedule = ScheduledWorkerSchedule { id, budget, input, 2 more } | DelayedWorkerSchedule { id, budget, delayInSeconds, 3 more } | CronWorkerSchedule { id, budget, cron, 3 more } | IntervalWorkerSchedule { id, budget, input, 3 more }

One of the following:

ScheduledWorkerSchedule { id, budget, input, 2 more }

id: string

budget: "low" | "standard" | "high" | "unlimited"

One of the following:

"low"

"standard"

"high"

"unlimited"

input: string

nextRunAt: string

formatdate-time

type: "scheduled"

DelayedWorkerSchedule { id, budget, delayInSeconds, 3 more }

id: string

budget: "low" | "standard" | "high" | "unlimited"

One of the following:

"low"

"standard"

"high"

"unlimited"

delayInSeconds: number

input: string

nextRunAt: string

formatdate-time

type: "delayed"

CronWorkerSchedule { id, budget, cron, 3 more }

id: string

budget: "low" | "standard" | "high" | "unlimited"

One of the following:

"low"

"standard"

"high"

"unlimited"

cron: string

input: string

nextRunAt: string

formatdate-time

type: "cron"

IntervalWorkerSchedule { id, budget, input, 3 more }

id: string

budget: "low" | "standard" | "high" | "unlimited"

One of the following:

"low"

"standard"

"high"

"unlimited"

input: string

intervalSeconds: number

nextRunAt: string

formatdate-time

type: "interval"

ScheduleListResponse { schedules, timezone, workerId }

schedules: Array<WorkerSchedule>

One of the following:

ScheduledWorkerSchedule { id, budget, input, 2 more }

id: string

budget: "low" | "standard" | "high" | "unlimited"

One of the following:

"low"

"standard"

"high"

"unlimited"

input: string

nextRunAt: string

formatdate-time

type: "scheduled"

DelayedWorkerSchedule { id, budget, delayInSeconds, 3 more }

id: string

budget: "low" | "standard" | "high" | "unlimited"

One of the following:

"low"

"standard"

"high"

"unlimited"

delayInSeconds: number

input: string

nextRunAt: string

formatdate-time

type: "delayed"

CronWorkerSchedule { id, budget, cron, 3 more }

id: string

budget: "low" | "standard" | "high" | "unlimited"

One of the following:

"low"

"standard"

"high"

"unlimited"

cron: string

input: string

nextRunAt: string

formatdate-time

type: "cron"

IntervalWorkerSchedule { id, budget, input, 3 more }

id: string

budget: "low" | "standard" | "high" | "unlimited"

One of the following:

"low"

"standard"

"high"

"unlimited"

input: string

intervalSeconds: number

nextRunAt: string

formatdate-time

type: "interval"

timezone: string

workerId: string

ScheduleCancelResponse { cancelled }

cancelled: boolean

WorkersWebhooks

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

Retrieve a worker webhook

client.workers.webhooks.retrieve(stringworkerID, RequestOptionsoptions?): Webhook { token, url }

GET/api/workers/{workerId}/webhook

Update a worker webhook

client.workers.webhooks.update(stringworkerID, WebhookUpdateParams { url } body, RequestOptionsoptions?): Webhook { token, url }

PUT/api/workers/{workerId}/webhook

Delete a worker webhook

client.workers.webhooks.delete(stringworkerID, RequestOptionsoptions?): Webhook { token, url }

DELETE/api/workers/{workerId}/webhook

Regenerate a worker webhook token

client.workers.webhooks.regenerateToken(stringworkerID, RequestOptionsoptions?): Webhook { token, url }

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

List worker webhook executions

client.workers.webhooks.listExecutions(stringworkerID, WebhookListExecutionsParams { page } query?, RequestOptionsoptions?): WebhookExecutionList { logs, page, pageCount, totalCount }

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

ModelsExpand Collapse

UpdateWebhook { url }

url: string | null

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

maxLength2048

formaturi

Webhook { token, url }

token: string | null

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

url: string | null

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

WebhookExecution { id, createdAt, durationMs, 7 more }

id: string

createdAt: string

formatdate-time

durationMs: number

Wall-clock time spent on the delivery attempt.

errorMessage: string | null

Failure reason when requestStatus is error.

requestStatus: "success" | "error"

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

One of the following:

"success"

"error"

responseStatus: number | null

HTTP status returned by the endpoint, when reachable.

taskId: string | null

Task that triggered the delivery, when available.

taskTitle: string | null

Title of the originating task, when available.

url: string

Endpoint Handinger attempted to deliver to.

workerId: string

WebhookExecutionList { logs, page, pageCount, totalCount }

logs: Array<WebhookExecution { id, createdAt, durationMs, 7 more } >

id: string

createdAt: string

formatdate-time

durationMs: number

Wall-clock time spent on the delivery attempt.

errorMessage: string | null

Failure reason when requestStatus is error.

requestStatus: "success" | "error"

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

One of the following:

"success"

"error"

responseStatus: number | null

HTTP status returned by the endpoint, when reachable.

taskId: string | null

Task that triggered the delivery, when available.

taskTitle: string | null

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.