List and search cards

GET

/cards

Filterable by external_ref, holder_email, program_id and status. Cursor-paginated. status is the DERIVED status, in precedence order archived > disabled > expired > locked/invited > active, so every card appears under exactly one of them and a card that is both disabled and past its expiry reads as disabled. An unrecognised status is a 400, not an empty page. holder_email is NOT an identity: one address can hold several cards of the same shop, so it answers with a page — join on external_ref. Requires an UNRESTRICTED key: a key limited to specific locations is refused with 403 location_scope_unsupported, and shop-wide data is never silently served to it instead. A card is not attributed to a location anywhere in TesserApp — it belongs to a program, and programs belong to the whole shop — so there is no correct subset of cards to serve such a key.

Authorizations

ApiKeyBearer

A shop-scoped API key created in the dashboard and shown exactly once. An MCP tmk_ key presented here returns a 401 that names the mistake.

Type

HTTP (bearer)

Parameters

Query Parameters

limit

Page size. Clamped to the maximum (100 by default, PUBLIC_API_MAX_PAGE_SIZE) rather than rejected.

Type

integer

Minimum

1

cursor

Opaque cursor from a previous response's next_cursor. Absent next_cursor (null) means the end.

Type

string

external_ref

Type

string

holder_email

Type

string

Format

"email"

program_id

Type

string

status

Type

string

Valid values

"active""disabled""locked""invited""archived""expired"

Responses

List and search cards

Content-Type

application/json

{

  

"data": [

  

  

{

  

  

  

"id": "cin_docsfixture0001",

  

  

  

"program_id": "prg_docsfixture0001",

  

  

  

"program_name": "Coffee Card",

  

  

  

"program_type": "standard",

  

  

  

"external_ref": "EMP-00417",

  

  

  

"holder_name": "Ada Lovelace",

  

  

  

"holder_email": "ada@docsfixture.invalid",

  

  

  

"status": "active",

  

  

  

"stamps_count": 4,

  

  

  

"current_value": 4,

  

  

  

"expires_at": "2026-10-04T10:15:00.000Z",

  

  

  

"installed_at": "2026-09-04T10:15:00.000Z",

  

  

  

"created_at": "2026-08-05T10:15:00.000Z"

  

  

}

  

],

  

"next_cursor": "eyJjIjoiMjAyNi0wOC0wNVQxMDoxNTowMC4wMDBaIiwiaSI6ImNpbl9kb2NzZml4dHVyZTAwMDEifQ",

  

"limit": 25

}

GET

/cards

Samples

Powered by VitePress OpenAPI