REST API

The REST base URL is https://api.boxpressd.com. Functional routes are versioned under /v1 and require x-boxpressd-key.

Method	Path	Purpose
`GET`	`/v1/cigars/search`	Search published cigars.
`GET`	`/v1/cigars/:id`	Get a published cigar by public ID.
`POST`	`/v1/cigars/resolve`	Resolve supplied text to ranked cigar candidates.
`GET`	`/v1/products/barcode/:barcode`	Look up published products and their cigar contents.
`GET`	`/v1/products/:id`	Get a published product by public ID.
`GET`	`/v1/me`	Get the connected user. Requires OAuth and `profile:read`.
`POST`	`/v1/matches`	Reserved for hosted cigar matching. Currently returns `501`.

Only GET /health and the interactive GET /docs route are anonymous.

Response conventions

Single-resource responses use a data object. Search responses include data and pagination. Public IDs are opaque and type-prefixed. REST search uses cursor pagination. Pass the returned endCursor as cursor on the next request. limit defaults to 20 and cannot exceed 100.

curl --get "https://api.boxpressd.com/v1/cigars/search" \
  --header "x-boxpressd-key: $BOXPRESSD_DEVELOPER_API_KEY" \
  --data-urlencode "q=maduro" \
  --data-urlencode "cursor=$NEXT_CURSOR"

The REST contract intentionally focuses on common search and lookup operations. Use GraphQL for brands, venues, events, relationships, and most connected-user collections.

Getting started

API guides

REST reference

Response conventions

​Response conventions

Response conventions