Skip to main content
The Boxpressd API gives your application access to an approved, stable view of Boxpressd data. Use REST for cigar search, record lookup, text resolution, barcode lookup, and AI-assisted cigar recognition. Use GraphQL when you need related catalog data or OAuth-scoped data for a connected Boxpressd user. Every functional API request requires a developer application key in the x-boxpressd-key header. User-specific requests also require an OAuth access token.

Get started

Create an application and make your first request.

Authentication

Understand developer keys and user access tokens.

JavaScript client

Use the typed API client from ESM or CommonJS applications.

REST API

Review stable versioned endpoints and response conventions.

GraphQL

Query curated catalog and connected-user data.

AI and cigar matching

Detect, analyze, and identify cigars from band images.

Credits and billing

Check usage, balances, plans, and AI credit availability.

​
Public contract

Public IDs are opaque, type-prefixed values such as cigar_k9P4m. The same ID identifies a resource in REST and GraphQL. Do not decode IDs or depend on their internal representation. The API is deny-by-default. Database fields do not become public automatically. The initial GraphQL release is read-only and has no mutation root. AI routes require the api.ai entitlement. Paid AI routes also require available AI credits and an idempotency key.
Write operations for connected users are coming soon. Cigar matching and billing operations are available through the documented REST routes.