Skip to content
HamstikHamstik Docs

Work Item templates API

Work Item templates API

Public API v1 exposes the same Project Work Item templates that administrators maintain in Project settings → Templates. The generated OpenAPI document is authoritative for exact request fields, bounds, ETags, and error responses.

Authorization and PAT scopes

  • Listing and reading templates uses project:read and is limited to the authorized Project.
  • Creating, editing, archiving, restoring, and setting the default template uses project:write plus current Project-management authorization.
  • Creating a Work Item from a template uses the existing work_item:write scope; the selected template must belong to the same authorized Project.

Resource grants, current membership, role, account state, Organization suspension, and Project scope are checked on every operation. A template id from another Project or Organization resolves to 404 and leaks nothing.

Routes

GET    /api/v1/organizations/{organizationSlug}/projects/{projectKey}/work-item-templates
POST   /api/v1/organizations/{organizationSlug}/projects/{projectKey}/work-item-templates
GET    /api/v1/organizations/{organizationSlug}/projects/{projectKey}/work-item-templates/{templateId}
PATCH  /api/v1/organizations/{organizationSlug}/projects/{projectKey}/work-item-templates/{templateId}
DELETE /api/v1/organizations/{organizationSlug}/projects/{projectKey}/work-item-templates/{templateId}
POST   /api/v1/organizations/{organizationSlug}/projects/{projectKey}/work-item-templates/{templateId}

GET on the collection returns { "items": [...] } and accepts includeArchived=true for Project managers. Other readers receive active templates only; direct reads of archived templates return 404 for them. Archived templates remain auditable evidence and cannot be applied.

Create a template

{
  "type": "bug",
  "name": "Bug reproduction",
  "description": "Steps, environment, and expected result",
  "isDefault": true,
  "defaults": {
    "title": "Bug: ",
    "priority": "high",
    "assigneeId": "11111111-1111-4111-8111-111111111111",
    "labelIds": ["22222222-2222-4222-8222-222222222222"],
    "attributes": [{ "key": "verified", "booleanValue": false }]
  }
}

Sending isDefault: true replaces the Project/type’s previous active default. A template may prefill only title, description, priority, assignee, existing Project labels, and valid Project-enabled Organization Attribute values; any other key is rejected with VALIDATION_ERROR. Reference identities are stored as-is and validated again when a Work Item is created.

Edit, archive, restore, and defaults

PATCH requires the exact current template ETag in If-Match and a positive expectedRevision in the body. A stale revision fails with 412.

DELETE archives a template and requires the exact ETag. Archiving clears the default atomically.

POST performs a discrete lifecycle action:

{ "action": "set_default", "expectedRevision": 3 }
{ "action": "clear_default", "expectedRevision": 3 }
{ "action": "restore", "expectedRevision": 3 }

set_default, restore, and clear_default require a positive expectedRevision to reject stale selections. The action endpoint does not require If-Match. Concurrent set_default calls resolve to exactly one active default per Project/type.

Create a Work Item from a template

POST /api/v1/organizations/{organizationSlug}/projects/{projectKey}/work-items accepts an optional templateId:

  • a string selects that template;
  • null explicitly opts out of any default template;
  • omitted applies the configured default template for the resolved type.

Explicit request values win over the template. A selected template completely replaces the default’s contribution. Use the ordinary Idempotency-Key header: a retry of the same logical creation produces one Work Item, even if the template is subsequently edited or archived. Omitted values and explicit clears are distinct request intent; keep the same request body when retrying.

Send templateRevision with an explicit templateId to require the version shown in your preview. A changed version fails with 412 before creation. description: "", assigneeId: null, labelIds: [], and attributes: [] explicitly clear those template contributions. A title may be omitted when the selected or configured default template supplies it.

Bulk Work Item creation accepts the same template selection and overrides for each operation.

Terminal window
curl -X POST \
  -H "Authorization: Bearer $HAMSTIK_TOKEN" \
  -H "Idempotency-Key: create-bug-2026-01-01" \
  -H "Content-Type: application/json" \
  "https://hamstik.com/api/v1/organizations/acme/projects/OPS/work-items" \
  -d '{
    "templateId": "33333333-3333-4333-8333-333333333333",
    "title": "Login fails on mobile",
    "priority": "urgent"
  }'

Creation validates the template’s defaults against current Work Item type, Project, Attribute, and assignee rules. An invalid stale default produces an actionable field error and no Work Item. The source template id and revision are recorded in the Work Item’s creation audit metadata, not as a live dependency, so later template edits never change the item.

Errors

Templates use the standard Public API error envelope. Relevant codes include VALIDATION_ERROR, FORBIDDEN, NOT_FOUND, CONFLICT (duplicate name or default), REVISION_CONFLICT/412 (stale edit), and PRECONDITION_REQUIRED (If-Match missing).

CLI

The verified CLI release does not provide named template commands. Use the documented Public API bridge; see CLI commands and output for hamstik api request examples.