Search products

GET

/v1/products/search

const url = 'https://api.listrar.com/v1/products/search?trust_level_min=L0&sort=relevance';
const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request GET \
  --url 'https://api.listrar.com/v1/products/search?trust_level_min=L0&sort=relevance' \
  --header 'Authorization: Bearer <token>'

Only manufacturer is backed by real data at this revision; brand, category and market are refused with UNSUPPORTED_FILTER rather than silently ignored, so an empty result never means “we ignored your filter”. Cursor pagination only — pass back meta.next_cursor, never an offset.

Authorizations

ApiKey

Parameters

Query Parameters

manufacturer

string

Fuzzy, trigram-ranked manufacturer name.

trust_level_min

Allowed values: L0 L1 L2 L3 L4 L5

Lowest acceptable trust level.

has_dpp

boolean

Restrict to products with, or without, a persisted passport.

updated_since

string format: date-time

RFC 3339 timestamp.

sort

Allowed values: relevance updated_at

relevance (default with manufacturer) or updated_at.

cursor

string

An opaque cursor from a previous meta.next_cursor.

limit

integer

>= 1 <= 200

Page size.

Responses

200

Matching products, with meta.next_cursor when more remain.

application/json

Response envelope

object

request_id

required

string

/^req_[0-9A-HJKMNP-TV-Z]{26}$/

status

required

Typed result status. Absence (‘not_found’, ‘unknown’) is an answer carried at HTTP 200, never a 404 — see ERROR_MODEL.md design rule 1. ‘not_found’ MUST NOT be softened (06 §9).

Allowed values: found not_found unknown ambiguous partial

reason

REQUIRED when status = ‘unknown’.

Allowed values: NO_SOURCE SOURCE_UNAVAILABLE OUT_OF_SCOPE LICENCE_RESTRICTED TIMEOUT AMBIGUOUS_INPUT

data

object | null

claims

Array<object>

Claim

object

required

string

subject

required

string

predicate

required

string

object

required

object

value

required

unit

string | null

language

string | null

claim_type

required

INFERENCE and ESTIMATION can never be promoted to FACT. See 10 §3.

Allowed values: FACT SOURCE ASSERTION VALIDATION INFERENCE ESTIMATION UNKNOWN

method

REQUIRED for INFERENCE and ESTIMATION

string | null

method_version

string | null

source_ref

string | null

publisher_ref

string | null

evidence_refs

Array<string>

verification_status

Allowed values: unverified domain_verified registry_verified contract_verified disputed

verification_method

string | null

trust_level

required

Allowed values: L0 L1 L2 L3 L4 L5

confidence

number

<= 1

published_at

string | null format: date-time

retrieved_at

required

string format: date-time

superseded_by

string | null

sources

Array<object>

object

required

string format: uuid

kind

required

Allowed values: registry gs1_resolver publisher_endpoint partner_feed tenant_upload web

origin

required

string

operator_party_id

string | null format: uuid

trust_tier

required

integer

<= 4

robots_policy

string | null

enabled

boolean

licence_name

required

string

may_store_raw

boolean

may_redistribute_verbatim

boolean

may_redistribute_derived

boolean

attribution_required

string | null

licence_determined_by

string

licence_determined_at

string format: date-time

licence_review_due_at

string format: date-time

meta

required

object

duration_ms

required

integer

coverage

What was actually consulted, so a caller can distinguish ‘does not exist’ from ‘not covered’. Present on absence and on batch responses.

object

sources_consulted

required

Array<string>

sources_skipped

Array<object>

object

required

string

reason

required

Allowed values: LICENCE_RESTRICTED CIRCUIT_OPEN OUT_OF_SCOPE TIMEOUT DISABLED

next_cursor

Opaque cursor for the next page; absent means end of results. Cursor pagination only, never offset.

string

validation

Up to four independent axes, never collapsed into one verdict (12 §5). A class is absent when no rule of that class has been evaluated for this subject — which is not the same as ‘not_assessed’, a recorded verdict.

object

technical

Allowed values: pass fail warn not_assessed

business

Allowed values: pass fail warn not_assessed

regulatory

Allowed values: pass fail warn not_assessed

authority

Allowed values: none attested

warnings

Array<object>

object

code

required

string

severity

required

Allowed values: info warn error

detail

string

errors

Array<object>

Problem (RFC 9457 + extensions)

