Skip to content
Handinger
Get started
API Reference

Workers

Create, retrieve, and manage agent worker templates.

Create a worker template
workers.create(WorkerCreateParams**kwargs) -> WorkerTemplate
POST/api/workers
Retrieve a worker
workers.retrieve(strworker_id, WorkerRetrieveParams**kwargs) -> Worker
GET/api/workers/{workerId}
Update a worker template
workers.update(strworker_id, WorkerUpdateParams**kwargs) -> WorkerTemplate
PATCH/api/workers/{workerId}
Delete a worker template
workers.delete(strworker_id) -> DeleteWorkerResponse
DELETE/api/workers/{workerId}
Retrieve a worker email address
workers.retrieve_email(strworker_id) -> WorkerRetrieveEmailResponse
GET/api/workers/{workerId}/email
ModelsExpand Collapse
class CreateWorker: …
instructions: Optional[str]

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

maxLength20000
output_schema: Optional[Dict[str, object]]

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[str]

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

maxLength10000
summary: Optional[str]

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

maxLength80
title: Optional[str]

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

minLength1
maxLength200
visibility: Optional[Literal["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: bool
class UpdateWorker: …
instructions: Optional[str]

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

maxLength20000
output_schema: Optional[Dict[str, object]]

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

summary: Optional[str]

Replaces the worker’s short one-line summary.

maxLength80
title: Optional[str]

New display name for the worker.

minLength1
maxLength200
visibility: Optional[Literal["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: str
created_at: Optional[int]
error: None
files: List[File]
filename: Optional[str]
media_type: str
url: str
formaturi
size: Optional[int]
minimum0
incomplete_details: None
messages: List[object]
metadata: Dict[str, object]
object: Literal["worker"]
output: List[Output]
id: str
content: List[OutputContent]
text: str
type: Literal["output_text"]
role: Literal["assistant"]
status: Literal["completed"]
type: Literal["message"]
output_text: str
running: bool
sources: List[Source]
id: str
title: Optional[str]
type: Literal["url"]
url: str
status: Literal["running", "completed", "pending"]
One of the following:
"running"
"completed"
"pending"
structured_output: Optional[Dict[str, object]]
url: str

Web URL of the worker in the Handinger dashboard.

usage: Optional[Usage]
duration_ms: Optional[int]
minimum0
class WorkerTemplate: …
id: str
created_at: Optional[str]
instructions: str
organization_id: str
output_schema: Optional[Dict[str, object]]
summary: str
title: str
updated_at: Optional[str]
url: str

Web URL of the worker in the Handinger dashboard.

user_id: str
visibility: Literal["public", "private"]
One of the following:
"public"
"private"
class WorkerRetrieveEmailResponse: …
email: str

WorkersSchedules

Manage future and recurring worker tasks.

List worker schedules
workers.schedules.list(strworker_id) -> ScheduleListResponse
GET/api/workers/{workerId}/schedules
Create a worker schedule
workers.schedules.create(strworker_id, ScheduleCreateParams**kwargs) -> WorkerSchedule
POST/api/workers/{workerId}/schedules
Cancel a worker schedule
workers.schedules.cancel(strschedule_id, ScheduleCancelParams**kwargs) -> ScheduleCancelResponse
DELETE/api/workers/{workerId}/schedules/{scheduleId}
ModelsExpand Collapse
One of the following:
class ScheduledWorkerSchedule: …
id: str
budget: Literal["low", "standard", "high", "unlimited"]
One of the following:
"low"
"standard"
"high"
"unlimited"
input: str
next_run_at: datetime
formatdate-time
type: Literal["scheduled"]
class DelayedWorkerSchedule: …
id: str
budget: Literal["low", "standard", "high", "unlimited"]
One of the following:
"low"
"standard"
"high"
"unlimited"
delay_in_seconds: int
input: str
next_run_at: datetime
formatdate-time
type: Literal["delayed"]
class CronWorkerSchedule: …
id: str
budget: Literal["low", "standard", "high", "unlimited"]
One of the following:
"low"
"standard"
"high"
"unlimited"
cron: str
input: str
next_run_at: datetime
formatdate-time
type: Literal["cron"]
class IntervalWorkerSchedule: …
id: str
budget: Literal["low", "standard", "high", "unlimited"]
One of the following:
"low"
"standard"
"high"
"unlimited"
input: str
interval_seconds: int
next_run_at: datetime
formatdate-time
type: Literal["interval"]
class ScheduleListResponse: …
schedules: List[WorkerSchedule]
One of the following:
class ScheduledWorkerSchedule: …
id: str
budget: Literal["low", "standard", "high", "unlimited"]
One of the following:
"low"
"standard"
"high"
"unlimited"
input: str
next_run_at: datetime
formatdate-time
type: Literal["scheduled"]
class DelayedWorkerSchedule: …
id: str
budget: Literal["low", "standard", "high", "unlimited"]
One of the following:
"low"
"standard"
"high"
"unlimited"
delay_in_seconds: int
input: str
next_run_at: datetime
formatdate-time
type: Literal["delayed"]
class CronWorkerSchedule: …
id: str
budget: Literal["low", "standard", "high", "unlimited"]
One of the following:
"low"
"standard"
"high"
"unlimited"
cron: str
input: str
next_run_at: datetime
formatdate-time
type: Literal["cron"]
class IntervalWorkerSchedule: …
id: str
budget: Literal["low", "standard", "high", "unlimited"]
One of the following:
"low"
"standard"
"high"
"unlimited"
input: str
interval_seconds: int
next_run_at: datetime
formatdate-time
type: Literal["interval"]
timezone: str
worker_id: str
class ScheduleCancelResponse: …
cancelled: bool

WorkersWebhooks

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

Retrieve a worker webhook
workers.webhooks.retrieve(strworker_id) -> Webhook
GET/api/workers/{workerId}/webhook
Update a worker webhook
workers.webhooks.update(strworker_id, WebhookUpdateParams**kwargs) -> Webhook
PUT/api/workers/{workerId}/webhook
Delete a worker webhook
workers.webhooks.delete(strworker_id) -> Webhook
DELETE/api/workers/{workerId}/webhook
Regenerate a worker webhook token
workers.webhooks.regenerate_token(strworker_id) -> Webhook
POST/api/workers/{workerId}/webhook/regenerate-token
List worker webhook executions
workers.webhooks.list_executions(strworker_id, WebhookListExecutionsParams**kwargs) -> WebhookExecutionList
GET/api/workers/{workerId}/webhook/executions
ModelsExpand Collapse
class UpdateWebhook: …
url: Optional[str]

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: Optional[str]

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

url: Optional[str]

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

class WebhookExecution: …
id: str
created_at: datetime
formatdate-time
duration_ms: int

Wall-clock time spent on the delivery attempt.

error_message: Optional[str]

Failure reason when requestStatus is error.

request_status: Literal["success", "error"]

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

One of the following:
"success"
"error"
response_status: Optional[int]

HTTP status returned by the endpoint, when reachable.

task_id: Optional[str]

Task that triggered the delivery, when available.

task_title: Optional[str]

Title of the originating task, when available.

url: str

Endpoint Handinger attempted to deliver to.

worker_id: str
class WebhookExecutionList: …
logs: List[WebhookExecution]
id: str
created_at: datetime
formatdate-time
duration_ms: int

Wall-clock time spent on the delivery attempt.

error_message: Optional[str]

Failure reason when requestStatus is error.

request_status: Literal["success", "error"]

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

One of the following:
"success"
"error"
response_status: Optional[int]

HTTP status returned by the endpoint, when reachable.

task_id: Optional[str]

Task that triggered the delivery, when available.

task_title: Optional[str]

Title of the originating task, when available.

url: str

Endpoint Handinger attempted to deliver to.

worker_id: str
page: int

Current page number.

page_count: int

Total number of pages available.

total_count: int

Total number of executions recorded.