API quickstart

This guide uses the API key created in the Whagons Settings experience. You need a role with permission to manage integrations.

1. Create an API key

In Whagons:

1. Open Settings.
2. Choose Integrations.
3. Open the API Keys tab.
4. Choose Add API Key.
5. Enter a descriptive name such as Guest request sync — production.
6. Choose an expiration. The current options are one hour, one day, 7, 30, 90, or 180 days, one year, or no expiration.
7. Choose Create.
8. Copy the whg_live_… value immediately. Whagons will not show the full key again.

The Settings flow currently issues both ext:read and ext:tasks:write. Effective access is still limited by the creator's current user permissions, teams, workspaces, and task visibility.

2. Set local variables

export WHAGONS_API_BASE="https://cvx-share.whagons.com/api/v1"
export WHAGONS_API_KEY="whg_live_…"
export WHAGONS_TENANT_ID="<your-tenant-id>"

The key belongs to one tenant, and most endpoints require that tenant's ID explicitly.

3. Verify the key

List visible workspaces:

curl --fail-with-body \
  "$WHAGONS_API_BASE/workspaces?tenantId=$WHAGONS_TENANT_ID" \
  -H "X-API-Key: $WHAGONS_API_KEY"

You should receive a JSON array. Choose a workspace and keep its _id:

[
  {
    "_id": "<workspace-id>",
    "name": "Guest Requests"
  }
]

If the response is 401, verify the key, tenant ID, active state, expiration, and the creator's access.

4. Create a task

curl --fail-with-body -X POST "$WHAGONS_API_BASE/tasks" \
  -H "X-API-Key: $WHAGONS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "tenantId": "<your-tenant-id>",
    "workspaceId": "<workspace-id>",
    "name": "Deliver extra towels to room 304",
    "description": "Created by the guest request integration."
  }'

Successful creation returns the document ID and, when present, the numeric task ID:

{
  "id": "<task-id>",
  "pgId": 1234
}

Store id for future API operations.

5. Read the task

curl --fail-with-body \
  "$WHAGONS_API_BASE/tasks?tenantId=$WHAGONS_TENANT_ID&taskId=<task-id>" \
  -H "Authorization: Bearer $WHAGONS_API_KEY"

Both X-API-Key and bearer authentication work for whg_live_… keys. Pick one style and use it consistently.

6. Add real tenant data

Before sending richer task payloads, resolve current IDs:

• Spots, users, teams, statuses, priorities, templates, and tags
• Task fields, updates, assignments, comments, and approvals
• Complete endpoint reference

Production checklist

• Use a separate key for production and each non-production environment.
• Give the key creator only the teams and workspaces the integration needs.
• Choose a finite expiration where the external system supports rotation.
• Keep the tenant ID and all Whagons reference IDs configurable.
• Treat 401 as non-retryable until credentials or scopes change.
• Do not retry a write blindly after a timeout; first determine whether it succeeded.
• Monitor the key's Last Used value in Settings.
• Test rotation before the original key expires.

Next, read API concepts or jump to the examples.