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.New(ctx, body) (*WorkerTemplate, error)

POST/api/workers

Retrieve a worker

client.Workers.Get(ctx, workerID, query) (*Worker, error)

GET/api/workers/{workerId}

Update a worker template

client.Workers.Update(ctx, workerID, body) (*WorkerTemplate, error)

PATCH/api/workers/{workerId}

Delete a worker template

client.Workers.Delete(ctx, workerID) (*DeleteWorkerResponse, error)

DELETE/api/workers/{workerId}

Retrieve a worker email address

client.Workers.GetEmail(ctx, workerID) (*WorkerGetEmailResponse, error)

GET/api/workers/{workerId}/email

ModelsExpand Collapse

type CreateWorker struct{…}

Instructions stringOptional

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

maxLength20000

OutputSchema map[string, any]Optional

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 stringOptional

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

maxLength10000

Summary stringOptional

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

maxLength80

Title stringOptional

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

minLength1

maxLength200

Visibility CreateWorkerVisibilityOptional

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

One of the following:

const CreateWorkerVisibilityPublic CreateWorkerVisibility = "public"

const CreateWorkerVisibilityPrivate CreateWorkerVisibility = "private"

type DeleteWorkerResponse struct{…}

Deleted bool

type UpdateWorker struct{…}

Instructions stringOptional

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

maxLength20000

OutputSchema map[string, any]Optional

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

Summary stringOptional

Replaces the worker’s short one-line summary.

maxLength80

Title stringOptional

New display name for the worker.

minLength1

maxLength200

Visibility UpdateWorkerVisibilityOptional

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

One of the following:

const UpdateWorkerVisibilityPublic UpdateWorkerVisibility = "public"

const UpdateWorkerVisibilityPrivate UpdateWorkerVisibility = "private"

type Worker struct{…}

ID string

CreatedAt int64

Error any

Files []WorkerFile

Filename string

MediaType string

URL string

formaturi

Size int64Optional

minimum0

IncompleteDetails any

Messages []any

Metadata map[string, any]

Object Worker

Output []WorkerOutput

ID string

Content []WorkerOutputContent

Text string

Type OutputText

Role Assistant

Status Completed

Type Message

OutputText string

Running bool

Sources []WorkerSource

ID string

Title string

Type URL

URL string

Status WorkerStatus

One of the following:

const WorkerStatusRunning WorkerStatus = "running"

const WorkerStatusCompleted WorkerStatus = "completed"

const WorkerStatusPending WorkerStatus = "pending"

StructuredOutput map[string, any]

URL string

Web URL of the worker in the Handinger dashboard.

Usage WorkerUsageOptional

DurationMs int64Optional

minimum0

type WorkerTemplate struct{…}

ID string

CreatedAt string

Instructions string

OrganizationID string

OutputSchema map[string, any]

Summary string

Title string

UpdatedAt string

URL string

Web URL of the worker in the Handinger dashboard.

UserID string

Visibility WorkerTemplateVisibility

One of the following:

const WorkerTemplateVisibilityPublic WorkerTemplateVisibility = "public"

const WorkerTemplateVisibilityPrivate WorkerTemplateVisibility = "private"

WorkersSchedules

Manage future and recurring worker tasks.

List worker schedules

client.Workers.Schedules.List(ctx, workerID) (*WorkerScheduleListResponse, error)

GET/api/workers/{workerId}/schedules

Create a worker schedule

client.Workers.Schedules.New(ctx, workerID, body) (*WorkerScheduleUnion, error)

POST/api/workers/{workerId}/schedules

Cancel a worker schedule

client.Workers.Schedules.Cancel(ctx, scheduleID, body) (*WorkerScheduleCancelResponse, error)

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

ModelsExpand Collapse

type WorkerScheduleUnion interface{…}

One of the following:

type WorkerScheduleScheduled struct{…}

ID string

Budget string

One of the following:

const WorkerScheduleScheduledBudgetLow WorkerScheduleScheduledBudget = "low"

const WorkerScheduleScheduledBudgetStandard WorkerScheduleScheduledBudget = "standard"

