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, and transitions;
  • 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;
  • Sprint listing, creation, transition discovery, and transitions;
  • 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;
  • the authoritative OpenAPI 3.1.1 document at GET /api/v1/openapi.json.

The registry currently contains 51 method/path/operation-ID entries. The 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.

Webhook subscriptions remain a deferred follow-up pending a security and delivery RFC covering SSRF/DNS rebinding defense, secret rotation, outbox delivery, authorization, retries, and worker deployment.