API Reference

The External API is the API exposed by keys created in Settings → Integrations → API Keys.

Base URL: https://cvx-share.whagons.com/api/v1
OpenAPI:  https://docs.whagons.com/openapi/whagons-v1.json

New integrations should use /api/v1/*. The production gateway also serves /api/ext/* as compatibility aliases for existing integrations.

Authentication and scopes

Send a Settings-issued key in either header form:

X-API-Key: whg_live_...

Authorization: Bearer whg_live_...

Keys currently receive both scopes when created in Settings. Every API-key call acts as the user who created the key and is evaluated against that user's current tenant permissions, teams, workspace visibility, and task access.

Endpoint index

Paths in the sections below are relative to the v1 base URL.

Request conventions

• tenantId is required on every API-key request. On reads it is a query parameter; on writes it is in the JSON body.
• tenantId must exactly match the tenant attached to the key.
• Resource IDs are opaque Convex IDs. Read them from Whagons instead of constructing them.
• Dates such as dueDate and startDate are Unix timestamps in milliseconds.
• Request bodies use Content-Type: application/json.
• List endpoints currently return JSON arrays directly; responses are not wrapped in a data envelope.
• There is not yet a cursor-pagination contract. GET /tasks instead accepts a bounded limit.

Session

GET /me/tenants

Lists tenants for the signed-in first-party Whagons user. This route uses the product's user session and does not accept a tenant API key. Server-to-server integrations normally already know their tenantId and do not need this endpoint.

Reference data

All reference-data calls require tenantId and ext:read. They return arrays of Whagons row objects. Common fields include _id, _creationTime, tenantId, name, and an optional legacy pgId; each resource can include additional configuration fields.

Example:

curl --request GET \
  --url 'https://cvx-share.whagons.com/api/v1/workspaces?tenantId=hotel-1' \
  --header 'X-API-Key: whg_live_REPLACE_ME'

Tasks

GET /tasks

With taskId or pgId, returns one visible task object. Without either identity, returns a newest-first array of visible tasks.

Task visibility is applied after filters. A caller never receives tasks outside the key creator's current permissions.

POST /tasks

Creates a task and optionally assigns users.

Minimal body:

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

Response:

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

pgId can be null or absent when no legacy numeric identity exists.

PATCH /tasks

Requires tenantId and taskId. Put changes in updates, or send the same update fields at the top level. When updates is present, it is used as the update source.

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

Allowed fields are name, description, statusId, priorityId, teamId, spotId, categoryId, templateId, dueDate, startDate, latitude, and longitude. Nullable fields can be sent as null to clear them. Unknown fields are ignored by the current handler.

The result includes taskId. Status changes and field updates still pass normal workflow, team, approval-lock, and field-permission checks.

DELETE /tasks

Soft-deletes a task. Send both identifiers as query parameters:

DELETE /tasks?tenantId=hotel-1&taskId=j97...

The handler also accepts the identifiers in a JSON body for compatibility. A successful response is:

{
  "ok": true,
  "taskId": "j97..."
}

Task subresources

Every read below requires tenantId and taskId as query parameters. Every write requires them in the JSON body. The task must be visible to the key creator.

Comments and attachment notes

GET /task-comments returns task notes from oldest to newest.

POST /task-comments accepts:

The response contains the new note id and taskId.

Assignments

GET /task-assignments returns the task's assignment rows.

POST /task-assignments requires a non-empty userIds array. mode is set by default and can be add or remove. The response contains taskId, plus added and removed user-ID arrays.

Tags

GET /task-tags returns the task's tag-link rows.

POST /task-tags accepts tagIds and a mode of set (default), add, or remove. Unlike assignments, tagIds may be empty; mode: "set" with an empty array clears all tags. The response contains taskId, added, and removed tag-ID arrays.

Logs

GET /task-logs returns task log rows newest first. Logs reflect changes made in both Whagons and the External API.

Approval decisions

POST /task-approval requires decision: "approved" | "rejected" and accepts optional contextId, comment, and signatureStorageId.

{
  "tenantId": "hotel-1",
  "taskId": "j97...",
  "contextId": "workspace-context-id",
  "decision": "approved",
  "comment": "Reviewed and approved"
}

Approvals belong to a workspace context on the source task. They are not duplicated action tasks. Omit contextId only when the intended context is unambiguous.

Acknowledgments

POST /task-acknowledgment accepts optional contextId and comment:

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

OpenAPI

The versioned, machine-readable description is available at /openapi/whagons-v1.json. It can be imported into API clients, code generators, or testing tools.

The prose guide is the operational source for permission and workflow behavior; OpenAPI is the request-and-response contract. Changes to either are recorded in the API changelog.

Compatibility routes

The same handlers remain available at /api/ext/*. New clients should use /api/v1/*, and existing clients should follow the migration guide.