const WorkerScheduleScheduledBudgetHigh WorkerScheduleScheduledBudget = "high"

const WorkerScheduleScheduledBudgetUnlimited WorkerScheduleScheduledBudget = "unlimited"

Input string

NextRunAt Time

formatdate-time

Type Scheduled

type WorkerScheduleDelayed struct{…}

ID string

Budget string

One of the following:

const WorkerScheduleDelayedBudgetLow WorkerScheduleDelayedBudget = "low"

const WorkerScheduleDelayedBudgetStandard WorkerScheduleDelayedBudget = "standard"

const WorkerScheduleDelayedBudgetHigh WorkerScheduleDelayedBudget = "high"

const WorkerScheduleDelayedBudgetUnlimited WorkerScheduleDelayedBudget = "unlimited"

DelayInSeconds int64

Input string

NextRunAt Time

formatdate-time

Type Delayed

type WorkerScheduleCron struct{…}

ID string

Budget string

One of the following:

const WorkerScheduleCronBudgetLow WorkerScheduleCronBudget = "low"

const WorkerScheduleCronBudgetStandard WorkerScheduleCronBudget = "standard"

const WorkerScheduleCronBudgetHigh WorkerScheduleCronBudget = "high"

const WorkerScheduleCronBudgetUnlimited WorkerScheduleCronBudget = "unlimited"

Cron string

Input string

NextRunAt Time

formatdate-time

Type Cron

type WorkerScheduleInterval struct{…}

ID string

Budget string

One of the following:

const WorkerScheduleIntervalBudgetLow WorkerScheduleIntervalBudget = "low"

const WorkerScheduleIntervalBudgetStandard WorkerScheduleIntervalBudget = "standard"

const WorkerScheduleIntervalBudgetHigh WorkerScheduleIntervalBudget = "high"

const WorkerScheduleIntervalBudgetUnlimited WorkerScheduleIntervalBudget = "unlimited"

Input string

IntervalSeconds int64

NextRunAt Time

formatdate-time

Type Interval

WorkersWebhooks

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

Retrieve a worker webhook

client.Workers.Webhooks.Get(ctx, workerID) (*Webhook, error)

GET/api/workers/{workerId}/webhook

Update a worker webhook

client.Workers.Webhooks.Update(ctx, workerID, body) (*Webhook, error)

PUT/api/workers/{workerId}/webhook

Delete a worker webhook

client.Workers.Webhooks.Delete(ctx, workerID) (*Webhook, error)

DELETE/api/workers/{workerId}/webhook

Regenerate a worker webhook token

client.Workers.Webhooks.RegenerateToken(ctx, workerID) (*Webhook, error)

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

List worker webhook executions

client.Workers.Webhooks.ListExecutions(ctx, workerID, query) (*WebhookExecutionList, error)

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

ModelsExpand Collapse

type UpdateWebhook struct{…}

URL string

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

maxLength2048

formaturi

type Webhook struct{…}

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.

type WebhookExecution struct{…}

ID string

CreatedAt Time

formatdate-time

DurationMs int64

Wall-clock time spent on the delivery attempt.

ErrorMessage string

Failure reason when requestStatus is error.

RequestStatus WebhookExecutionRequestStatus

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

One of the following:

const WebhookExecutionRequestStatusSuccess WebhookExecutionRequestStatus = "success"

const WebhookExecutionRequestStatusError WebhookExecutionRequestStatus = "error"

ResponseStatus int64

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

type WebhookExecutionList struct{…}

Logs []WebhookExecution

ID string

CreatedAt Time

formatdate-time

DurationMs int64

Wall-clock time spent on the delivery attempt.

ErrorMessage string

Failure reason when requestStatus is error.

RequestStatus WebhookExecutionRequestStatus

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

One of the following:

const WebhookExecutionRequestStatusSuccess WebhookExecutionRequestStatus = "success"

const WebhookExecutionRequestStatusError WebhookExecutionRequestStatus = "error"

ResponseStatus int64

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 int64

Current page number.

PageCount int64

Total number of pages available.

TotalCount int64

Total number of executions recorded.