Sign in

v27

latestOpenAPI 3.1.0LicenseRef-Proprietaryraw.githubusercontent.com2026-07-21173076.1 KB
Workers

Create a worker template

Create a new worker. The worker is a reusable agent template; tasks are runs against this template. Use POST /tasks to actually run the agent.

post/api/workers

Request body

titlestring

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

instructionsstring

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

summarystring

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

promptstring

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

visibility'public' | 'private'

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

outputSchemaobject

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.

Example request

{
  "title": "Brand voice analyzer",
  "instructions": "You are a brand voice analyzer. Read the input text and report whether it matches Acme's playful, plain-spoken house style. Quote specific phrases.",
  "summary": "Audits copy against the Acme brand voice guide.",
  "prompt": "A worker that fact-checks short claims and returns a verdict with citations.",
  "visibility": "public",
  "outputSchema": {
    "type": "object",
    "required": [
      "verdict",
      "summary"
    ],
    "properties": {
      "verdict": {
        "type": "string",
        "enum": [
          "supported",
          "debunked",
          "mixed",
          "unknown"
        ]
      },
      "summary": {
        "type": "string"
      },
      "citations": {
        "type": "array",
        "items": {
          "type": "string"
        }
      }
    }
  }
}

Response

Created worker template.

idstring required
titlestring required
instructionsstring required
summarystring required
visibility'public' | 'private' required
outputSchemaobject nullable required
urlstring required

Web URL of the worker in the Handinger dashboard.

organizationIdstring required
userIdstring required
createdAtstring nullable required
updatedAtstring nullable required

Example response

{
  "url": "https://v3.handinger.com/worker/wrk_vk81XUHKHG-qr4"
}
All 17 operations