TracePass
Manage products, EU Digital Product Passports, operator parties, and GS1 EPCIS supply-chain events.
Should I use this
Quality & Safety
Findings (3)
- HIGHTool poisoning patterns detected
- MEDIUMTool description contains URL to non-standard domainin tracepass_passports
- MEDIUMTool description contains URL to non-standard domainin tracepass_passport_parties
Based on automated analysis of tool definitions and protocol compliance.
Context Cost
This is the approximate number of tokens consumed each time the server's tools are loaded into a model's context. Higher counts reduce the attention available for other tasks.
Install
One-Click Install
Add this to your `claude_desktop_config.json` file:
{
"mcpServers": {
"tracepass": {
"command": "npx",
"args": [
"tracepass-mcp-server"
]
}
}
}Runnable packages
1.24.0stdioRemote endpoints
https://ai.tracepass.eu/mcpstreamable-httpWhat it can do
Tool inventory
Tools (7)
🔴tracepass_products(action, args)
Manage the TracePass product catalogue. A product is the catalogue layer — one product can have many passports (one per serialised unit). Products are not billable on their own. Actions (pass via `action`, with `args`): - list — args: { page?, limit? (≤100), category?, status?, search? }. Read-only. - get — args: { id }. Read-only. - create — args: { name, model, category, description? }. `category` is one of: battery, textile, electronics, construction, steel, detergents, paints-coatings, packaging, furniture, tyres, jewelry, toys, fmcg. - update — args: { id, name?, model?, description? }; pass at least one field to change. - create_batch — args: { products: [ { name, model, category, description? }, … ] }, up to 100. Partial-success: the response carries a per-item status, so some items can be created while others error. The whole batch consumes N writes upfront; if that would exceed the daily cap NOTHING is created (429). - archive — args: { id }. Soft-archive a product. Blocked with 409 while any non-archived passport still references it — archive those passports first. This is reversible and is NOT deletion.
Input Schema
{
"type": "object",
"properties": {
"action": {
"type": "string",
"enum": [
"list",
"get",
"create",
"create_batch",
"update",
"archive"
],
"description": "Which product operation to run: list | get | create | create_batch | update | archive."
},
"args": {
"description": "Arguments for the chosen action; required fields depend on `action` (see each action above).",
"type": "object",
"properties": {
"id": {
"description": "Product id. Required for get and update.",
"type": "string"
},
"name": {
"description": "Product name. Required for create; optional on update.",
"type": "string"
},
"model": {
"description": "Manufacturer model / SKU. Required for create; optional on update.",
"type": "string"
},
"category": {
"description": "DPP category for create: battery | textile | electronics | construction | steel | detergents | paints-coatings | packaging | furniture | tyres | jewelry | toys | fmcg.",
"type": "string"
},
"description": {
"description": "Free-text product description (create/update).",
"type": "string"
},
"page": {
"description": "Page number for list (1-based).",
"type": "number"
},
"limit": {
"description": "Page size for list, max 100.",
"type": "number"
},
"status": {
"description": "Filter list by product status.",
"type": "string"
},
"search": {
"description": "Filter list by a search term.",
"type": "string"
},
"products": {
"description": "Products to create for create_batch: [{ name, model, category, description? }], max 100.",
"type": "array",
"items": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {}
}
}
}
}
},
"required": [
"action"
],
"$schema": "http://json-schema.org/draft-07/schema#"
}Output Schema
{
"type": "object",
"properties": {
"id": {
"description": "The resource's TracePass id, when the response is a single entity.",
"type": "string"
},
"items": {
"description": "The page of results, when the action is a list.",
"type": "array",
"items": {}
},
"total": {
"description": "Total matching records across all pages (list actions).",
"type": "number"
},
"page": {
"description": "Current page number (list actions).",
"type": "number"
},
"limit": {
"description": "Page size (list actions).",
"type": "number"
},
"totalPages": {
"description": "Total number of pages (list actions).",
"type": "number"
},
"result": {
"description": "Wraps a non-object response body (e.g. a QR code string)."
},
"error": {
"description": "Machine-readable error code, when the API rejected the request.",
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"message": {
"description": "Human-readable error or status detail, when present.",
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
}
},
"$schema": "http://json-schema.org/draft-07/schema#",
"additionalProperties": false
}🔴tracepass_passports(action, args)
Manage Digital Product Passports — create, read, and run lifecycle actions. IMPORTANT: `create` makes a DRAFT passport. A draft takes no plan DPP slot and is never billed; the slot, and any per-DPP overage past the plan cap, is taken when the passport is published, which happens in the TracePass dashboard, not through this tool. Each create counts against the daily write budget. `archive` is IRREVERSIBLE (the public QR permanently 404s); prefer `suspend` when a change might be undone. IDENTIFIER SCHEMES (EN 18219): passports are identified by one of five schemes. Battery passports (Battery Regulation Art. 77(3)) accept ONLY gs1 and iso15459. • gs1 — { scheme:"gs1", gtin, serialNumber } — GS1 GTIN + serial; gtin is 8/12/13/14 digits, stored as GTIN-14. • iso15459 — { scheme:"iso15459", issuingAgencyCode, primaryId, serial? } — ISO/IEC 15459; the server derives raw (IAC + primaryId + serial). • iec61406 — { scheme:"iec61406", uri } — IEC 61406 Identification Link (https URI). Not valid for batteries. • did — { scheme:"did", did, method } — W3C DID Core. Not valid for batteries. • doi — { scheme:"doi", doi, granularity:"model"|"batch"|"item" } — ISO 26324 DOI, stored as bare 10.<registrant>/<suffix> (any https://doi.org/ or doi: prefix stripped on input; resolves as https://doi.org/<doi>); granularity REQUIRED per EN 18219 §5.6.2(b). Not valid for batteries. The legacy top-level gtin + serialNumber pair is still accepted as a deprecated alias for scheme:"gs1". Actions (pass via `action`, with `args`): - list — args: { page?, limit? (≤100), productId?, status?, search? }. status ∈ draft|in_review|approved|published|suspended|expired|archived. Read-only. - get — args: { id, format? (summary|full), lang? }. Read-only. Response includes `identifier`, `identifierKey`, and (for GS1 passports) `gs1`. - get_by_serial — args: { serial, format?, lang?, gtin? }. Read-only. Addresses the passport by your own serial. A serial is unique only WITHIN a GTIN — if the same serial exists under two GTINs in your account the call returns 409 ambiguous_serial; pass `gtin` (or use the by-id action) to resolve exactly. - compliance — args: { id }. Read-only. Returns a three-tier compliance verdict (compliant | compliant_with_warnings | incomplete) with regulation-cited findings — use to gap-check a passport against the rules for its category, fix the cited fields/parties, then re-check. Also returns byRegulation[]: the same findings grouped per regulation, worst first, so you can tell WHICH regime is failing instead of reading one `incomplete` as everything being wrong. A regulation absent from that array raised no finding — that is not the same as it having passed. - registry_readiness — args: { id }. Read-only. Returns { ready, findings[] } — whether the passport would pass the EU DPP Registry's FORMAL submission gate (mandatory fields present, correct formatting, a resolvable public link, item-level granularity via a serial number, and a well-formed commodity code where the category carries one). This is the registry's mechanical pre-submission check, NOT the substantive compliance verdict; a passport can be registry-ready yet not substantively compliant. Battery passports only. - create — args: { productId, identifier?, gtin?, serialNumber?, lineage? }. Creates a draft (not billed). Provide identifier (preferred) or legacy gtin + serialNumber. Battery passports accept only gs1 and iso15459 schemes — other schemes return 400. A duplicate identifier returns 409. lineage (battery only) — a repurposed, remanufactured or reused battery needs a NEW passport linked to the original(s) (Battery Regulation Art. 77(7)): { predecessors: [ { internalPassportId? | identifier?, trigger: preparation_for_reuse|preparation_for_repurposing|repurposing|remanufacturing } ] (≤10), noPredecessorReason? (only with an empty list, e.g. placed on the market before 18 Feb 2027) }. The server derives batteryStatus from the triggers and links your own predecessor passports back. Immutable after create. Rule violations return 422 with the rule code (duplicate_predecessor, predecessor_not_found, status_trigger_mismatch, …). - suspend — args: { id }. Reversible — public QR shows 'suspended'. - suspend_by_serial — args: { serial, gtin? }. Same as suspend, addressed by your serial. 409 ambiguous_serial if the serial isn't unique in your account — pass `gtin`. - archive — args: { id, reason? (recycled|never_placed|duplicate_or_error) }. IRREVERSIBLE and destructive — confirm with the user first. reason is REQUIRED for battery passports (400 reason_required / invalid_reason without a valid one): recycled, never_placed (never placed on the market or put into service), or duplicate_or_error (a duplicate or erroneous record); for other categories it is optional. A passport marked for deletion cannot be archived (409). - archive_by_serial — args: { serial, gtin?, reason? }. IRREVERSIBLE and destructive, addressed by your serial — confirm first. Same reason rule as archive. 409 ambiguous_serial if the serial isn't unique — pass `gtin`. - get_qr — args: { id, format? (svg|png), symbology? (qr|datamatrix) }. Read-only. symbology=datamatrix renders an ISO/IEC 16022 Data Matrix instead of a QR (EN 18220 permits both; same passport URL). - get_qr_by_serial — args: { serial, format? (svg|png), symbology? (qr|datamatrix), gtin? }. Read-only. Same as get_qr, addressed by your own serial. A serial is unique only WITHIN a GTIN — if the same serial exists under two GTINs in your account the call returns 409 ambiguous_serial; pass `gtin` (or use get_qr by id) to resolve exactly. - list_snapshots — args: { id, page?, limit? (≤100), at? (ISO 8601) }. Read-only. Returns a paginated list of snapshots for the passport (newest first). A snapshot is written on publish and after every change to a non-draft passport (EN 18221 change archive); each carries id, version, reason (e.g. published|field_edit|status_change|baseline), actor (who caused it, when known), snapshotAt, contentHash, hashValid (re-verified on every read), restorable, fieldCount. With `at`, returns instead the single snapshot valid at that instant (full record plus validFrom/validUntil) — answers "what did this passport say on date D"; 404 before the first snapshot. Counts 1 against the daily read budget. - get_snapshot — args: { id, snapshotId }. Read-only. Returns the full archival record of one snapshot: the complete JSON-LD the passport asserted at that time, plus hash and hashValid. Counts 1 against the daily read budget. - get_condition_flags — args: { id }. Read-only. Returns the resolved condition profile Record<flagKey,{value,status,source}>. Condition flags are reviewer-approved yes/no facts gating conditional legal duties. Battery flags: hasBMS, rechargeable, externalStorageOnly, isStationaryBess. An approved flag makes specific fields required — a missing gated field is a hard publish block (conditional_missing). Counts 1 against the daily read budget. - get_condition_flags_by_serial — args: { serial, gtin? }. Read-only. Same as get_condition_flags, addressed by your own serial. 409 ambiguous_serial if serial not unique — pass gtin. - set_condition_flags — args: { id, flags: Record<flagKey, boolean|null> }. WRITE. Set or clear condition flags (null clears). Keys must be registered for the passport category (battery: hasBMS, rechargeable, externalStorageOnly, isStationaryBess). WARNING: approving a flag can make fields required and block publishing if those fields are empty — fix any gated fields before or immediately after setting the flag. Writes are approved + audited. Idempotency-Key supported. Counts 1 write. - set_condition_flags_by_serial — args: { serial, gtin?, flags }. WRITE. Same as set_condition_flags, addressed by your own serial. 409 ambiguous_serial if serial not unique — pass gtin. - capture_measurements — args: { id, measurements: [ { fieldKey, value, measuredAt (ISO 8601), externalId?, unit? } ] (≤500) }. WRITE, battery passports only, published only. Pushes over-life measurements from the customer's own equipment (e.g. a BMS reporting stateOfHealth, numberOfFullEquivalentChargingCycles; the Annex XIII point 4 use-data keys). Every measurement is stored; the newest per field becomes the passport's current value and sets dynamicDataAsOf. externalId makes a measurement idempotent. A value may be at most 16 KB serialised. batteryStatus is NOT a measurement (400 invalid_field_key). A key the Regulation keeps off this battery category returns 422 field_not_applicable (e.g. stateOfCertifiedEnergy on an LMT battery). Metered against the plan's monthly measurement allowance, not the daily write budget: paid plans keep counting past it at no charge; Free stops at its allowance. Reading a passport is never metered. - capture_measurements_by_serial — args: { serial, gtin?, measurements }. Same, addressed by your own serial. - list_measurements — args: { id, fieldKey?, from?, to? (ISO 8601), limit? (≤200), cursor? }. Read-only. Measurement history, newest first; page with the returned nextCursor. - list_measurements_by_serial — args: { serial, gtin?, fieldKey?, from?, to?, limit?, cursor? }. Read-only. - latest_measurements — args: { id }. Read-only. The newest measurement per accepted key (null where none yet). - latest_measurements_by_serial — args: { serial, gtin? }. Read-only.
Input Schema
{
"type": "object",
"properties": {
"action": {
"type": "string",
"enum": [
"list",
"get",
"get_by_serial",
"compliance",
"registry_readiness",
"get_condition_flags",
"get_condition_flags_by_serial",
"set_condition_flags",
"set_condition_flags_by_serial",
"capture_measurements",
"capture_measurements_by_serial",
"list_measurements",
"list_measurements_by_serial",
"latest_measurements",
"latest_measurements_by_serial",
"create",
"suspend",
"suspend_by_serial",
"archive",
"archive_by_serial",
"get_qr",
"get_qr_by_serial",
"list_snapshots",
"get_snapshot"
],
"description": "Which passport operation to run. Reads: list | get | get_by_serial | compliance | registry_readiness | get_condition_flags | get_condition_flags_by_serial | get_qr | get_qr_by_serial | list_snapshots | get_snapshot | list_measurements(_by_serial) | latest_measurements(_by_serial). Writes: set_condition_flags | set_condition_flags_by_serial | capture_measurements(_by_serial) | create (a draft, not billed). Lifecycle: suspend (reversible) | archive (IRREVERSIBLE; battery passports need `reason`), each with a _by_serial variant."
},
"args": {
"description": "Arguments for the chosen action; required fields depend on `action` (see each action above).",
"type": "object",
"properties": {
"id": {
"description": "Passport id. Required for get/compliance/suspend/archive/get_qr (the by-id actions).",
"type": "string"
},
"serial": {
"description": "Your own serial number. Required for the *_by_serial actions.",
"type": "string"
},
"gtin": {
"description": "For create (legacy): GS1 GTIN. Also used as a disambiguator for *_by_serial actions when a serial isn't unique (else 409 ambiguous_serial).",
"type": "string"
},
"productId": {
"description": "Parent product id. Required for create.",
"type": "string"
},
"identifier": {
"description": "EN 18219 scheme-tagged identifier for create. Must have `scheme` plus scheme-specific fields. Schemes: gs1 {gtin, serialNumber} | iso15459 {issuingAgencyCode, primaryId, serial?} | iec61406 {uri} | did {did, method} | doi {doi, granularity} (granularity: \"model\"|\"batch\"|\"item\" REQUIRED per EN 18219 §5.6.2(b)). Battery passports: gs1 and iso15459 only.",
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {}
},
"serialNumber": {
"description": "Serial for the new passport (create, legacy gs1 path).",
"type": "string"
},
"lineage": {
"description": "create, battery only: link a second-life battery's new passport to the original passport(s) (Art. 77(7)). See the create action.",
"type": "object",
"properties": {
"predecessors": {
"maxItems": 10,
"type": "array",
"items": {
"type": "object",
"properties": {
"identifier": {
"type": "string",
"maxLength": 2000
},
"internalPassportId": {
"type": "string"
},
"trigger": {
"type": "string",
"enum": [
"preparation_for_reuse",
"preparation_for_repurposing",
"repurposing",
"remanufacturing"
]
}
},
"required": [
"trigger"
]
}
},
"noPredecessorReason": {
"type": "string",
"maxLength": 500
}
},
"required": [
"predecessors"
]
},
"format": {
"description": "get/get_by_serial: summary|full. get_qr/get_qr_by_serial: svg|png.",
"type": "string"
},
"symbology": {
"description": "get_qr/get_qr_by_serial: qr (default) | datamatrix.",
"type": "string"
},
"at": {
"description": "list_snapshots: ISO 8601 instant — return the snapshot valid then instead of the list.",
"type": "string"
},
"lang": {
"description": "Resolve field values to one of the 24 EU locales server-side (get/get_by_serial).",
"type": "string"
},
"page": {
"description": "Page number for list (1-based).",
"type": "number"
},
"limit": {
"description": "Page size for list, max 100.",
"type": "number"
},
"status": {
"description": "Filter list by status: draft|in_review|approved|published|suspended|expired|archived.",
"type": "string"
},
"search": {
"description": "Filter list by a search term.",
"type": "string"
},
"snapshotId": {
"description": "Snapshot id. Required for get_snapshot.",
"type": "string"
},
"measurements": {
"description": "capture_measurements(_by_serial): [{ fieldKey, value, measuredAt, externalId?, unit? }], max 500.",
"type": "array",
"items": {
"type": "object",
"properties": {
"fieldKey": {
"type": "string",
"minLength": 1
},
"value": {},
"measuredAt": {
"type": "string",
"minLength": 1
},
"externalId": {
"type": "string"
},
"unit": {
"type": "string"
}
},
"required": [
"fieldKey",
"value",
"measuredAt"
]
}
},
"fieldKey": {
"description": "list_measurements(_by_serial): only this field key.",
"type": "string"
},
"from": {
"description": "list_measurements(_by_serial): measuredAt from (ISO 8601).",
"type": "string"
},
"to": {
"description": "list_measurements(_by_serial): measuredAt to (ISO 8601).",
"type": "string"
},
"cursor": {
"description": "list_measurements(_by_serial): nextCursor from the previous page.",
"type": "string"
},
"flags": {
"description": "For set_condition_flags / set_condition_flags_by_serial: Record<flagKey, boolean|null>. null clears the flag.",
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
]
}
},
"reason": {
"description": "archive / archive_by_serial: Required for battery passports: why the passport ends. A battery passport ends only when the battery has been recycled, so the choices are recycled, never placed on the market or put into service, or a duplicate or erroneous record.",
"type": "string",
"enum": [
"recycled",
"never_placed",
"duplicate_or_error"
]
}
}
}
},
"required": [
"action"
],
"$schema": "http://json-schema.org/draft-07/schema#"
}Output Schema
{
"type": "object",
"properties": {
"id": {
"description": "The resource's TracePass id, when the response is a single entity.",
"type": "string"
},
"items": {
"description": "The page of results, when the action is a list.",
"type": "array",
"items": {}
},
"total": {
"description": "Total matching records across all pages (list actions).",
"type": "number"
},
"page": {
"description": "Current page number (list actions).",
"type": "number"
},
"limit": {
"description": "Page size (list actions).",
"type": "number"
},
"totalPages": {
"description": "Total number of pages (list actions).",
"type": "number"
},
"result": {
"description": "Wraps a non-object response body (e.g. a QR code string)."
},
"error": {
"description": "Machine-readable error code, when the API rejected the request.",
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"message": {
"description": "Human-readable error or status detail, when present.",
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
}
},
"$schema": "http://json-schema.org/draft-07/schema#",
"additionalProperties": false
}🔴tracepass_passport_fields(action, args)
Update field values on a Digital Product Passport. Every change is recorded in the passport's audit trail with the credential that made it (API key or connected app) and this MCP channel. `source` (optional) says where the value came from. Omit it, or pass "manual", when the user gave you the value or it comes from their own records: it is written with the user's rights (approved for an API key or an admin; sent to review for a connected app acting for an editor). Pass "ai_suggested" when you found or inferred the value yourself (web research, reading a document): it lands in the dashboard review queue for a human to approve, and it is refused on fields only the economic operator may state or that must be measured (e.g. battery stateOfHealth). Actions (pass via `action`, with `args`): - update — args: { id, fieldKey, value, source? }. `value` type matches the field's dataType (string, number, boolean, array, object). - update_by_serial — args: { serial, fieldKey, value, gtin?, source? }. Same as update, addressed by your own serial. A serial is unique only WITHIN a GTIN — if it isn't unique in your account the call returns 409 ambiguous_serial; pass `gtin` (or use update by id) to resolve exactly.
Input Schema
{
"type": "object",
"properties": {
"action": {
"type": "string",
"enum": [
"update",
"update_by_serial"
],
"description": "Update one passport field, addressed by passport id (update) or by your serial (update_by_serial)."
},
"args": {
"description": "Arguments for the chosen action; required fields depend on `action`.",
"type": "object",
"properties": {
"id": {
"description": "Passport id. Required for update.",
"type": "string"
},
"serial": {
"description": "Your serial. Required for update_by_serial.",
"type": "string"
},
"gtin": {
"description": "GTIN disambiguator for update_by_serial when the serial isn't unique (else 409).",
"type": "string"
},
"fieldKey": {
"description": "The field key to set (required).",
"type": "string"
},
"value": {
"description": "The new value for the field (required). Type depends on the field's dataType."
},
"source": {
"description": "Where the value came from: \"manual\" (default — the user's statement) or \"ai_suggested\" (you found it; it goes to human review).",
"type": "string",
"enum": [
"manual",
"ai_suggested"
]
}
}
}
},
"required": [
"action"
],
"$schema": "http://json-schema.org/draft-07/schema#"
}Output Schema
{
"type": "object",
"properties": {
"id": {
"description": "The resource's TracePass id, when the response is a single entity.",
"type": "string"
},
"items": {
"description": "The page of results, when the action is a list.",
"type": "array",
"items": {}
},
"total": {
"description": "Total matching records across all pages (list actions).",
"type": "number"
},
"page": {
"description": "Current page number (list actions).",
"type": "number"
},
"limit": {
"description": "Page size (list actions).",
"type": "number"
},
"totalPages": {
"description": "Total number of pages (list actions).",
"type": "number"
},
"result": {
"description": "Wraps a non-object response body (e.g. a QR code string)."
},
"error": {
"description": "Machine-readable error code, when the API rejected the request.",
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"message": {
"description": "Human-readable error or status detail, when present.",
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
}
},
"$schema": "http://json-schema.org/draft-07/schema#",
"additionalProperties": false
}🔴tracepass_passport_parties(action, args)
Manage the economic-operator parties on a passport — manufacturer, importer, authorisedRepresentative, distributor, recycler, producerResponsibilityOrg. Each party carries a legal name and at least one identifier. Identifier rules (EN 18219 §6.2–6.5): a party needs at least one of `gln`, `legacyOperatorId`, or `operatorIdentifier`. If both `gln` and `operatorIdentifier` (scheme gln) are provided they must agree — a mismatch returns 400. An operatorIdentifier of scheme gln also fills the top-level `gln` field; facilityIdentifier never does. Typed identifiers (operatorIdentifier / facilityIdentifier) are not set by AI extraction or CSV import. operatorIdentifier schemes: • iso6523 — { scheme:"iso6523", icd:"<4 digits>", value } — ICD 0199 = LEI (ISO 17442), 0088 = GLN, 0060 = DUNS. • gln — { scheme:"gln", gln:"<13 digits>" } — also fills top-level `gln`. • did — { scheme:"did", did:"did:<method>:<id>" } — syntax-checked only (EN 18219 §6.4.2(b)). • doi — { scheme:"doi", doi:"10.<registrant>/<suffix>" } — doi:/https://doi.org/ prefix accepted and stripped. facilityIdentifier schemes: same four; the gln variant also accepts optional `extension` (GS1 SGLN sub-location). Actions (pass via `action`, with `args`): - set — args: { id, role, legalName, gln?, country?, url?, tradeName?, postalAddress?, email?, legacyOperatorId?, operatorIdentifier?, facilityIdentifier? }. Sets or updates one role. tradeName, postalAddress and email are shown on the public passport; for a battery importer they are its Battery Regulation Art. 41(3) details. - remove — args: { id, role }. Clears one role.
Input Schema
{
"type": "object",
"properties": {
"action": {
"type": "string",
"enum": [
"set",
"remove"
],
"description": "Set (add/replace) or remove an economic-operator party on a passport by its role."
},
"args": {
"description": "Arguments for the chosen action; required fields depend on `action`.",
"type": "object",
"properties": {
"id": {
"description": "Passport id (required).",
"type": "string"
},
"role": {
"description": "Economic-operator role: manufacturer | importer | authorisedRepresentative | distributor | recycler | producerResponsibilityOrg (required).",
"type": "string"
},
"legalName": {
"description": "Party legal name. Required for set.",
"type": "string"
},
"gln": {
"description": "GS1 Global Location Number (13 digits). Strongly recommended for multi-role disambiguation.",
"type": "string"
},
"country": {
"description": "ISO 3166-1 alpha-2 country code (set, optional).",
"type": "string"
},
"url": {
"description": "Organisation web address (set, optional).",
"type": "string"
},
"tradeName": {
"description": "Registered trade name or registered trade mark, max 200 chars (set, optional). Public.",
"type": "string"
},
"postalAddress": {
"description": "Postal address with a single contact point, one line, max 500 chars (set, optional). Public.",
"type": "string"
},
"email": {
"description": "Company contact e-mail, not a person's (set, optional). Public.",
"type": "string"
},
"legacyOperatorId": {
"description": "Free-text fallback identifier (VAT, EORI, supplier code). Required when gln and operatorIdentifier are both absent.",
"type": "string"
},
"operatorIdentifier": {
"description": "Structured operator identifier per EN 18219 §6.2–6.5. Must have `scheme` plus scheme fields. Schemes: iso6523 {icd:\"<4 digits>\", value} | gln {gln:\"<13 digits>\"} | did {did:\"did:<method>:<id>\"} | doi {doi:\"10.<registrant>/<suffix>\"}. scheme gln also fills the top-level gln field; they must match if both are set (400 otherwise). Not set by AI extraction.",
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {}
},
"facilityIdentifier": {
"description": "Structured facility identifier per EN 18219 §6.2–6.5. Same four schemes as operatorIdentifier; the gln variant also accepts optional `extension` (GS1 SGLN sub-location). Never fills the top-level gln field. Not set by AI extraction.",
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {}
}
}
}
},
"required": [
"action"
],
"$schema": "http://json-schema.org/draft-07/schema#"
}Output Schema
{
"type": "object",
"properties": {
"id": {
"description": "The resource's TracePass id, when the response is a single entity.",
"type": "string"
},
"items": {
"description": "The page of results, when the action is a list.",
"type": "array",
"items": {}
},
"total": {
"description": "Total matching records across all pages (list actions).",
"type": "number"
},
"page": {
"description": "Current page number (list actions).",
"type": "number"
},
"limit": {
"description": "Page size (list actions).",
"type": "number"
},
"totalPages": {
"description": "Total number of pages (list actions).",
"type": "number"
},
"result": {
"description": "Wraps a non-object response body (e.g. a QR code string)."
},
"error": {
"description": "Machine-readable error code, when the API rejected the request.",
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"message": {
"description": "Human-readable error or status detail, when present.",
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
}
},
"$schema": "http://json-schema.org/draft-07/schema#",
"additionalProperties": false
}🟢tracepass_epcis(action, args)
GS1 EPCIS 2.0 supply-chain events. `export`, `capture`, `capture_job` and `query` are on every plan, Free included. Captured events count against the plan's event allowance (10 a month on Free); over it, `capture` returns an overage or hard-block message. Actions (pass via `action`, with `args`): - export — args: { id }. Export a passport's events as an EPCIS 2.0 JSON-LD document. Read-only. - export_by_serial — args: { serial, gtin? }. Same as export, addressed by your own serial. A serial is unique only WITHIN a GTIN — if it isn't unique in your account the call returns 409 ambiguous_serial; pass `gtin` (or use export by id). Read-only. - capture — args: { events }. `events` is an EPCISDocument, a single event, or an array of events (JSON-LD). Returns a 202 with a captureJobId. - capture_job — args: { jobId }. Poll an async capture job. Read-only. - query — args: { params? }. `params` is a key/value map of standard EPCIS query parameters (EQ_bizStep, GE_eventTime, MATCH_epc, …). Read-only.
Input Schema
{
"type": "object",
"properties": {
"action": {
"type": "string",
"enum": [
"export",
"export_by_serial",
"capture",
"capture_job",
"query"
],
"description": "EPCIS 2.0: export a passport's events (export | export_by_serial), capture new events, poll a capture job, or query events."
},
"args": {
"description": "Arguments for the chosen action; required fields depend on `action`.",
"type": "object",
"properties": {
"id": {
"description": "Passport id. Required for export.",
"type": "string"
},
"serial": {
"description": "Your serial. Required for export_by_serial.",
"type": "string"
},
"gtin": {
"description": "GTIN disambiguator for export_by_serial when the serial isn't unique (else 409).",
"type": "string"
},
"events": {
"description": "EPCIS 2.0 event payload (an EPCISDocument or event list). Required for capture."
},
"jobId": {
"description": "Capture job id to poll. Required for capture_job.",
"type": "string"
},
"params": {
"description": "EPCIS query parameters as key→value strings (query, optional).",
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"type": "string"
}
}
}
}
},
"required": [
"action"
],
"$schema": "http://json-schema.org/draft-07/schema#"
}Output Schema
{
"type": "object",
"properties": {
"id": {
"description": "The resource's TracePass id, when the response is a single entity.",
"type": "string"
},
"items": {
"description": "The page of results, when the action is a list.",
"type": "array",
"items": {}
},
"total": {
"description": "Total matching records across all pages (list actions).",
"type": "number"
},
"page": {
"description": "Current page number (list actions).",
"type": "number"
},
"limit": {
"description": "Page size (list actions).",
"type": "number"
},
"totalPages": {
"description": "Total number of pages (list actions).",
"type": "number"
},
"result": {
"description": "Wraps a non-object response body (e.g. a QR code string)."
},
"error": {
"description": "Machine-readable error code, when the API rejected the request.",
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"message": {
"description": "Human-readable error or status detail, when present.",
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
}
},
"$schema": "http://json-schema.org/draft-07/schema#",
"additionalProperties": false
}🟢tracepass_templates(action, args)
Discover the regulatory field schema for each DPP category — what a COMPLIANT passport must contain, per the governing EU regulation. Read-only reference data. Use this to advise on requirements before creating products/passports, and to gap-check a draft against the rules. Actions (pass via `action`, with `args`): - list — args: {}. Lists all 13 categories with their field count, required-field count, and governing regulation (name + number + effective/mandatory dates). - get — args: { category }. Full field schema for one category: every field's key, label, dataType, whether it is REQUIRED, its access level (public/restricted/authority), enum options, validation bounds, and — where known — the regulation article/annex that mandates it. `category` is one of: battery, textile, electronics, construction, steel, detergents, paints-coatings, packaging, furniture, tyres, jewelry, toys, fmcg. BATTERY — required-ness is per-category, so `required` alone is the wrong answer. Resolve it in this order: 1. SCOPE FIRST. Only EV, LMT and industrial_gt_2kwh batteries owe a passport at all (Art. 77(1), Reg (EU) 2023/1542). For portable, SLI or industrial_lte_2kwh, NO field is required — do not list mandatory fields for them; say the battery is out of scope. 2. Then `requiredBy[batteryCategory]` where the field carries that map (required | conditional | notApplicable). 3. Then fall back to `required`. The map is keyed ONLY by the three in-scope categories, so skipping step 1 falls through to `required` and invents an obligation the Regulation does not impose. Note also that EV and LMT report state-of-health through MUTUALLY EXCLUSIVE field sets — an EV battery must leave the remaining-capacity cluster empty and an LMT battery must leave stateOfCertifiedEnergy empty, so no single battery ever fills every field.
Input Schema
{
"type": "object",
"properties": {
"action": {
"type": "string",
"enum": [
"list",
"get"
],
"description": "List all DPP category templates, or get one template by category."
},
"args": {
"description": "Arguments for the chosen action; `category` is required for get, ignored for list.",
"type": "object",
"properties": {
"category": {
"description": "DPP category to fetch (required for get): battery | textile | electronics | construction | steel | detergents | paints-coatings | packaging | furniture | tyres | jewelry | toys | fmcg.",
"type": "string"
}
}
}
},
"required": [
"action"
],
"$schema": "http://json-schema.org/draft-07/schema#"
}Output Schema
{
"type": "object",
"properties": {
"id": {
"description": "The resource's TracePass id, when the response is a single entity.",
"type": "string"
},
"items": {
"description": "The page of results, when the action is a list.",
"type": "array",
"items": {}
},
"total": {
"description": "Total matching records across all pages (list actions).",
"type": "number"
},
"page": {
"description": "Current page number (list actions).",
"type": "number"
},
"limit": {
"description": "Page size (list actions).",
"type": "number"
},
"totalPages": {
"description": "Total number of pages (list actions).",
"type": "number"
},
"result": {
"description": "Wraps a non-object response body (e.g. a QR code string)."
},
"error": {
"description": "Machine-readable error code, when the API rejected the request.",
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"message": {
"description": "Human-readable error or status detail, when present.",
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
}
},
"$schema": "http://json-schema.org/draft-07/schema#",
"additionalProperties": false
}🟡tracepass_scope(action, args)
Check what EU law says for a product type matching the facts given: whether it needs a Digital Product Passport, from when, at which level, under which act and article, and the duties of each role. Also read the company's catalogue-wide scope report and trigger a catalogue refresh run. HARD RULES — always apply these to scope answers: - Answers state what the law says for product types matching the given facts. This is not legal advice; never write 'you must' — use product-type phrasing ('LMT batteries need a passport from 18 February 2027, Battery Regulation Art. 77(1)'). - Cite the article the answer gives for every verdict and duty. A regulation without an article is not a citation. A `not_covered` answer rests on no article: say our rules do not cover the product and name the nearest act it gives, never cite that act as the basis. - A date with precision 'quarter', 'month' or 'year' is a plan, NEVER a deadline or a start date. Write 'planned for Q2 2027 (planned, not law yet)', never 'from', 'by' or 'deadline'. - Relay `not_covered` and `needs_input` as the results they are, never as errors. `not_covered` = the product falls outside these scope rules. `needs_input` = blocking questions remain unanswered — relay the questions in `ask[]` to the user before giving a verdict. - Items in an act's `planned` list are not law yet: always label them 'Planned, not law yet' (`labelText`), with their `wording`. - `ruleStatus: 'needs_recheck'` means the law behind an act changed and our rules for it are being re-checked (since `recheckSince`): say so with the answer. Actions (pass via `action`, with `args`): - check — args: { category?, facts?, role?, placedOnMarket?, lifecycleEvent?, contains?, productId?, passportId?, locale? }. Ask whether a product type needs a DPP. Available on every plan, Free included. Counts against the per-company scope-answer cap (~100/day, 30/min burst), NOT the v1 read/write budget. 429 `scope_answer_cap` when the daily cap is spent. `not_covered` and `needs_input` are 200 results, not errors. category: one of battery | detergents | toys | construction | textile | steel | tyres | furniture | electronics | packaging | paints-coatings | jewelry | fmcg | vehicles | other. facts: namespace-prefixed keys from the loaded rules (e.g. battery.use, battery.capacityKWh). Unknown keys or wrong values return 400 invalid_input. role: your role in the act's terms: manufacturer | importer | distributor | authorised_representative | fulfilment_service_provider. Selling under your own name = manufacturer with facts.ownBrand: true. Omit to list every role's duties. placedOnMarket: { date: 'YYYY-MM-DD' | 'YYYY-MM' | 'YYYY', precision?: 'day'|'month'|'year' } or null. contains: array (≤5) of component queries — use to ask about a battery inside a toy: [ { label?, facts? } ]. locale: en | bg | de | it (default: from Accept-Language header, else en). - catalogue_report — args: { classification?, category?, act?, changed?, q?, cursor?, limit? (≤500) }. Read the catalogue-wide scope report (one row per product). Requires the Growth plan or above; 403 `plan_upgrade_required` below Growth — tell the user this needs a plan upgrade, do not retry. Counts 1 against the daily read budget per page. classification filter: missing | draft_only | published_incomplete | published | not_required | open_questions | not_covered. Response: { run, running, totals, items: [{ productId, passportIds, gtin, category, summary, classification, changedAt }], nextCursor, disclaimer }. Full answer for one product: call check with that productId. - catalogue_run — args: {}. Start a catalogue scope refresh run (also runs nightly). Returns 202 { runId, status }; poll with catalogue_run_status. Requires Growth plan. 409 run_in_progress if already active; 429 run_cooldown with retryAfter within 10 minutes of a finished run. - catalogue_run_status — args: { runId }. Get the status (queued | running | done | failed) and result counts for one catalogue run. Requires Growth plan.
Input Schema
{
"type": "object",
"properties": {
"action": {
"type": "string",
"enum": [
"check",
"catalogue_report",
"catalogue_run",
"catalogue_run_status"
],
"description": "Which scope operation to run: check | catalogue_report | catalogue_run | catalogue_run_status."
},
"args": {
"description": "Arguments for the chosen action; required fields depend on `action` (see above).",
"type": "object",
"properties": {
"category": {
"description": "Product category for check (battery, textile, vehicles, other, …).",
"type": "string"
},
"facts": {
"description": "Fact key→value map for check (e.g. { 'battery.use': 'ev' }).",
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {}
},
"role": {
"description": "Role hint for check (e.g. manufacturer, importer, ownBrand).",
"type": "string"
},
"placedOnMarket": {
"description": "Placing date for check: { date: YYYY[-MM[-DD]], precision?: day|month|year } or null.",
"anyOf": [
{
"type": "object",
"properties": {
"date": {
"type": "string"
},
"precision": {
"type": "string"
}
},
"required": [
"date"
]
},
{
"type": "null"
}
]
},
"lifecycleEvent": {
"description": "Lifecycle event for check (e.g. end_of_life).",
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"contains": {
"description": "Component queries for check (max 5), e.g. a toy containing a battery.",
"type": "array",
"items": {
"type": "object",
"properties": {
"label": {
"type": "string"
},
"facts": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {}
}
}
}
},
"productId": {
"description": "Product id — adds saved product facts and passport data to check.",
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"passportId": {
"description": "Passport id — adds saved passport facts to check.",
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"locale": {
"description": "Answer locale for check: en | bg | de | it.",
"type": "string"
},
"classification": {
"description": "Filter catalogue_report by classification: missing | draft_only | published_incomplete | published | not_required | open_questions | not_covered.",
"type": "string"
},
"act": {
"description": "Filter catalogue_report by governing act (CELEX, e.g. 32023R1542).",
"type": "string"
},
"changed": {
"description": "catalogue_report: true to return only rows changed since the last run.",
"type": "boolean"
},
"q": {
"description": "catalogue_report: search by product name or GTIN.",
"type": "string"
},
"cursor": {
"description": "Pagination cursor (catalogue_report).",
"type": "string"
},
"limit": {
"description": "Page size for catalogue_report, max 500.",
"type": "number"
},
"runId": {
"description": "Run id to poll (catalogue_run_status).",
"type": "string"
}
}
}
},
"required": [
"action"
],
"$schema": "http://json-schema.org/draft-07/schema#"
}Output Schema
{
"type": "object",
"properties": {
"id": {
"description": "The resource's TracePass id, when the response is a single entity.",
"type": "string"
},
"items": {
"description": "The page of results, when the action is a list.",
"type": "array",
"items": {}
},
"total": {
"description": "Total matching records across all pages (list actions).",
"type": "number"
},
"page": {
"description": "Current page number (list actions).",
"type": "number"
},
"limit": {
"description": "Page size (list actions).",
"type": "number"
},
"totalPages": {
"description": "Total number of pages (list actions).",
"type": "number"
},
"result": {
"description": "Wraps a non-object response body (e.g. a QR code string)."
},
"error": {
"description": "Machine-readable error code, when the API rejected the request.",
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"message": {
"description": "Human-readable error or status detail, when present.",
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
}
},
"$schema": "http://json-schema.org/draft-07/schema#",
"additionalProperties": false
}Community
Evidence