---
title: "Start a task recording"
method: POST
path: "/api/task-creations"
---

# Start a task recording

`POST /api/task-creations`

## Request

- Base URL: `https://www.toma.com`
- URL: `https://www.toma.com/api/task-creations`
- Auth: one of:
  - HTTP bearer
  - API key in cookie `better-auth.session_token`

Creates a version-3 task preparation ready for recording without a title, description, or initial model call. Optional supplied wording is retained. Each member can have one unfinished new-task draft. A second start returns 409 with its recovery link; list with state=draft to resume, or explicitly discard the draft before starting another. Drafts survive closing, navigation, and processing failures until published or cancelled. Published-task revisions remain independent. Use the private recording link by default, or add a completed external screen recording through evidence with recordingMode set to screen. Every unpublished task requires a screen walkthrough with meaningful narration; supplied text and Context supplement it. The owner can explicitly accept an inconclusive content check for its current fingerprint through accept-recording. Explicitly call analyze to validate the recording, freeze Context, and begin understanding. Final approval and publication are separate operations.

## Request body

- object
  - `title` string: Write every newly generated title as a short proposition requesting work: for example, "Help me build a personal website", "I need my research organized", or "Get my report export working". Use a concrete action and desired result, never just a deliverable label such as "Personal website". Use sentence case without a trailing period, preserving proper names and acronyms.
  - `description` string

## Response `201`

A private recording link with an expiring token in its fragment. Keep it private.

- TaskCreationLink
  - `recordingRequirement` object
    - `required` boolean, required
    - `status` 'exempt' | 'missing' | 'processing' | 'checking' | 'passed' | 'rejected' | 'unavailable', required
    - `reason` 'missing_video' | 'missing_narration' | 'not_screen' | 'unrelated' | 'uncertain' | 'media_unavailable' | 'provider_unavailable'
    - `fingerprint` string
  - `id` string, required
  - `recordingUrl` string, required
  - `expiresAt` string, required
  - `status` 'preparing' | 'recording' | 'processing' | 'review' | 'rendering' | 'context_preparing' | 'context' | 'generating' | 'ready' | 'publishing' | 'published' | 'discarded' | 'failed', required
  - `revision` integer
  - `costs` object
    - `listingFeeCents` integer, required
    - `summary` string, required
  - `workflow` object
    - `stage` 'record' | 'analyze' | 'review', required
    - `state` 'input_needed' | 'ready_to_analyze' | 'processing' | 'asks' | 'review' | 'failed' | 'published' | 'discarded', required
    - `reviewUrl` string, required
    - `next` object, required
      - `kind` 'tool' | 'human' | 'wait' | 'done', required
      - `reason` string, required
      - `tool` string
      - `arguments` object
      - `url` string
    - `asks` object[], required
      - `id` string, required
      - `kind` 'clarification' | 'access' | 'correction', required
      - `prompt` string, required
      - `reason` string
      - `options` string[], required
      - `answerArguments` object, required
    - `saveDraft` object
      - `tool` string, required
      - `arguments` object, required
    - `publication` object, required
      - `tool` string, required
      - `arguments` object, required
      - `requiresHumanApproval` true, required
      - `recordingMediaPublic` true, required
      - `listingFeeCents` integer, required
      - `requiredAcknowledgements` string[], required
      - `pendingComments` boolean, required

## Other responses

- `400`: Invalid input.
- `401`: Sign in or use a valid recording capability.
- `404`: Not found, expired, revoked, or owned by another member.
- `409`: The revision, take, upload sequence, or processing state changed. Fetch the current session.
- `503`: Processing or storage is unavailable. No publication was made.

---

[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)