Create tasks
POST /api/v1/tasks: request fields and declared response contract.
POST/api/v1/tasks
| Permission | task.create |
|---|---|
| Workspace scope | required |
| Scope target | workspace |
Request body
| Field | Type | Required | Nullable | Default |
|---|---|---|---|---|
| title | string | required | non-null | — |
| workflowInstanceId | string | optional | nullable | — |
| targetRef | object | optional | nullable | — |
| targetRef.kind | string | required | non-null | — |
| targetRef.id | string | required | non-null | — |
| dueAt | string | optional | nullable | — |
| expiresAt | string | optional | nullable | — |
| responsiblePrincipal | object | optional | nullable | — |
| responsiblePrincipal.kind | string | required | non-null | — |
| responsiblePrincipal.id | string | required | non-null | — |
| description | string | optional | nullable | — |
| 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 | — |
| priority | "high" | "normal" | "low" | optional | non-null | "normal" |
| entityType | string | optional | nullable | — |
| entityId | string | optional | nullable | — |
| emailDraftId | string | optional | nullable | — |
| suggestedAction | object | optional | nullable | — |
| routingRuleId | string | optional | nullable | — |
| sourceType | "ai" | "system" | "user" | optional | nullable | — |
| sourceEntity | string | optional | nullable | — |
| sourceId | string | optional | nullable | — |
| context | object | optional | nullable | — |
| context.type | string | required | non-null | — |
| context.instanceId | string | optional | nullable | — |
| context.blockId | string | optional | nullable | — |
| context.templateId | string | optional | nullable | — |
| context.credential | object | optional | nullable | — |
| context.credential.attemptId | string | optional | non-null | — |
| context.credential.pauseGeneration | string | optional | non-null | — |
| context.credential.grantId | string | required | non-null | — |
| context.credential.grantRevision | integer | required | non-null | — |
| context.credential.requirementKey | string | required | non-null | — |
| context.credential.capability | string | required | non-null | — |
| context.credential.purpose | string | required | non-null | — |
| status | "idea" | "open" | "planned" | "in_progress" | "review" | "blocked" | "completed" | "cancelled" | "pending" | "approved" | "dismissed" | "expired" | optional | non-null | — |
Response
201
| Field | Type | Required | Nullable | Default |
|---|---|---|---|---|
| data | object | required | non-null | — |
| data.companyId | string | required | non-null | — |
| data.workspaceId | unknown | optional | non-null | — |
| data.title | string | required | non-null | — |
| data.workflowInstanceId | unknown | optional | non-null | — |
| data.targetRef | unknown | optional | non-null | — |
| data.createdAt | string | required | non-null | — |
| data.updatedAt | string | required | non-null | — |
| data.dueAt | unknown | optional | non-null | — |
| data.expiresAt | unknown | optional | non-null | — |
| data.taskId | string | required | non-null | — |
| data.fields | unknown | optional | non-null | — |
| data.description | unknown | optional | non-null | — |
| data.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.status | "idea" | "open" | "planned" | "in_progress" | "review" | "blocked" | "completed" | "cancelled" | "pending" | "approved" | "dismissed" | "expired" | required | non-null | — |
| data.priority | "high" | "normal" | "low" | required | non-null | "normal" |
| data.lifecycleDefinitionId | unknown | optional | non-null | — |
| data.lifecycleRevision | unknown | optional | non-null | — |
| data.stateKey | unknown | optional | non-null | — |
| data.entityType | unknown | optional | non-null | — |
| data.entityId | unknown | optional | non-null | — |
| data.emailDraftId | unknown | optional | non-null | — |
| data.suggestedAction | unknown | optional | non-null | — |
| data.sourceType | unknown | optional | non-null | — |
| data.sourceEntity | unknown | optional | non-null | — |
| data.sourceId | unknown | optional | non-null | — |
| data.statusChangedAt | unknown | optional | non-null | — |
| data.statusChangedBy | unknown | optional | non-null | — |
| data.assignedAt | unknown | optional | non-null | — |
| data.assignedBy | unknown | optional | non-null | — |
| data.routingRuleId | unknown | optional | non-null | — |
| data.assignmentRevision | unknown | optional | non-null | — |
| data.activeAgentAttemptId | unknown | optional | non-null | — |
| data.agentAttemptCount | unknown | optional | non-null | — |
| data.lockedBy | unknown | optional | non-null | — |
| data.lockedAt | unknown | optional | non-null | — |
| data.lockTtlSeconds | unknown | optional | non-null | — |
| data.context | unknown | optional | non-null | — |
| data.ttl | unknown | optional | non-null | — |
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 HTTP/1.1
Authorization: Bearer <token>
x-merulan-workspace-id: <workspace-id>
Content-Type: application/json
{
"title": "<title>",
"taskType": "pipeline_update"
}