---
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.

---

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