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

workers.create(**kwargs) -> WorkerTemplate { id, created_at, instructions, 8 more }

POST/api/workers

Retrieve a worker

workers.retrieve(worker_id, **kwargs) -> Worker { id, created_at, error, 13 more }

GET/api/workers/{workerId}

Update a worker template

workers.update(worker_id, **kwargs) -> WorkerTemplate { id, created_at, instructions, 8 more }

PATCH/api/workers/{workerId}

Delete a worker template

workers.delete(worker_id) -> DeleteWorkerResponse { deleted }

DELETE/api/workers/{workerId}

Retrieve a worker email address

workers.retrieve_email(worker_id) -> WorkerRetrieveEmailResponse { email }

GET/api/workers/{workerId}/email

ModelsExpand Collapse

class CreateWorker { instructions, output_schema, prompt, 3 more }

instructions: String

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

maxLength20000

output_schema: Hash[Symbol, untyped]

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

class DeleteWorkerResponse { deleted }

deleted: bool

class UpdateWorker { instructions, output_schema, 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

output_schema: Hash[Symbol, untyped]

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

class Worker { id, created_at, error, 13 more }

id: String

created_at: Integer

error: nil

files: Array[File{ filename, media_type, url, size}]

filename: String

media_type: String

url: String

size: Integer

minimum0

incomplete_details: nil

messages: Array[untyped]

metadata: Hash[Symbol, untyped]

object: :worker

output: Array[Output{ id, content, role, 2 more}]

id: String

content: Array[Content{ text, type}]

text: String

type: :output_text

role: :assistant

status: :completed

type: :message

output_text: String

running: bool

sources: Array[Source{ id, title, type, url}]

id: String

title: String

type: :url

url: String

status: :running | :completed | :pending

One of the following:

:running

:completed

:pending

structured_output: Hash[Symbol, untyped]

url: String

Web URL of the worker in the Handinger dashboard.

usage: Usage{ credits, duration_ms}

credits: Integer

minimum0

duration_ms: Integer

minimum0

class WorkerTemplate { id, created_at, instructions, 8 more }

id: String

created_at: String

instructions: String

organization_id: String

output_schema: Hash[Symbol, untyped]

summary: String

title: String

updated_at: String

url: String

Web URL of the worker in the Handinger dashboard.

user_id: String

visibility: :public | :private

One of the following:

:public

:private

class WorkerRetrieveEmailResponse { email }

email: String

WorkersSchedules

Manage future and recurring worker tasks.

List worker schedules

workers.schedules.list(worker_id) -> ScheduleListResponse { schedules, worker_id }

GET/api/workers/{workerId}/schedules

Create a worker schedule

workers.schedules.create(worker_id, **kwargs) -> WorkerSchedule

POST/api/workers/{workerId}/schedules

Cancel a worker schedule

workers.schedules.cancel(schedule_id, **kwargs) -> ScheduleCancelResponse { cancelled }

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

ModelsExpand Collapse

WorkerSchedule = Scheduled{ id, budget, input, 2 more} | Delayed{ id, budget, delay_in_seconds, 3 more} | Cron{ id, budget, cron, 3 more} | Interval{ id, budget, input, 3 more}

One of the following:

class Scheduled { id, budget, input, 2 more }

id: String

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

One of the following:

:low

:standard

:high

:unlimited

input: String

next_run_at: Time

formatdate-time

type: :scheduled

class Delayed { id, budget, delay_in_seconds, 3 more }

id: String

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

One of the following:

:low

:standard

:high

:unlimited

delay_in_seconds: Integer

input: String

next_run_at: Time

formatdate-time

type: :delayed

class Cron { id, budget, cron, 3 more }

id: String

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

One of the following:

:low

:standard

:high

:unlimited

cron: String

input: String

next_run_at: Time

formatdate-time

type: :cron

class Interval { id, budget, input, 3 more }

id: String

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

One of the following:

:low

:standard

:high

:unlimited

input: String

interval_seconds: Integer

next_run_at: Time

formatdate-time

type: :interval

class ScheduleListResponse { schedules, worker_id }

schedules: Array[WorkerSchedule]

One of the following:

class Scheduled { id, budget, input, 2 more }

id: String

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

One of the following:

:low

:standard

:high

:unlimited

input: String

next_run_at: Time

formatdate-time

type: :scheduled

class Delayed { id, budget, delay_in_seconds, 3 more }

id: String

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

One of the following:

:low

:standard

:high

:unlimited

delay_in_seconds: Integer

input: String

next_run_at: Time

formatdate-time

type: :delayed

class Cron { id, budget, cron, 3 more }

id: String

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

One of the following:

:low

:standard

:high

:unlimited

cron: String

input: String

next_run_at: Time

formatdate-time

type: :cron

class Interval { id, budget, input, 3 more }

id: String

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

One of the following:

:low

:standard

:high

:unlimited

input: String

interval_seconds: Integer

next_run_at: Time

formatdate-time

type: :interval

worker_id: String

class ScheduleCancelResponse { cancelled }

cancelled: bool

WorkersWebhooks

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

Retrieve a worker webhook

workers.webhooks.retrieve(worker_id) -> Webhook { token, url }

GET/api/workers/{workerId}/webhook

Update a worker webhook

workers.webhooks.update(worker_id, **kwargs) -> Webhook { token, url }

PUT/api/workers/{workerId}/webhook

Delete a worker webhook

workers.webhooks.delete(worker_id) -> Webhook { token, url }

DELETE/api/workers/{workerId}/webhook

Regenerate a worker webhook token

workers.webhooks.regenerate_token(worker_id) -> Webhook { token, url }

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

List worker webhook executions

workers.webhooks.list_executions(worker_id, **kwargs) -> WebhookExecutionList { logs, page, page_count, total_count }

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

ModelsExpand Collapse

class UpdateWebhook { 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

class Webhook { 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.

class WebhookExecution { id, created_at, duration_ms, 7 more }

id: String

created_at: Time

formatdate-time

duration_ms: Integer

Wall-clock time spent on the delivery attempt.

error_message: String

Failure reason when requestStatus is error.

request_status: :success | :error

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

One of the following:

:success

:error

response_status: Integer

HTTP status returned by the endpoint, when reachable.

task_id: String

Task that triggered the delivery, when available.

task_title: String

Title of the originating task, when available.

url: String

Endpoint Handinger attempted to deliver to.

worker_id: String

class WebhookExecutionList { logs, page, page_count, total_count }

logs: Array[WebhookExecution { id, created_at, duration_ms, 7 more } ]

id: String

created_at: Time

formatdate-time

duration_ms: Integer

Wall-clock time spent on the delivery attempt.

error_message: String

Failure reason when requestStatus is error.

request_status: :success | :error

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

One of the following:

:success

:error

response_status: Integer

HTTP status returned by the endpoint, when reachable.

task_id: String

Task that triggered the delivery, when available.

task_title: String

Title of the originating task, when available.

url: String

Endpoint Handinger attempted to deliver to.

worker_id: String

page: Integer

Current page number.

page_count: Integer

Total number of pages available.

total_count: Integer

Total number of executions recorded.