---
title: "Create a task"
method: POST
path: "/api/tasks"
tags: ["Tasks"]
---

# Create a task

`POST /api/tasks`

Run a new task against an existing worker and wait for the result. Send a `taskId` of a prior task to add a follow-up turn instead of starting a fresh task. Send `multipart/form-data` to attach files; the bytes are bootstrapped into the worker's workspace before the task starts. The task runs to completion on the server even if the connection drops; subscribe to task webhooks for long-running tasks.

## Request body

- CreateTaskRequest
  - `input` string, required
  - `budget` 'low' | 'standard' | 'high' | 'unlimited' — Compute budget the worker is allowed to spend on the task. Defaults to `standard`.
  - `taskId` string — Optional client-provided task id. Reuse this id to add turns to an existing task.
  - `workerId` string — Worker id the task belongs to. If omitted, a new worker is created on-the-fly using the input as instructions.

## Response `200`

Worker object reflecting the final task result.

- Worker
  - `id` string, required
  - `object` 'worker', required
  - `created_at` integer, nullable, required
  - `status` 'running' | 'completed' | 'pending', required
  - `running` boolean, required
  - `error` unknown, required
  - `incomplete_details` unknown, required
  - `metadata` object, required
  - `output` object[], required
    - `id` string, required
    - `type` 'message', required
    - `role` 'assistant', required
    - `status` 'completed', required
    - `content` object[], required
      - `type` 'output_text', required
      - `text` string, required
  - `output_text` string, required
  - `structured_output` object, nullable, required
  - `sources` object[], required
    - `id` string, required
    - `type` 'url', required
    - `url` string, required
    - `title` string, nullable, required
  - `files` object[], required
    - `mediaType` string, required
    - `filename` string, nullable, required
    - `url` string, uri, required
    - `size` integer
  - `usage` object
    - `durationMs` integer
  - `messages` unknown[], required
    - unknown
  - `url` string, required — Web URL of the worker in the Handinger dashboard.

## Other responses

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

## Changes

- **2026-07-10** `26ac9ff402ce` — 1 warning
  - removed the optional property `usage/credits` from the response with the `200` status
- **2026-06-03** `f933ba68df7d` — 1 breaking, 2 warning
  - removed the media type `text/event-stream` for the response with the status `200`
  - removed the request property `stream` (media type: application/json)
  - removed the request property `stream` (media type: multipart/form-data)
- **2026-05-15** `15c82f8f15cc` — 1 info
  - added the optional property `files/items/size` to the response with the `200` status
- **2026-05-11** `689cce060c12` — 12 info
  - the `object` response property const value `worker` was added for the status `200`
  - the `role` response property const value `assistant` was added for the status `200`
  - the `status` response property const value `completed` was added for the status `200`
  - the `type` response property const value `message` was added for the status `200`
  - …8 more
- **2026-05-11** `cdb7eec4dd76` — 3 breaking, 1 warning, 5 info
  - added the new required request property `input` (media type: application/json)
  - the request's body type/format changed from ``/`` to `object`/`` (media type: application/json)
  - removed `subschema #1, subschema #2, subschema #3` from the `files` request property `anyOf` list (media type: multipart/form-data)
  - removed `#/components/schemas/CreateWorkerRequest, subschema #2` from the request body `allOf` list (media type: application/json)
  - …5 more

[Full history](https://skmtc.dev/ramensoft/apis/handinger-api/changes/api/tasks/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)