Tasks

External task operations use the same visibility, permission, and workflow policy as product workflows. API keys act as the user who created the key.

Minimal Task

{
  "tenantId": "hotel-1",
  "name": "Inspect room 304",
  "workspaceId": "j57..."
}

Required fields:

Field	Description
`tenantId`	Tenant identifier for the task.
`name`	Human-readable task title.
`workspaceId`	Convex workspace ID from `GET /api/v1/workspaces`.

Optional Assignments

Add userIds to assign users at creation time:

{
  "tenantId": "hotel-1",
  "name": "Deliver crib to room 512",
  "workspaceId": "j57...",
  "userIds": ["k97...", "n42..."]
}

Optional Location

Add spotId to attach a physical location:

{
  "tenantId": "hotel-1",
  "name": "Check pool towels",
  "workspaceId": "j57...",
  "spotId": "m22..."
}

Optional Task Metadata

Task creation also accepts optional Convex IDs returned from reference endpoints:

Field	Source
`categoryId`	`GET /api/v1/categories`
`teamId`	`GET /api/v1/teams`
`templateId`	`GET /api/v1/templates`
`statusId`	`GET /api/v1/statuses`
`priorityId`	`GET /api/v1/priorities`
`slaId`	Internal SLA configuration, when exposed to the integration.
`dueDate`	Unix timestamp in milliseconds.
`startDate`	Unix timestamp in milliseconds.
`latitude` / `longitude`	Optional coordinates.
`reportedByTeamId` / `reportedByUserId`	Reporting context, when allowed by task policy.

Response

{
  "id": "j97...",
  "pgId": 1234
}

Use id for future Convex-native references. pgId is returned when a legacy numeric identifier exists.

Read Tasks

GET /api/v1/tasks?tenantId=<tenant-id>&limit=100

Supported filters:

Query	Description
`taskId`	Fetch one visible task by Convex ID.
`pgId`	Fetch one visible task by legacy numeric ID.
`workspaceId`	Filter by workspace.
`statusId`	Filter by status.
`priorityId`	Filter by priority.
`categoryId`	Filter by category/task type.
`teamId`	Filter by team.
`spotId`	Filter by spot/location.
`templateId`	Filter by template.
`assignedTo=me`	Tasks assigned to the API-key creator.
`assignedTo=<userId>`	Tasks assigned to a specific user.
`search`	Case-insensitive match against task name and description.
`limit`	Maximum rows from `1` to `500`; defaults to `100` and is clamped by the server.

Only tasks visible to the key creator are returned.

Update a Task

PATCH /api/v1/tasks

{
  "tenantId": "hotel-1",
  "taskId": "j97...",
  "updates": {
    "description": "Updated from automation",
    "statusId": "s12...",
    "priorityId": "p34..."
  }
}

Allowed update fields are name, description, statusId, priorityId, teamId, spotId, categoryId, templateId, dueDate, startDate, latitude, and longitude.

Status changes require normal status-change permission, owning-team access, and workflow validity. Fields can also be restricted by field-permission policy.

Delete a Task

DELETE /api/v1/tasks?tenantId=<tenant-id>&taskId=<task-id>

This soft-deletes a visible task and requires delete-task permission.

Comments and Attachments

List comments:

GET /api/v1/task-comments?tenantId=<tenant-id>&taskId=<task-id>

Create a comment:

POST /api/v1/task-comments

{
  "tenantId": "hotel-1",
  "taskId": "j97...",
  "note": "Comment from automation"
}

The same endpoint accepts source: "task_attachment" and an attachments array when the integration already has valid storage IDs.

Assignments

GET /api/v1/task-assignments?tenantId=<tenant-id>&taskId=<task-id>
POST /api/v1/task-assignments

{
  "tenantId": "hotel-1",
  "taskId": "j97...",
  "mode": "add",
  "userIds": ["u12..."]
}

mode can be set, add, or remove.

Logs

GET /api/v1/task-logs?tenantId=<tenant-id>&taskId=<task-id>

Returns task logs visible to the key creator.

Approval and Acknowledgment Actions

Approve or reject a visible approval context:

POST /api/v1/task-approval

{
  "tenantId": "hotel-1",
  "taskId": "j97...",
  "contextId": "optional-context-id",
  "decision": "approved",
  "comment": "Looks good"
}

Acknowledge a visible acknowledgment context:

POST /api/v1/task-acknowledgment

{
  "tenantId": "hotel-1",
  "taskId": "j97...",
  "contextId": "optional-context-id",
  "comment": "Acknowledged"
}

Implementation Notes

API-key task creation records the key creator as the acting user.
Task reads and writes are permission-checked as that creator.
Optional fields can be added in v1 when they are backward compatible.
Invalid JSON or missing required fields returns 400.
Missing, invalid, expired, inactive, wrong-tenant, or under-scoped credentials return 401.