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"]
  }'

import axios from 'axios';

const response = await axios.post(
  'https://api.reten.ai/api/activities/tasks',
  {
    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'],
  },
  {
    headers: {
      Authorization: 'Bearer <token>',
      'x-tenant-id': '<tenant-id>',
    },
  }
);

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