Create Task Activity

POST /api/activities/tasks

Create a TASK-type activity with route and operator assignment. Task activities require routeId and operatorId in addition to the base activity fields.

Auth: Required — CREATE_ACTIVITY permission

Request Body

Field	Type	Required	Description
`reason`	string	Yes	Reason for creating the task
`channel`	string	Yes	Channel for dispatch
`commerce_id`	UUID	Yes	Target commerce
`idempotency_key`	string	Yes	Unique per tenant
`assigned_route_id`	UUID	Yes	Assigned route
`assigned_operator_id`	UUID	Yes	Assigned operator
`scheduled_at`	ISO 8601	Yes	Scheduled execution time
`suggested_execution_time`	ISO 8601	No	Suggested time for execution
`user_status`	string	No	User status context
`score`	integer	No	Priority score
`assignment_reason`	string	No	Reason for the assignment
`target_criteria`	array	No	Override target resolution criteria
`attribute_keys`	string[]	No	Attribute key names to resolve via policies
`attributes`	array	No	Caller-provided attribute values (objects with `key`, `value`, `fallback`)

Example

curl -X POST https://api.reten.ai/api/activities/tasks \
  -H "Authorization: Bearer <token>" \
  -H "x-tenant-id: <tenant-id>" \
  -H "Content-Type: application/json" \
  -d '{
    "reason": "Monthly visit",
    "channel": "SALESMAN",
    "commerce_id": "880e8400-e29b-41d4-a716-446655440000",
    "idempotency_key": "task-2025-01-15-001",
    "assigned_route_id": "dd0e8400-e29b-41d4-a716-446655440000",
    "assigned_operator_id": "cc0e8400-e29b-41d4-a716-446655440000",
    "scheduled_at": "2025-01-16T09:00:00.000Z",
    "attribute_keys": ["commerce_info", "promotions"]
  }'

const response = await fetch("https://api.reten.ai/api/activities/tasks", {
  method: "POST",
  headers: {
    "Authorization": "Bearer <token>",
    "x-tenant-id": "<tenant-id>",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    reason: "Monthly visit",
    channel: "SALESMAN",
    commerce_id: "880e8400-e29b-41d4-a716-446655440000",
    idempotency_key: "task-2025-01-15-001",
    assigned_route_id: "dd0e8400-e29b-41d4-a716-446655440000",
    assigned_operator_id: "cc0e8400-e29b-41d4-a716-446655440000",
    scheduled_at: "2025-01-16T09:00:00.000Z",
    attribute_keys: ["commerce_info", "promotions"],
  }),
});
const task = await response.json();

import requests

response = requests.post(
    "https://api.reten.ai/api/activities/tasks",
    headers={
        "Authorization": "Bearer <token>",
        "x-tenant-id": "<tenant-id>",
    },
    json={
        "reason": "Monthly visit",
        "channel": "SALESMAN",
        "commerce_id": "880e8400-e29b-41d4-a716-446655440000",
        "idempotency_key": "task-2025-01-15-001",
        "assigned_route_id": "dd0e8400-e29b-41d4-a716-446655440000",
        "assigned_operator_id": "cc0e8400-e29b-41d4-a716-446655440000",
        "scheduled_at": "2025-01-16T09:00:00.000Z",
        "attribute_keys": ["commerce_info", "promotions"],
    },
)
task = response.json()

Response `201 Created`

{
  "id": "ee0e8400-e29b-41d4-a716-446655440000",
  "type": "TASK",
  "channel": "SALESMAN",
  "status": "READY",
  "taskDetails": {
    "assignedRouteId": "dd0e8400-e29b-41d4-a716-446655440000",
    "assignedOperatorId": "cc0e8400-e29b-41d4-a716-446655440000"
  }
}

Error Responses

Status	Description
`400`	Validation error
`404`	Commerce, route, or operator not found
`409`	Idempotency key already exists