Skip to content
HamstikHamstik Docs

Public API v1

Hamstik Public API v1

Hamstik Public API v1 is the stable HTTP surface for the Hamstik CLI, scripts, agents, and server automation. It lives under /api/v1, uses Organization terminology, and returns explicit resource projections rather than database rows.

The complete dogfooding slice supports:

  • identity: GET /api/v1/me;
  • authenticated public identity and Organization-scoped usernames;
  • Organization and Project discovery;
  • Project creation for Organization administrators;
  • filtered, cursor-paginated Work Item lists and complete Work Item reads;
  • Work Item creation, updates, transition discovery, transitions, and watcher controls;
  • flat, threaded Work Item comment lists, comment creation, and author-only comment deletion;
  • Work Item attachment listing, downloads, uploads, and creator/Organization-admin deletion;
  • Project label listing/creation and Work Item label assignment;
  • Organization Attribute discovery/administration, Project enablement, and Work Item assignment;
  • Sprint listing, creation, transition discovery, and transitions;
  • Project Release Version listing, creation, metadata updates, and lifecycle transitions;
  • Quality test plans, suites, cases, runs, immutable result evidence with machine publishing, verification signoffs, defect links, and opt-in release quality gates;
  • Organization automation rules with bounded triggers, preview, enable/disable, and an explainable execution log;
  • Work Item to Release Version membership reads and idempotent assignment changes;
  • Organization-wide and My Work collections with stable keyset cursors;
  • Work Item links, archival/deletion, activity feeds, and bulk mutations;
  • authenticated profile summaries, profile Work/activity, avatars, and member directories;
  • Project lifecycle controls and comment editing;
  • Sprint delivery reports with commitment, scope changes, carryover, burndown, and status distribution;
  • Advanced report definitions, personal mutations, report/dashboard execution, and exact selections;
  • the authoritative OpenAPI 3.1.1 document at GET /api/v1/openapi.json.

The method/path/operation-ID registry and the OpenAPI builders in src/lib/api/openapi.ts are one contract: clients should use the OpenAPI response rather than treating this overview as a generated SDK.

Start with authentication, then read:

The API does not use browser-session cookies. Authenticate with a Personal Access Token in an Authorization: Bearer ... header. Browser account pages remain the place to create, list, and revoke tokens. The OpenAPI document is the machine-readable source of truth for the public contract and the source for any future client generator. Hamstik does not currently ship an official generated client.

Every response is Cache-Control: no-store and carries X-Request-Id. Public JSON collections use {items, page} with opaque cursors. New mutations use the documented idempotency and ETag rules; the original 20 v1 operations keep their existing header requirements for compatibility.

Public user identity is distinct from Organization membership identity. New user references use an immutable usr_ public ID; the legacy internal UUID is retained only where an existing v1 contract requires it. A nullable username is unique only within one Organization and is never a global handle. Email is private and appears in v1 only in the authenticated caller’s /me response.

Outgoing Webhooks are administered through the webhook:read and webhook:write scopes; see Webhooks for the delivery contract, signing scheme, and retry policy.