# Create a task

> `POST` `/v1/tasks`

URL: https://www.agencytitan.com/docs/tag/tasks/POST/v1/tasks

Operation ID: `tasks_create`

Tag: [tasks](https://www.agencytitan.com/docs/tag/tasks.md)

## Description

Creates one task through the live privacy-aware task-creation domain path. For the simple path, pass `process_definition_id` and `name`; the server resolves the configured primary name field and maps the title to its field-definition UUID. Use `field_values` only for additional fields or when intentionally overriding the same primary field. The command applies process field defaults, saves initial custom field values, associates an optional client, sets due date and assignment, materializes every task stage, and atomically applies privacy. Paid process definitions debit the tenant platform fund on successful insert; when the balance is insufficient, the same RPC queues a deferred-creation intent and returns `creation_status=queued` with no task id. The funds gate cannot be bypassed through this operation. A queued task cannot be linked to a ticket until it is materialized.

## Parameters

_None_

## Request body

- Required: yes
- Content-Type: `application/json`
  - Type: `object`
  - Properties:
    - `assigned_to` (`array<string>`) — Initial parent-task assignees. Private creation also ensures the caller remains assigned.
    - `client_id` (`string|null`) — Client to associate, or null for a process definition that does not require a client.
    - `due_date` (`string|null`) — Initial parent-task due date.
    - `field_values` (`object`) — Initial custom field values keyed by task field definition UUID. Usually omit the primary name field and pass name inst…
    - `is_private` (`boolean`) — Whether the task is private at creation time, including if creation is deferred.
    - `name` (`string`) — Simple task title. The server trims it and maps it to the process definition's configured primary name field. If field_…
    - `process_definition_id` (`string`, required) — Active process definition to instantiate as a task.

## Responses

- `200` (`application/json`): Successful response.
  - Type: `object`
  - Properties:
    - `data` (`object`, required)
- `400` (`application/json`): Request validation failed (unknown or out-of-range parameters/properties are rejected).
  - Type: `object`
  - Properties:
    - `error` (`object`, required)
- `401` (`application/json`): Missing, invalid, expired, or revoked bearer token.
  - Type: `object`
  - Properties:
    - `error` (`string`, required)
    - `error_description` (`string`, required)
- `403` (`application/json`): The authenticated user does not have permission for this operation.
  - Type: `object`
  - Properties:
    - `error` (`object`, required)
- `404` (`application/json`): The requested resource was not found.
  - Type: `object`
  - Properties:
    - `error` (`object`, required)
- `409` (`application/json`): The request conflicts with an existing record or partially applied.
  - Type: `object`
  - Properties:
    - `error` (`object`, required)
- `429` (`application/json`): Per-tenant rate limit exceeded (600 requests/minute across all /v1 REST endpoints). The Retry-After header indicates how many seconds to wait.
  - Type: `object`
  - Properties:
    - `error` (`object`, required)
- `500` (`application/json`): An unexpected internal error occurred.
  - Type: `object`
  - Properties:
    - `error` (`object`, required)

## Authentication

- `bearerAuth` — http (bearer) — All /v1 endpoints (except `/v1/openapi.json` and `/v1/llms.txt`) require a bearer token. Two equal first-class paths: (1) an OAuth 2.0 access token from the au…

## Useful links

- Interactive page: https://www.agencytitan.com/docs/tag/tasks/POST/v1/tasks
- API reference home: https://www.agencytitan.com/docs/
- Tag page: https://www.agencytitan.com/docs/tag/tasks.md
- This operation as Markdown: https://www.agencytitan.com/docs/tag/tasks/POST/v1/tasks.md
- OpenAPI JSON: https://www.agencytitan.com/docs/openapi.json
- Full API Markdown: https://api.agencytitan.com/v1/llms.txt
- API keys: https://app.agencytitan.com/settings/api-mcp