Attributes API

Attributes API

Public API v1 addresses definitions and options by their stable machine keys. An editable display name or option label is descriptive only; it is never the identity used by an integration. The generated OpenAPI document is authoritative for exact responses, bounds, and errors.

Authorization and PAT scopes

Organization discovery uses organization:read. Project-specific discovery uses project:read and is limited to that authorized Project. Definition and option administration uses the standalone attribute:write scope and also requires the caller’s current Organization Owner or Administrator role. attribute:write implies no read, Project, Work Item, or other write scope. Adding this scope does not change any existing token; create a replacement token with the explicit scope when administration is needed.

Project enablement uses the explicit attribute:write scope, a grant for the target Project, and Project-management authorization. attribute:write does not grant Organization or other Project access; resource grants still bound each request. Existing project:write tokens do not receive this scope. Work Item assignment uses the existing work_item:write scope. Resource grants, current membership, role, account state, Organization suspension, and Project scope are checked on each operation. A Project-restricted token cannot use Organization administration and its Project catalog does not disclose other Projects’ enablement or usage.

Catalog and administration

GET  /api/v1/organizations/{organizationSlug}/attributes
GET  /api/v1/organizations/{organizationSlug}/attributes/{attributeKey}
POST /api/v1/organizations/{organizationSlug}/attributes
PATCH /api/v1/organizations/{organizationSlug}/attributes/{attributeKey}
POST /api/v1/organizations/{organizationSlug}/attributes/{attributeKey}/transitions
POST /api/v1/organizations/{organizationSlug}/attributes/{attributeKey}/options
PATCH /api/v1/organizations/{organizationSlug}/attributes/{attributeKey}/options/{optionKey}
POST /api/v1/organizations/{organizationSlug}/attributes/{attributeKey}/options/reorder
POST /api/v1/organizations/{organizationSlug}/attributes/{attributeKey}/options/{optionKey}/retire

The catalog lists supported types and fixed product limits. Add ?includeRetired=true to include retired definitions. Options are returned in their configured order with active/retired state. Mutations require an exact Attribute If-Match ETag and Idempotency-Key; stale revisions return 412 REVISION_CONFLICT. Option keys and definition keys cannot be renamed or reused. A definition’s type is fixed when it is created.

Create an Attribute:

curl -X POST \
  -H "Authorization: Bearer $HAMSTIK_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: attribute-customer-01" \
  -d '{"key":"customer","name":"Customer","type":"single_select"}' \
  "https://hamstik.com/api/v1/organizations/$ORG_SLUG/attributes"

Add an option using its stable key and an administrator-controlled label:

{"key":"acme","label":"ACME"}

The definition response’s ETag is required for option changes and lifecycle transitions. Reordering submits the complete option-key list, including retired options.

Project enablement

GET  /api/v1/organizations/{organizationSlug}/projects/{projectKey}/attributes
POST /api/v1/organizations/{organizationSlug}/projects/{projectKey}/attributes/{attributeKey}/enablement

The Project catalog returns active definitions and active options available for assignment, plus enablement for that one Project. Each available definition includes its exact etag so a Project-restricted administrator can submit the current If-Match value when managing only an Attribute already visible to that Project. The enablement response does not expose other Projects. To enable a definition, send {"enabled":true} with the current definition ETag and an idempotency key; send false to opt out. Opt-out retains already assigned Work Item values.

Work Item assignments

Full Work Item and search projections include attributes. List and context projections include them when the attributes field is requested or when the complete summary fields are returned. This includes My Work and user Work Item lists, within the caller’s authorized Organizations and Projects. Each value includes its stable key, definition identity and lifecycle, whether the Project is enabled, and ordered option keys/labels/states. An unset definition has no value entry. Boolean false appears as booleanValue: false; it is not omitted.

Create or update request bodies may include a sparse attributes array:

{
  "attributes": [
    {"key":"customer","optionKeys":["acme"]},
    {"key":"regulated","booleanValue":false}
  ]
}

Omit attributes or an individual definition to preserve its existing value. To clear one value, send { "key": "customer", "clear": true }. A single-select takes one optionKeys entry; a multi-select takes up to ten unique entries; a boolean takes booleanValue: true or false. Unknown, foreign, wrong-type, inactive, or non-enabled references fail without being coerced. Single and bulk Work Item operations use the same validation and assignment service. Include an Idempotency-Key on single Work Item updates that include attributes, as well as on Work Item creates and bulk mutations. Status changes remain separate transition operations.

Errors and compatibility

Inaccessible Organizations, Projects, definitions, and options are concealed with the normal Public API not-found behavior. Other common failures are VALIDATION_ERROR, FORBIDDEN, CONFLICT, and REVISION_CONFLICT, using the standard request ID and error envelope. Every mutation rechecks current grants and authorization in its transaction.

Existing clients that omit attributes keep their current assignments during Work Item updates. Apps can read the same documented projection under their normal API grants; the API does not let Apps register definitions, add types, or attach workflow behavior to Attributes. The installed Hamstik CLI v0.2.0 does not yet expose Attribute-specific named commands or assignment flags; see CLI compatibility.

The current CLI’s documented api request bridge can call these Public API routes without bypassing scopes or resource grants. It supports JSON-valued --field arguments for request bodies. For example, create an assignment using the documented API contract:

hamstik --json --no-input api request \
  "/api/v1/organizations/<ORG>/projects/<PROJECT>/work-items" \
  --method POST --field "title=Classify request" \
  --field 'attributes=[{"key":"verified","booleanValue":false}]' \
  --idempotency-key create-classified-request

Use the same bridge with the Organization or Project Attribute catalog routes, the Work Item detail route to read assignments, and the SqueakQL search route to query them. The bridge does not yet provide named Attribute commands, projection flags, or Attribute-specific single/bulk command schemas.