Projects

Projects, tasks and support

Cloud project routes are scoped under /v1/workspaces/{workspace_id}. Use a credential with the appropriate project read/write permissions. Requests run with current workspace access, not an unrestricted service identity.

Read a workspace

curl --fail-with-body -H "Authorization: Bearer $ALSHIVAL_TOKEN" \
  "$ALSHIVAL_BASE_URL/v1/workspaces/$ALSHIVAL_WORKSPACE_ID/tasks"

Discover boards, taxonomy, statuses, and assignees before constructing mutations. Use /project, /project/timeline, and /project/activity for workspace views. Task numbers are display identifiers; routes use object UUIDs.

Create and change work

The API exposes tasks, deliverables, notes, and tickets. Task comments, note replies, and ticket messages have separate routes. Use the endpoint-specific body in the cloud reference, including its revision and idempotency fields where required. Do not assume every write uses the same shape.

Read the latest object before editing. On a revision conflict, fetch current state and reconcile the intended change rather than blindly overwriting it. Reuse an idempotency key only for the same logical request where supported.

Task movement uses the dedicated /tasks/{item_id}/move route. Archive, restore, approvals, and other lifecycle operations use the documented actions or restore route; deleting and archiving are not interchangeable.

Create a task

Generate one UUID for the logical create request and reuse it only when retrying that same body:

export ALSHIVAL_IDEMPOTENCY_KEY="$(python3 -c 'import uuid; print(uuid.uuid4())')"
curl --fail-with-body -X POST \
  "$ALSHIVAL_BASE_URL/v1/workspaces/$ALSHIVAL_WORKSPACE_ID/tasks" \
  -H "Authorization: Bearer $ALSHIVAL_TOKEN" \
  -H 'Content-Type: application/json' \
  --data "{\"idempotency_key\":\"$ALSHIVAL_IDEMPOTENCY_KEY\",\"title\":\"Review worker logs\",\"priority\":\"normal\"}"

Creation returns HTTP 201; an idempotent replay can return 200. Save the returned object ID and revision. Optional fields include board, type, labels, assignee, reviewer, and dates; obtain their values from the corresponding workspace catalogs.

Desktop differences

Desktop work uses /v1/projects/items and related catalogs, not the cloud task routes. Local item mutations require idempotency_key; edits/actions also require the observed revision. See Desktop API.

---

Published from the versioned Alshival documentation source. Edit the source rather than this generated page.