Transition tasks

POST/api/v1/tasks/{taskId}/transition

Authorization
Permission	`task.update`
Workspace scope	required
Scope target	workspace

Parameters

Path parameters
Field	Type	Required	Nullable	Default
taskId	string	required	non-null	—

Query parameters: none.

Request body

Request body fields
Field	Type	Required	Nullable	Default
toStateKey	string	required	non-null	—
expectedStateKey	string	optional	non-null	—
reason	string	optional	non-null	—

Response

200

Response fields
Field	Type	Required	Nullable	Default
data	object	required	non-null	—
data.taskId	string	required	non-null	—
data.lifecycleDefinitionId	string	required	non-null	—
data.lifecycleRevision	number	required	non-null	—
data.stateKey	string	required	non-null	—
data.status	string	required	non-null	—
data.updatedAt	string	required	non-null	—
data.document	object	required	non-null	—
data.document.companyId	string	required	non-null	—
data.document.workspaceId	unknown	optional	non-null	—
data.document.title	string	required	non-null	—
data.document.workflowInstanceId	unknown	optional	non-null	—
data.document.targetRef	unknown	optional	non-null	—
data.document.createdAt	string	required	non-null	—
data.document.updatedAt	string	required	non-null	—
data.document.dueAt	unknown	optional	non-null	—
data.document.expiresAt	unknown	optional	non-null	—
data.document.taskId	string	required	non-null	—
data.document.fields	unknown	optional	non-null	—
data.document.description	unknown	optional	non-null	—
data.document.taskType	"pipeline_update" \| "qa_verification" \| "reengagement" \| "general" \| "recurring_reminder" \| "email_review" \| "meeting_notes" \| "follow_up" \| "follow_up_reminder" \| "campaign_monitor" \| "workflow_review" \| "approval" \| "schedule-meeting"	required	non-null	—
data.document.status	"idea" \| "open" \| "planned" \| "in_progress" \| "review" \| "blocked" \| "completed" \| "cancelled" \| "pending" \| "approved" \| "dismissed" \| "expired"	required	non-null	—
data.document.priority	"high" \| "normal" \| "low"	required	non-null	"normal"
data.document.lifecycleDefinitionId	unknown	optional	non-null	—
data.document.lifecycleRevision	unknown	optional	non-null	—
data.document.stateKey	unknown	optional	non-null	—
data.document.entityType	unknown	optional	non-null	—
data.document.entityId	unknown	optional	non-null	—
data.document.emailDraftId	unknown	optional	non-null	—
data.document.suggestedAction	unknown	optional	non-null	—
data.document.sourceType	unknown	optional	non-null	—
data.document.sourceEntity	unknown	optional	non-null	—
data.document.sourceId	unknown	optional	non-null	—
data.document.statusChangedAt	unknown	optional	non-null	—
data.document.statusChangedBy	unknown	optional	non-null	—
data.document.assignedAt	unknown	optional	non-null	—
data.document.assignedBy	unknown	optional	non-null	—
data.document.routingRuleId	unknown	optional	non-null	—
data.document.assignmentRevision	unknown	optional	non-null	—
data.document.activeAgentAttemptId	unknown	optional	non-null	—
data.document.agentAttemptCount	unknown	optional	non-null	—
data.document.lockedBy	unknown	optional	non-null	—
data.document.lockedAt	unknown	optional	non-null	—
data.document.lockTtlSeconds	unknown	optional	non-null	—
data.document.context	unknown	optional	non-null	—
data.document.ttl	unknown	optional	non-null	—

Declared failures

Declared failures
TASK_CAPABILITY_UNAVAILABLE	503 — retryable
TASK_NOT_FOUND	404 — not retryable
TASK_NOT_TERMINAL	409 — not retryable
TASK_PRINCIPAL_NOT_ASSIGNABLE	422 — not retryable
TASK_STATE_STALE	409 — retryable
TASK_TRANSITION_NOT_SUPPORTED	422 — not retryable

Readback

Read the result back with:

tasks.get

Request example

Schematic only. Replace placeholders with real values and include all required nested fields.

POST /api/v1/tasks/{taskId}/transition HTTP/1.1
Authorization: Bearer <token>
x-merulan-workspace-id: <workspace-id>
Content-Type: application/json

{
  "toStateKey": "<toStateKey>"
}