Reference Data
How integrations read workspaces, spots, users, task types, statuses, priorities, teams, templates, and tags.
Reference data endpoints require ext:read.
Use them before task creation or task updates so the external system can select the right workspace, task type, status, priority, user, tag, or spot.
API-key callers only receive rows the key creator is allowed to view.
Workspaces
GET /api/v1/workspaces?tenantId=<tenant-id>Returns active workspaces for the tenant, sorted by name for API-key callers.
Typical fields include:
| Field | Description |
|---|---|
_id | Convex workspace ID. Use this as workspaceId in task creation. |
pgId | Legacy numeric ID when present. |
name | Workspace display name. |
slug | Optional route-friendly name. |
teams | Team IDs with access when present. |
allowedCategoryIds | Task types allowed in the workspace when configured. |
Spots
GET /api/v1/spots?tenantId=<tenant-id>Returns tenant spots or physical locations.
Typical fields include:
| Field | Description |
|---|---|
_id | Convex spot ID. Use this as spotId in task creation. |
pgId | Legacy numeric ID when present. |
name | Spot display name. |
spotTypeId | Type/classification when configured. |
parentId | Parent spot for nested location structures. |
Users
GET /api/v1/users?tenantId=<tenant-id>Returns active users for the tenant.
Typical fields include:
| Field | Description |
|---|---|
_id | Convex user ID. Use this in task creation userIds. |
pgId | Legacy numeric ID when present. |
name | User display name. |
email | User email. |
apodo | Optional nickname. |
Task Types / Categories
GET /api/v1/categories?tenantId=<tenant-id>Optional filters:
| Query | Description |
|---|---|
workspaceId | Return categories linked to a workspace when the category row carries workspace scope. |
Use _id as categoryId when creating or updating tasks.
Statuses
GET /api/v1/statuses?tenantId=<tenant-id>&categoryId=<category-id>Use _id as statusId. Statuses may carry fields such as action, initial, and final; integrations should not assume status names are stable across tenants.
Priorities
GET /api/v1/priorities?tenantId=<tenant-id>&categoryId=<category-id>Use _id as priorityId.
Teams
GET /api/v1/teams?tenantId=<tenant-id>Use _id as teamId when an integration needs to set or update task ownership.
Templates
GET /api/v1/templates?tenantId=<tenant-id>&workspaceId=<workspace-id>&categoryId=<category-id>Use _id as templateId. Template and task-type policy can affect allowed task creation fields.
Tags
GET /api/v1/tags?tenantId=<tenant-id>Use _id values with /api/v1/task-tags.
Caching Guidance
Reference data can be cached by the external system, but integrations should refresh when an ID is missing, a task write fails because a referenced object no longer exists, or tenant admins change workspace/team structure.