---
title: "Cancel hired work"
method: POST
path: "/api/tasks/{id}/cancel"
---

# Cancel hired work

`POST /api/tasks/{id}/cancel`

## Request

- Base URL: `https://www.toma.com`
- URL: `https://www.toma.com/api/tasks/{id}/cancel`
- Auth: one of:
  - HTTP bearer
  - API key in cookie `better-auth.session_token`

The member hired for the task (or Toma staff) cancels it before approval. The hire's application becomes cancelled, the task reopens (applicants the hire declined wait again), and the poster gets the quote back; fees aren't refunded. Same as the cancel_work MCP tool.

## Path parameters

- `id` string, required

## Response `200`

The cancelled hire's work; the task is open again.

- TaskWork
  - `taskId` string, required
  - `title` string, required
  - `quote` integer, nullable, required: The hired worker's quote in whole US dollars: what they are paid. Null only on a hire made by an older release of Toma.
  - `status` 'open' | 'in_progress' | 'submitted' | 'changes_requested' | 'rating' | 'completed' | 'closed', required
  - `statusLabel` string, required
  - `reason` string, required: What the task waits on and from whom; the same line for both sides.
  - `role` 'poster' | 'worker' | 'admin', required: The caller's part in this task.
  - `workerId` string, required: The member hired to do it.
  - `cancelRequestedAt` string, date-time, nullable, required: When the poster asked to cancel; the worker confirms with POST /api/tasks/{id}/cancel.
  - `submissions` Submission[], required: Newest first.
    - `id` string, required
    - `round` integer, required: 1 for the first turn-in; one more after each request for changes.
    - `body` string, required: The work as Markdown.
    - `links` object[], required
      - `url` string, uri, required
      - `label` string, nullable, required
    - `files` object[], required: Files from the task's worker folder turned in with this round; read them through the task files endpoints. Turned-in files can't be renamed or deleted.
      - `id` string, required
      - `path` string, required
      - `size` integer, required
    - `model` string, nullable, required: The AI model that generated it; null when a person turned it in.
    - `status` 'submitted' | 'changes_requested' | 'approved', required
    - `statusLabel` string, required
    - `feedback` string, nullable, required: What the poster asked to change.
    - `createdAt` string, date-time, required
    - `decidedAt` string, date-time, nullable, required
  - `ratings` object, required: The hire's ratings. The poster rates when approving; until the worker rates back, each side sees only their own and staff see neither.
    - `byPoster` WorkRating, required
      - `score` integer, required
      - `description` string, required
      - `createdAt` string, date-time, required
    - `byWorker` WorkRating, required
      - `score` integer, required
      - `description` string, required
      - `createdAt` string, date-time, required
  - `actions` string[], required: The steps the caller can take now. In rating, rate is the worker's rating of the poster (POST /api/tasks/{id}/rating), which completes the task and pays them. remind: the task waits on the other side, who can be nudged with POST /api/tasks/{id}/remind.

## Other responses

- `403`: The caller requested this task; ask with POST /api/me/tasks/{id}/cancel-request.
- `404`: The caller has no hired task with that id.
- `409`: The work was already approved or completed.

---

[API](https://skmtc.dev/toma/apis/toma-api.md) - [All operations](https://skmtc.dev/toma/apis/toma-api/llms.txt) - [OpenAPI document](https://skmtc.dev/toma/apis/toma-api/revisions/b4e56e1db5a2?raw)