Skip to main content
POST
/
api
/
v1
/
tasks
Create task
curl --request POST \
  --url https://api.getarca.app/api/v1/tasks \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "list_id": "<string>",
  "title": "<string>",
  "description": "<string>",
  "priority": "<string>",
  "status_id": "<string>",
  "due_date": "<string>",
  "start_date": "<string>",
  "assignee_ids": [
    {}
  ],
  "custom_fields": [
    {}
  ]
}
'
{
  "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"
    }
  ]
}
Requires the tasks:write scope. Viewers cannot create tasks. Access-restricted members receive 403 if the target list_id is outside their permitted scope.

​
Request body

​
list_id
string
required
Numeric ID of the list to place the task in.
​
title
string
required
Task title.
​
description
string
Optional task description. Accepts an HTML string.
​
priority
string
default:"none"
Task priority. Must be one of urgent, high, medium, low, or none. Defaults to none if omitted.
​
status_id
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.
​
due_date
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.
​
start_date
string
Start date in ISO 8601 UTC format.
​
assignee_ids
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.
​
custom_fields
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.
"custom_fields": [
  { "id": 1, "value": "Pro" },
  { "id": 2, "value": "8" }
]

​
Response

Returns the created task. The identifier is a workspace-scoped sequential number auto-incremented from the last task in the workspace.
​
id
number
required
New task identifier.
​
workspace_id
number
required
Workspace this task belongs to.
​
list_id
number
required
List this task belongs to.
​
title
string
required
Task title.
​
description
string | null
Task description. null if not provided.
​
priority
string
required
Task priority.
​
identifier
number
required
Auto-assigned workspace-scoped sequential task number.
​
due_date
string | null
UTC ISO-8601 due date. null if not set.
​
start_date
string | null
UTC ISO-8601 start date. null if not set.
​
creator_id
number
required
User ID of the API key owner (the creator).
​
created_at
string
required
UTC ISO-8601 creation timestamp.
​
status
object | null
Assigned status object. null if no status exists in the workspace.
​
assignees
array
required
Array of assigned users. Each entry contains id, name, and avatar_url. Empty array if no assignee_ids were provided.
​
custom_fields
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.
{
  "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"
    }
  ]
}