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`	Identify a cigar with the complete band-matching workflow.
`POST`	`/v1/ai/cigars/*`	Run individual cigar image analysis stages.
`GET`	`/v1/billing/status`	Get current usage and the AI credit balance.
`GET`	`/v1/billing/usage`	Get normalized usage for the current period.
`GET`	`/v1/billing/plans`	List active developer plans.
`GET`	`/v1/billing/credit-packs`	List AI credit offers for developer applications.

Only GET /health and the interactive GET /docs route are anonymous. See AI and cigar matching for every image endpoint and Credits and billing for the credit lifecycle.

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. Paid AI requests require an Idempotency-Key header in addition to the developer key. See AI and cigar matching for retry behavior. Published cigar objects use the normalized cigar composition contract. origin remains a canonical country string. wrapper, binder, and filler are arrays of tobacco components, including when they are empty.

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