---
title: "Create a worker template"
method: POST
path: "/api/workers"
tags: ["Workers"]
---

# Create a worker template

`POST /api/workers`

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.

## Request body

- CreateWorkerRequest
  - `title` string — Optional display name. When omitted, Handinger assigns a random dog-themed name.
  - `instructions` string — Persistent system prompt the worker uses for every task it runs.
  - `summary` string — Short one-line description of the worker's purpose. Auto-generated when omitted and a `prompt` is provided.
  - `prompt` string — 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.
  - `outputSchema` 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`.

## Response `201`

Created worker template.

- WorkerTemplate
  - `id` string, required
  - `title` string, required
  - `instructions` string, required
  - `summary` string, required
  - `visibility` 'public' | 'private', required
  - `outputSchema` object, nullable, required
  - `url` string, required — Web URL of the worker in the Handinger dashboard.
  - `organizationId` string, required
  - `userId` string, required
  - `createdAt` string, nullable, required
  - `updatedAt` string, nullable, required

## Other responses

- `401` — Unauthorized.
- `403` — Forbidden.
- `429` — Rate limit exceeded.
- `500` — Internal server error.

## Changes

- **2026-05-11** `1cd8acc54da5` — 1 info
  - added the required property `url` to the response with the `201` status
- **2026-05-08** `1d03ffac7c93` — 2 info
  - added the new optional request property `summary`
  - added the required property `summary` to the response with the `201` status
- **2026-05-08** `18bf56dfd496` — 2 info
  - added the new optional request property `outputSchema`
  - added the required property `outputSchema` to the response with the `201` status
- **2026-05-06** `a19d4ca505c5` — 1 info
  - the request property `title` became optional
- **2026-05-05** `10c7ebab2bab` — 1 info
  - added the new optional request property `prompt`

[Full history](https://skmtc.dev/ramensoft/apis/handinger-api/changes/api/workers/post.md)

---

[API](https://skmtc.dev/ramensoft/apis/handinger-api.md) · [All operations](https://skmtc.dev/ramensoft/apis/handinger-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/ramensoft/handinger-api/revisions/95b6b61a63ef/schema)