object

type

required

string format: uri

title

required

string

status

required

integer

>= 100 <= 599

code

required

string

/^[A-Z][A-Z0-9_]+$/

detail

string

<= 512 characters

request_id

string

retryable

required

boolean

docs_url

string format: uri

Example

{
  "status": "found",
  "reason": "NO_SOURCE",
  "claims": [
    {
      "subject": "gtin14:04012345678901",
      "predicate": "dpp:carbonFootprintKgCO2e",
      "claim_type": "FACT",
      "verification_status": "unverified",
      "trust_level": "L0"
    }
  ],
  "sources": [
    {
      "kind": "registry"
    }
  ],
  "meta": {
    "coverage": {
      "sources_skipped": [
        {
          "reason": "LICENCE_RESTRICTED"
        }
      ]
    }
  },
  "validation": {
    "technical": "pass",
    "business": "pass",
    "regulatory": "pass",
    "authority": "none"
  },
  "warnings": [
    {
      "severity": "info"
    }
  ]
}

Headers

x-request-id

string

Echoes the envelope’s request_id.

400

INVALID_FILTER, UNSUPPORTED_FILTER, INVALID_SORT, INVALID_CURSOR

application/problem+json

Problem (RFC 9457 + extensions)

object

type

required

string format: uri

title

required

string

status

required

integer

>= 100 <= 599

code

required

string

/^[A-Z][A-Z0-9_]+$/

detail

string

<= 512 characters

request_id

string

retryable

required

boolean

docs_url

string format: uri

Example^generated

{
  "type": "https://example.com",
  "title": "example",
  "status": 1,
  "code": "example",
  "detail": "example",
  "request_id": "example",
  "retryable": true,
  "docs_url": "https://example.com"
}

401

UNAUTHENTICATED

application/problem+json

Problem (RFC 9457 + extensions)

object

type

required

string format: uri

title

required

string

status

required

integer

>= 100 <= 599

code

required

string

/^[A-Z][A-Z0-9_]+$/

detail

string

<= 512 characters

request_id

string

retryable

required

boolean

docs_url

string format: uri

Example^generated

{
  "type": "https://example.com",
  "title": "example",
  "status": 1,
  "code": "example",
  "detail": "example",
  "request_id": "example",
  "retryable": true,
  "docs_url": "https://example.com"
}

402

TENANT_QUOTA_EXCEEDED

application/problem+json

Problem (RFC 9457 + extensions)

object

type

required

string format: uri

title

required

string

status

required

integer

>= 100 <= 599

code

required

string

/^[A-Z][A-Z0-9_]+$/

detail

string

<= 512 characters

request_id

string

retryable

required

boolean

docs_url

string format: uri

Example^generated

{
  "type": "https://example.com",
  "title": "example",
  "status": 1,
  "code": "example",
  "detail": "example",
  "request_id": "example",
  "retryable": true,
  "docs_url": "https://example.com"
}

429

RATE_LIMITED

application/problem+json

Problem (RFC 9457 + extensions)

object

type

required

string format: uri

title

required

string

status

required

integer

>= 100 <= 599

code

required

string

/^[A-Z][A-Z0-9_]+$/

detail

string

<= 512 characters

request_id

string

retryable

required

boolean

docs_url

string format: uri

Example^generated

{
  "type": "https://example.com",
  "title": "example",
  "status": 1,
  "code": "example",
  "detail": "example",
  "request_id": "example",
  "retryable": true,
  "docs_url": "https://example.com"
}

500

INTERNAL_ERROR

application/problem+json

Problem (RFC 9457 + extensions)

object

type

required

string format: uri

title

required

string

status

required

integer

>= 100 <= 599

code

required

string

/^[A-Z][A-Z0-9_]+$/

detail

string

<= 512 characters

request_id

string

retryable

required

boolean

docs_url

string format: uri

Example^generated

{
  "type": "https://example.com",
  "title": "example",
  "status": 1,
  "code": "example",
  "detail": "example",
  "request_id": "example",
  "retryable": true,
  "docs_url": "https://example.com"
}

Search products

Authorizations

Parameters

Query Parameters

Responses

200

Example

Headers

400

Examplegenerated

401

Examplegenerated

402

Examplegenerated

429

Examplegenerated

500

Examplegenerated

Example^generated

Example^generated

Example^generated

Example^generated

Example^generated