SqueakQL getting started

In the web app

Open a Project’s Work Items view and find Advanced Query · SqueakQL. Type an expression, choose Apply query, and the result stays in the URL so the view can be bookmarked. The simple filter controls remain available for everyday filtering. When Advanced Query is active, choose Use basic filters before changing those controls.

A small query

status = 'in_progress'

Values use single quotes. The status values in Hamstik are backlog, todo, in_progress, in_review, and done.

Add another condition

status = 'in_progress'
AND priority IN ('high', 'urgent')

Use your identity

assignee = CURRENT_USER
AND status <> 'done'

Add ordering

status <> 'done'
ORDER BY priority DESC, updated_at DESC

Hamstik adds deterministic Work Item key and id tiebreakers internally, so a page boundary does not randomly reorder equal values.

API request

{
  "query": "status <> 'done' AND assignee = CURRENT_USER ORDER BY updated_at DESC",
  "limit": 50,
  "cursor": null
}

The endpoint is read-only even though it uses POST. Use the cursor returned by a response for the next page; do not inspect or construct cursor contents.

Search requires a Bearer Personal Access Token with work_item:read, your Organization membership, and any required token resource grants. No Idempotency-Key is needed. limit defaults to 50 and accepts 1–200. Only query, limit, and cursor are accepted in the JSON body. Structured filters and URL query parameters are rejected; use the existing GET Work Items API for structured filters.

Validate a query with POST /api/v1/organizations/{organizationSlug}/squeakql/validate and a JSON body containing only query. A valid query returns:

{ "valid": true, "languageVersion": 1, "errors": [] }

Invalid language returns HTTP 200 with valid: false and diagnostics from validation, or HTTP 400 with a SqueakQL error from search. Validation checks the language, not whether referenced users, Projects, Sprints, or labels exist. Authentication, permissions, and malformed request bodies use normal API errors.

In the web app, basic filter values stay in the URL while paused. Applying an advanced query replaces their effect; Use basic filters restores them.