Agent API access

An approved agent calls the same public task API used by Settings-issued API keys. The credential and lifecycle differ; endpoint request and response shapes do not.

Current production endpoints

export WHAGONS_API_BASE="https://cvx-share.whagons.com/api/v1"
export WHAGONS_AGENT_TOKEN="whg_agent_…"
export WHAGONS_TENANT_ID="<approved-tenant-id>"

The underlying cvx-share.whagons.com host is the production HTTP action gateway. Agent access is tenant-specific: the approved claim determines the tenant and user context, and API requests must carry that matching tenantId.

Authenticate

Agent tokens use bearer authentication:

Authorization: Bearer whg_agent_…

Unlike Settings-issued API keys, an agent token cannot be sent as X-API-Key.

Read visible workspaces

curl "$WHAGONS_API_BASE/workspaces?tenantId=$WHAGONS_TENANT_ID" \
  -H "Authorization: Bearer $WHAGONS_AGENT_TOKEN"

The API returns only workspaces visible to the user who approved the agent.

Create a task

curl -X POST "$WHAGONS_API_BASE/tasks" \
  -H "Authorization: Bearer $WHAGONS_AGENT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "tenantId": "<approved-tenant-id>",
    "workspaceId": "<visible-workspace-id>",
    "name": "Inspect room 304"
  }'

The token needs ext:tasks:write, and the approving user must be allowed to create that task in the selected workspace.

Token-aware client behavior

Discover token lifetime from authorization-server metadata and token responses.
Refresh or re-register before running a long multi-step workflow.
Treat 401 as a credential, expiry, scope, or tenant mismatch until proven otherwise.
Do not retry a write after an ambiguous network failure without an idempotency strategy in the agent's own workflow.
Never switch tenantId from the tenant approved in the claim.
Resolve current reference IDs before writing; names and IDs vary by tenant.
Keep an external correlation ID in the agent's own logs without recording raw credentials.

What agents can do through v1

With the right scope and user permissions, an agent can:

read workspaces, spots, users, task types, statuses, priorities, teams, templates, and tags;
list or fetch visible tasks;
create, update, or soft-delete tasks;
read and add comments;
read or change assignments and tags;
read task logs;
approve or reject visible approval contexts;
acknowledge visible acknowledgment contexts.

See the API reference for exact fields and the OpenAPI document for machine-readable schemas.