TracePass
Get started
Passports

List passports

Paginated list of passports the workspace owns. Filter by `productId`, `status`, or a free-text search across GTIN and serial number. Counts against the daily passport-read budget (`maxV1PassportsPerDay`); the response items use the same shape as the single-read endpoint but trimmed to the listing fields.

GET/api/v1/passports
Download OpenAPI 3.1
GET/api/v1/passports

List passports

Paginated list of passports the workspace owns. Filter by `productId`, `status`, or a free-text search across GTIN and serial number. Counts against the daily passport-read budget (`maxV1PassportsPerDay`); the response items use the same shape as the single-read endpoint but trimmed to the listing fields.

Query parameters

  • page

    number (default 1)

    1-based page number.

  • limit

    number (1-100, default 20)

    Items per page.

  • productId

    ObjectId

    Filter by product.

  • status

    enum

    `draft`, `in_review`, `approved`, `published`, `suspended`, `expired`, `archived`.

  • search

    string

    Free-text across GTIN + serial.

Headers

  • Authorizationrequired

    string

    `Bearer <token>` — either a `tp_` API key (Developer → API Keys; simplest, for server-to-server) or an OAuth 2.0 access token (Developer → OAuth Apps; for user-authorized apps, scoped + revocable). The Authentication page has the full OAuth flow and scope list.

    e.g. Bearer tp_REDACTED_xxxxxxxxxxxx

Request

curl -sS \
  "https://app.tracepass.eu/api/v1/passports?status=published&limit=50" \
  -H "Authorization: Bearer tp_REDACTED_xxxxxxxxxxxx"

Response

{
  "items": [
    {
      "_id": "6650b2c3d4e5f6a7b8c9d0e1",
      "productId": "6650a1b2c3d4e5f6a7b8c9d0",
      "gs1": {
        "gtin": "04012345000016",
        "serialNumber": "BP-48V-100-000001",
        "digitalLinkUri": "https://id.tracepass.eu/p/01/04012345000016/21/BP-48V-100-000001"
      },
      "status": "published",
      "completionPercentage": 87,
      "publishedAt": "2026-04-11T10:00:00.000Z"
    }
  ],
  "total": 1,
  "page": 1,
  "limit": 50,
  "totalPages": 1
}

Related endpoints