> ## Documentation Index
> Fetch the complete documentation index at: https://docs.getarca.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Create task

> Creates a new task in a workspace.

<Info>
  Requires the `tasks:write` scope. Viewers cannot create tasks.
  Access-restricted members receive `403` if the target `list_id` is outside
  their permitted scope.
</Info>

## Request body

<ParamField body="list_id" type="string" required>
  Numeric ID of the list to place the task in.
</ParamField>

<ParamField body="title" type="string" required>
  Task title.
</ParamField>

<ParamField body="description" type="string">
  Optional task description. Accepts an HTML string.
</ParamField>

<ParamField body="priority" type="string" default="none">
  Task priority. Must be one of `urgent`, `high`, `medium`, `low`, or `none`.
  Defaults to `none` if omitted.
</ParamField>

<ParamField body="status_id" type="string">
  Numeric ID of the workspace status to apply. Must belong to the same
  workspace. If omitted, the task is assigned the first status in the workspace
  with the `pending` category.
</ParamField>

<ParamField body="due_date" type="string">
  Due date in ISO 8601 UTC format (e.g., `"2026-03-25T17:00:00Z"`). A string
  without a timezone suffix is treated as UTC.
</ParamField>

<ParamField body="start_date" type="string">
  Start date in ISO 8601 UTC format.
</ParamField>

<ParamField body="assignee_ids" type="array">
  Optional array of numeric user IDs to assign to the task. All IDs must be
  members of the workspace derived from `list_id`. Invalid or non-member IDs are
  silently ignored. Use `GET /api/v1/workspaces/:id/members` to resolve user IDs
  before calling this endpoint.
</ParamField>

<ParamField body="custom_fields" type="array">
  Optional array of custom field values to set on the new task. Each entry must contain a numeric `id` and a string `value` (or `null` to clear). Only fields that apply to the task's list and are visible to the API key user are applied; other fields are silently ignored.

  ```json theme={null}
  "custom_fields": [
    { "id": 1, "value": "Pro" },
    { "id": 2, "value": "8" }
  ]
  ```
</ParamField>

## Response

Returns the created task. The `identifier` is a workspace-scoped sequential number auto-incremented from the last task in the workspace.

<ResponseField name="id" type="number" required>
  New task identifier.
</ResponseField>

<ResponseField name="workspace_id" type="number" required>
  Workspace this task belongs to.
</ResponseField>

<ResponseField name="list_id" type="number" required>
  List this task belongs to.
</ResponseField>

<ResponseField name="title" type="string" required>
  Task title.
</ResponseField>

<ResponseField name="description" type="string | null">
  Task description. `null` if not provided.
</ResponseField>

<ResponseField name="priority" type="string" required>
  Task priority.
</ResponseField>

<ResponseField name="identifier" type="number" required>
  Auto-assigned workspace-scoped sequential task number.
</ResponseField>

<ResponseField name="due_date" type="string | null">
  UTC ISO-8601 due date. `null` if not set.
</ResponseField>

<ResponseField name="start_date" type="string | null">
  UTC ISO-8601 start date. `null` if not set.
</ResponseField>

<ResponseField name="creator_id" type="number" required>
  User ID of the API key owner (the creator).
</ResponseField>

<ResponseField name="created_at" type="string" required>
  UTC ISO-8601 creation timestamp.
</ResponseField>

<ResponseField name="status" type="object | null">
  Assigned status object. `null` if no status exists in the workspace.

  <Expandable title="Status fields">
    <ResponseField name="id" type="number" required>Status identifier.</ResponseField>
    <ResponseField name="name" type="string" required>Status label.</ResponseField>
    <ResponseField name="icon" type="string | null">Icon.</ResponseField>
    <ResponseField name="color" type="string | null">Color.</ResponseField>
    <ResponseField name="category" type="string" required>One of `pending`, `in_progress`, `completed`, or `cancelled`.</ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="assignees" type="array" required>
  Array of assigned users. Each entry contains `id`, `name`, and `avatar_url`.
  Empty array if no `assignee_ids` were provided.
</ResponseField>

<ResponseField name="custom_fields" type="array" required>
  Custom fields that apply to the new task's list, each with its current value after creation.
  Fields the user does not have access to are not returned.

  <Expandable title="Custom field entry">
    <ResponseField name="id" type="number" required>Custom field identifier.</ResponseField>
    <ResponseField name="name" type="string" required>Custom field name (e.g., `"Customer Tier"`).</ResponseField>

    <ResponseField name="type" type="string" required>
      Field type. One of `text`, `number`, `date`, `checkbox`, `rating`, `dropdown`, `money`, or `people`.
    </ResponseField>

    <ResponseField name="config" type="object | null">
      Type-specific configuration.

      For example:

      * `rating` fields include `icon` and `color`;
      * `dropdown` fields include an `options` array of strings;
      * `money` fields include `currency` and `decimals`.

      It's `null` for field types with no configuration (which are `text`, `number`, `date`, `checkbox` and `people`).
    </ResponseField>

    <ResponseField name="position" type="number" required>Sort position of the field within the workspace.</ResponseField>

    <ResponseField name="value" type="string | null">
      The task's value for this field. `null` when no value has been set.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseExample>
  ```json 201 theme={null}
  {
    "id": 110,
    "workspace_id": 3,
    "list_id": 20,
    "title": "Write unit tests",
    "description": "<p>Cover all service layer methods.</p>",
    "priority": "high",
    "identifier": 14,
    "due_date": "2026-03-30T17:00:00.000Z",
    "start_date": null,
    "creator_id": 1,
    "created_at": "2026-03-18T18:00:00.000Z",
    "status": {
      "id": 1,
      "name": "To Do",
      "icon": "todo",
      "color": "gray",
      "category": "pending"
    },
    "assignees": [
      { "id": 7, "name": "Jane Smith", "avatar_url": null }
    ],
    "custom_fields": [
      {
        "id": 1,
        "name": "Customer Tier",
        "type": "dropdown",
        "config": { "options": ["Free", "Starter", "Pro"] },
        "position": 1,
        "value": "Pro"
      }
    ]
  }
  ```

  ```json 400 theme={null}
  {
    "error": "list_id is required"
  }
  ```

  ```json 401 theme={null}
  {
    "error": "Invalid API key"
  }
  ```

  ```json 403 theme={null}
  {
    "error": "Scope 'tasks:write' is required for this endpoint"
  }
  ```

  ```json 404 theme={null}
  {
    "error": "List not found in this workspace"
  }
  ```
</ResponseExample>