Skip to main content
POST
Create task

Authorizations

Authorization
string
header
required

Company API key (mwk_) or personal access token (mel_). A PAT requires X-Workspace-ID on company-scoped routes. An API key implies its own company.

Headers

X-Workspace-ID
string<uuid>

Company UUID for a personal token on company-scoped operations. A company API key already binds its company.

Body

application/json
repositories
object[]

At most 20 repository grants, fixed at Task creation. Requires an admin company key and an enabled integration broker. Each grant names a canonical GitHub HTTPS URL, read or write permission and a credential_reference identifying an authorization grant, never a token. The broker response must contain token, expires_at and permission matching the request. expires_at must be more than 30 seconds and at most 70 minutes after the exchange validation time. This expiry rule applies to the broker response, not to a Task creation field.

Maximum array length: 20
metadata
object

A flat map of strings, numbers and booleans with at most 50 keys. Keys match ^[a-zA-Z_][a-zA-Z0-9_.-]{0,63}$. The encoded create value and stored JSONB each have an 8 KiB limit; storage size is checked by the server, not by a JSON Schema character limit. Null values, arrays and nested objects are rejected.

instructions
string

Immutable guidance for every Run on the Task. At most 32768 UTF-8 bytes and no NUL characters. The server checks bytes, not Unicode character count. Run credentials cannot configure this field.

Pattern: ^[^]*$
callback_url
string
client_request_id
string
title
string
description
string | null
parent_task_id
string | null
area_id
string | null
attachment_ids
string[]
origin_type
string | null
origin_id
string | null
allow_duplicate
boolean
execution
object | null
start
boolean | null
input
string
isolated
boolean
execution_identity_id
string
mcp_servers
object[]

At most 10 servers with unique, non-reserved names. Each server uses exactly one of a remote HTTPS url or a stdio command. headers belong to remote servers; args and env belong to stdio servers. The encrypted set is limited to 64 KiB; the server rejects a larger sealed set with HTTP 413. This encrypted-size limit cannot be measured as JSON character count. Header and environment values are write-only; GET returns McpServerSummary objects.

Maximum array length: 10

Response

TaskResponse with the same derived fields as GET /api/tasks/{id}, plus the initial run_id when a Run was created. A client_request_id replay returns the original Task in its current state and the same run_id; see Idempotency. The response never includes mcp_servers; read them with GET /api/tasks/{id}/mcp-servers.

execution
object | null
required
id
string
required
workspace_id
string
required
number
integer
required
identifier
string
required
title
string
required
description
string | null
required
status
enum<string>
required
Available options:
cancelled,
done,
working,
paused,
needs_you,
to_review,
idle
delivered_at
string | null
required
completed_at
string | null
required
cancelled_at
string | null
required
creator_type
string
required
creator_id
string
required
parent_task_id
string | null
required
area_id
string | null
required
created_at
string
required
updated_at
string
required
origin_type
string | null
required
metadata
object
required
isolated
boolean
required
execution_identity_id
string | null
participant_member_ids
string[]
participant_harnesses
string[]
has_pending_interaction
boolean
has_active_run
boolean
has_paused_run
boolean
attention_reason
string
failure_reason
string
failure_class
string
unread
boolean
viewer_participated
boolean
pull_request
object | null
attachments
object[]
run_id
string | null