> ## Documentation Index
> Fetch the complete documentation index at: https://docs.boxpressd.com/llms.txt
> Use this file to discover all available pages before exploring further.

# REST API

> Use the stable Boxpressd REST endpoints for catalog and connected-user requests.

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`.

```bash theme={null}
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"
```

<Note>
  The REST contract intentionally focuses on common search and lookup operations. Use [GraphQL](/developer-api/graphql) for brands, venues, events, relationships, and most connected-user collections.
</Note>