Aeroz

Verify a physical item by its Aeroz chip: the UID plus whatever signature the tap carried. Same answer as GET /v1/verify. Use this before trusting any claim about a physical unit — a database record proves a record exists, not that the object in front of you is the one it describes. Read `proof` and `proves`: proof "presence" means the chip answered a fresh one-time SUN challenge (picc_data + cmac) and was physically there at this tap; proof "identity" means the static `t` signature is the one Aeroz issued for this UID, which a copied tag also carries. verified:false with reason "no_signature" (recognised:true) proves NOTHING about the item — only that the number is on the register. "signature_unchecked" means the signature was not compared (not a mismatch). A failed signature returns NO product data. Each call records the tap and spends the chip's one-time answer, so pass each SUN tap once. A sandbox key answers its seeded sandbox chips as fixtures (mode "sandbox" with a _warning) and any other UID from the register (mode "sandbox", register:true), so a sandbox company can check the test tags it minted.

{
  "type": "object",
  "properties": {
    "uid": {
      "type": "string",
      "description": "The chip UID read from the NFC tag or QR payload. Optional when SUN parameters or a tap_url carry it."
    },
    "signature": {
      "type": "string",
      "description": "The static signature from the tag payload (the `t` parameter). Proves identity, not presence."
    },
    "picc_data": {
      "type": "string",
      "description": "SUN: the encrypted `picc_data` (or `e`) parameter from an NTAG 424 tap URL. Send with `cmac`."
    },
    "cmac": {
      "type": "string",
      "description": "SUN: the `cmac` (or `c`) parameter from the same tap URL."
    },
    "tap_url": {
      "type": "string",
      "description": "Alternatively, the full https tap URL the phone opened (on an Aeroz host). uid, t, picc_data/e and cmac/c are read from it."
    }
  }
}

Check whether a specific unit is subject to an active recall, from the register: reads only, verifies no signature and spends no chip answer. Returns known (on the register), recalled, and the recall reason, severity, date and id when one applies. recalled:null means the status is UNKNOWN (the UID is not on the register, or the register could not be read) — never report that as "not recalled". This says nothing about whether the item is genuine; use verify_chip for that. Use whenever a unit is about to be shipped, sold, dispensed, or installed. A sandbox key answers its seeded sandbox chips first and any other UID from the register (register:true).

{
  "type": "object",
  "properties": {
    "uid": {
      "type": "string",
      "description": "The chip UID of the unit to check."
    }
  },
  "required": [
    "uid"
  ]
}

Assess how ready a product category is for an EU Digital Product Passport, against the delegated act that applies to it. Returns the required data fields, which are present, and which are missing. IMPORTANT: this is a readiness signal, not a legal compliance determination — never report its output as confirmation that a product is compliant.

{
  "type": "object",
  "properties": {
    "category": {
      "type": "string",
      "description": "Product group, e.g. \"batteries\", \"textiles\", \"iron_steel\", \"furniture\", \"tyres\", \"aluminium\"."
    }
  },
  "required": [
    "category"
  ]
}

List findings raised by the Aeroz compliance agents watching this organisation — recall hits, DPP data gaps, regulatory changes, dwell anomalies, and clone detections. Use this to answer "what needs my attention".

{
  "type": "object",
  "properties": {
    "severity": {
      "type": "string",
      "enum": [
        "info",
        "warn",
        "critical"
      ],
      "description": "Filter by severity."
    },
    "limit": {
      "type": "number",
      "description": "Maximum findings to return (default 25, max 200)."
    }
  }
}

List the Aeroz compliance agents available to this organisation and which are currently enabled. Use this to explain monitoring coverage or to find an agent worth enabling.

{
  "type": "object",
  "properties": {}
}

Return this organisation's Aeroz verification volume and outcome breakdown over a recent period. Use for reporting on scan volume, authentication failure rates, and trend. The buckets — authentic, recalled (any tap whose answer carried a recall, verified or not), mismatched (failed static or SUN signature), not_found, unverified (no or unchecked signature, test tag, held or disabled unit) and other — always sum to total.

{
  "type": "object",
  "properties": {
    "days": {
      "type": "number",
      "description": "Days to look back (default 30, max 365)."
    }
  }
}

List the seeded sandbox chips for this organisation, with the UID and signature to pass to verify_chip, one per scenario: authentic, recalled, signature_mismatch (listed with a deliberately WRONG signature) and not_found (a UID that is not on the register). Sandbox only — use when building or testing an integration before physical chips ship.

{
  "type": "object",
  "properties": {}
}

Report where this organisation stands in Aeroz onboarding: current stage, percentage complete, health, the single next action, and every open step with which side owns it. Use this to answer "what do we still need to do", "why are we not live yet", or "what is Aeroz waiting on". Steps marked side="aeroz" are Aeroz's obligation, not the customer's — say so plainly rather than presenting them as homework.

{
  "type": "object",
  "properties": {}
}

Return only the single most important next action and how to complete it. Use when the user asks what to do next and does not want the whole checklist.

{
  "type": "object",
  "properties": {}
}

Mark a manual onboarding step complete on behalf of this organisation. Only steps the customer owns and that Aeroz cannot verify automatically can be set this way; an automatically verified step will refuse, because a self-report that contradicts the platform data is worse than no report. Pass the step key from onboarding_status.

{
  "type": "object",
  "properties": {
    "key": {
      "type": "string",
      "description": "The step key, e.g. \"gs1_prefix\" or \"carrier_chosen\"."
    },
    "note": {
      "type": "string",
      "description": "What was done, for the audit trail."
    }
  },
  "required": [
    "key"
  ]
}

The full picture of this business as Aeroz holds it: declared product categories with their mandate dates and whether each date is fixed or provisional, onboarding state, open findings, and — importantly — which recall sources are NOT being monitored. Use this to orient before answering anything about the account. Never present an empty findings list as evidence of safety without also reporting coverage_gaps.

{
  "type": "object",
  "properties": {}
}

Ask this organisation's dedicated Aeroz agent a question in plain language and get a grounded answer. Use it for anything a human at the business would ask their account manager: "what do we still need to do", "when is our deadline", "what is Aeroz waiting on", "what is not being monitored", "how do we go live". The answer carries `grounded`: `computed` means it was read directly from the account's own data; `model` means a model composed it from that data and every date and figure was checked against it; `declined` means the agent does not hold what the question needs and said so — relay that honestly rather than filling the gap yourself. Asking refreshes the account's onboarding state and records the question and answer in the conversation (see agent_conversation). It sends nothing outside Aeroz and changes no product, shipment or passport data.

{
  "type": "object",
  "properties": {
    "question": {
      "type": "string",
      "description": "The question, as the person asked it (at most 2000 characters)."
    }
  },
  "required": [
    "question"
  ]
}

The recent conversation between this organisation and its Aeroz agent, across the dashboard, MCP and email. Use it to see what has already been asked and answered before asking again.

{
  "type": "object",
  "properties": {
    "limit": {
      "type": "number",
      "description": "Turns to return (default 20, max 60)."
    }
  }
}

Register a shipment of physical items under a sensitivity profile so Aeroz can watch it in transit. Profiles: cold_chain (2–8 °C, mean kinetic temperature), frozen (≤ −15 °C), ambient_crt (15–30 °C, MKT ≤ 25), fragile (shock, tilt), high_value (light = container opened, dwell, chip-verified custody at every handoff), standard (movement only). Origin and destination need decimal-degree coordinates. Items may carry a chip uid, GTIN, lot and serial. Returns the shipment id and the thresholds that will judge it.

{
  "type": "object",
  "properties": {
    "reference": {
      "type": "string",
      "description": "Your own reference (PO, ASN, waybill)."
    },
    "profile": {
      "type": "string",
      "enum": [
        "cold_chain",
        "frozen",
        "ambient_crt",
        "fragile",
        "high_value",
        "standard"
      ]
    },
    "carrier": {
      "type": "string"
    },
    "origin": {
      "type": "object",
      "properties": {
        "label": {
          "type": "string"
        },
        "lat": {
          "type": "number"
        },
        "lng": {
          "type": "number"
        }
      },
      "required": [
        "lat",
        "lng"
      ]
    },
    "destination": {
      "type": "object",
      "properties": {
        "label": {
          "type": "string"
        },
        "lat": {
          "type": "number"
        },
        "lng": {
          "type": "number"
        }
      },
      "required": [
        "lat",
        "lng"
      ]
    },
    "planned_depart": {
      "type": "string",
      "description": "ISO 8601"
    },
    "planned_arrive": {
      "type": "string",
      "description": "ISO 8601"
    },
    "thresholds": {
      "type": "object",
      "description": "Optional overrides of the profile defaults (temp_min_c, temp_max_c, mkt_max_c, shock_crit_g, dwell_max_min, …)."
    },
    "items": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "uid": {
            "type": "string"
          },
          "gtin": {
            "type": "string"
          },
          "lot_number": {
            "type": "string"
          },
          "serial": {
            "type": "string"
          },
          "description": {
            "type": "string"
          },
          "quantity": {
            "type": "number"
          }
        }
      }
    }
  },
  "required": [
    "origin",
    "destination"
  ]
}

Everything Aeroz holds about one shipment: profile and thresholds, status, items, custody events with their chip verification, the telemetry assessment (min/max/mean temperature, mean kinetic temperature, minutes out of range, peak shock, whether an excursion is open), the ranked routes, and open findings. Use for "where is it", "is the cold chain intact", "was it ever opened". An open excursion on a cold-chain lane means the load must be quarantined on arrival pending QA — say so.

{
  "type": "object",
  "properties": {
    "shipment_id": {
      "type": "string"
    }
  },
  "required": [
    "shipment_id"
  ]
}

List this organisation's shipments, optionally by status (planned | in_transit | delivered | exception | cancelled).

{
  "type": "object",
  "properties": {
    "status": {
      "type": "string"
    },
    "limit": {
      "type": "number"
    }
  }
}

Record sensor readings for a shipment — position, temperature, humidity, shock, tilt, light, battery — up to 500 per call. Aeroz judges the whole recent stream against the lane's thresholds immediately and returns the assessment and any findings raised. A shipment in `planned` moves to `in_transit` on its first reading. Readings from a logger read out at the dock are accepted after `delivered` if they fall inside the journey (departure − 60 min to arrival + 60 min); a cancelled shipment accepts none. Each logger (`source`) is judged on its own; the assessment reports the worst logger and every logger in temp.by_source, plus unobserved minutes. More than 500 readings, future readings and duplicates are refused or ignored and counted.

{
  "type": "object",
  "properties": {
    "shipment_id": {
      "type": "string"
    },
    "readings": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "at": {
            "type": "string",
            "description": "ISO 8601; defaults to now"
          },
          "lat": {
            "type": "number"
          },
          "lng": {
            "type": "number"
          },
          "temp_c": {
            "type": "number"
          },
          "humidity_pct": {
            "type": "number"
          },
          "shock_g": {
            "type": "number"
          },
          "tilt_deg": {
            "type": "number"
          },
          "light_lux": {
            "type": "number"
          },
          "battery_pct": {
            "type": "number"
          }
        }
      }
    }
  },
  "required": [
    "shipment_id",
    "readings"
  ]
}

Record a custody event on a shipment: pickup, checkpoint, handoff, delivered, exception or note. Pass the chip `uid` (and `signature`) read at the handoff and Aeroz verifies it on the spot, turning a signature on a form into proof of presence. On a high_value lane a handoff without a verified chip raises a finding, and so does a chip that is not among the shipment's items (even an authentic one: `verify_result` is then uid_not_in_shipment; `chip_verify_result` is the chip's own verdict). `pickup` moves the shipment to in_transit and must come before `delivered` (logged telemetry also counts as departure), and `delivered` closes it. A delivered or cancelled shipment is final: it accepts only `note` events.

{
  "type": "object",
  "properties": {
    "shipment_id": {
      "type": "string"
    },
    "kind": {
      "type": "string",
      "enum": [
        "pickup",
        "checkpoint",
        "handoff",
        "delivered",
        "exception",
        "note"
      ]
    },
    "actor": {
      "type": "string"
    },
    "uid": {
      "type": "string"
    },
    "signature": {
      "type": "string"
    },
    "lat": {
      "type": "number"
    },
    "lng": {
      "type": "number"
    },
    "location": {
      "type": "string"
    },
    "note": {
      "type": "string"
    },
    "occurred_at": {
      "type": "string"
    }
  },
  "required": [
    "shipment_id",
    "kind"
  ]
}

Compute and rank routes for a shipment at a departure time, scored for its sensitivity profile: traffic-aware duration and delay, ambient heat or cold along the way against the lane's ceiling, and rain, snow or gusts. Lower score is better and only comparable within one computation. The best route is marked chosen. The response says plainly when routing or weather data was unavailable and the ranking is time-only — relay that; a straight-line estimate is not a traffic-aware route.

{
  "type": "object",
  "properties": {
    "shipment_id": {
      "type": "string"
    },
    "depart_at": {
      "type": "string",
      "description": "ISO 8601; defaults to the planned departure or now"
    }
  },
  "required": [
    "shipment_id"
  ]
}

The sensitivity profiles Aeroz can judge a shipment against and the exact thresholds each applies, plus whether traffic and weather providers are configured for this deployment.

{
  "type": "object",
  "properties": {}
}

Bind an Aeroz chip to a graded collectible slab (PSA, CGC, SGC, BGS, TAG). The chip UID, grader, cert number, grade and card identity are signed together, so the chip vouches for exactly this label: a label moved to another holder, or a cert reprinted on a copy, shows as "binding broken" on a buyer's tap. For PSA, the cert is cross-checked against PSA's own record when PSA_API_TOKEN is configured; a disagreement flags the item. `grader_check` is match, mismatch, not_found, unavailable (nobody looked), or unverified_identity (the grade agrees but the grader's record does not confirm the card). A chip that has ever been bound to a graded item is refused (use a new chip), and so is a grader cert already bound to another chip — for a re-holdered slab, retire the old binding with record_provenance first. Returns the public verify URL to encode in the slab's QR. This does NOT grade the card and does not claim the card was unaltered before sealing — never present it as either.

{
  "type": "object",
  "properties": {
    "uid": {
      "type": "string",
      "maxLength": 64,
      "description": "Chip UID bonded to the slab (at most 64 characters, as verify_chip accepts)."
    },
    "grader": {
      "type": "string",
      "enum": [
        "psa",
        "cgc",
        "sgc",
        "bgs",
        "tag",
        "other"
      ]
    },
    "cert_number": {
      "type": "string",
      "maxLength": 64
    },
    "grade": {
      "type": "string",
      "maxLength": 32,
      "description": "As printed: \"10\", \"9.5\", \"8 OC\", \"Authentic\", \"Authentic Altered\"."
    },
    "title": {
      "type": "string",
      "maxLength": 240,
      "description": "e.g. \"2003 Topps Chrome LeBron James #111\""
    },
    "category": {
      "type": "string",
      "maxLength": 40,
      "enum": [
        "trading_card",
        "coin",
        "comic",
        "memorabilia",
        "other"
      ]
    },
    "year": {
      "type": "string",
      "maxLength": 12
    },
    "set_name": {
      "type": "string",
      "maxLength": 120
    },
    "card_number": {
      "type": "string",
      "maxLength": 32
    },
    "subject": {
      "type": "string",
      "maxLength": 120
    },
    "variety": {
      "type": "string",
      "maxLength": 120
    },
    "front_image_url": {
      "type": "string",
      "maxLength": 500
    },
    "back_image_url": {
      "type": "string",
      "maxLength": 500
    },
    "public": {
      "type": "boolean",
      "description": "Resolvable by a public tap (default true)."
    },
    "sealed_at": {
      "type": "string"
    },
    "sealed_by": {
      "type": "string",
      "maxLength": 120
    }
  },
  "required": [
    "uid",
    "grader",
    "cert_number",
    "grade",
    "title"
  ]
}

A graded item as Aeroz holds it: grader, cert, grade, identity, whether the grader's own record matched, how many times it has been verified by tap, and its full provenance chain (sealed, sold, consigned, vaulted, shipped, verified…). Use for "is this slab the one that was sealed", "where has it been", "has anyone tried to pass off a copy". Report what this proves AND what it does not.

{
  "type": "object",
  "properties": {
    "item_id": {
      "type": "string"
    }
  },
  "required": [
    "item_id"
  ]
}

Append an event to a graded item's chain: sold, consigned, vaulted, withdrawn, shipped, received, flagged, retired, note. Events are append-only and, when public, appear on the buyer's tap page. `flagged` marks the item and needs a `note` saying why. `retired` ends the binding (the slab was re-holdered or destroyed) and needs a `note` saying why: the chip stops vouching for any label and the grader cert is freed to be bound to a new chip. A retired item accepts only `note` events.

{
  "type": "object",
  "properties": {
    "item_id": {
      "type": "string"
    },
    "kind": {
      "type": "string",
      "enum": [
        "sold",
        "consigned",
        "vaulted",
        "withdrawn",
        "shipped",
        "received",
        "flagged",
        "retired",
        "note"
      ]
    },
    "actor": {
      "type": "string",
      "maxLength": 120
    },
    "location": {
      "type": "string",
      "maxLength": 200
    },
    "note": {
      "type": "string",
      "maxLength": 2000
    },
    "occurred_at": {
      "type": "string",
      "description": "ISO 8601; not in the future, not before the item was sealed"
    },
    "public": {
      "type": "boolean"
    }
  },
  "required": [
    "item_id",
    "kind"
  ]
}

List this organisation's chip-bound graded items, optionally by status (sealed | active | flagged | retired).

{
  "type": "object",
  "properties": {
    "status": {
      "type": "string"
    },
    "limit": {
      "type": "number"
    }
  }
}

Return everything the Aeroz agent has built for this organisation: the regulatory calendar with only ADOPTED dates, the passport scaffold per product showing exactly which fields are missing, the identifier audit, the GS1 route, monitoring coverage, integration readiness, and the pre-filled audit scope. Each block carries a confidence — `computed` is derived from this account's own data and needs no review; `sourced` and `drafted` came from outside the platform or involved judgement and are cited. Use this to answer almost any question about what this business needs to do. Report a block's confidence when you rely on it, and never present a `drafted` block as settled.

{
  "type": "object",
  "properties": {
    "block": {
      "type": "string",
      "description": "Optional. One of: calendar, passport, identifiers, gs1, coverage, integration, audit_scope, packet, profile, regimes, contacts, carrier."
    }
  }
}

The whole history of one serialized unit: every custody hop from commissioning to dispensing, whether the append-only log has been tampered with, and what each regulation makes of it. Use this to answer "where has this been", "who handled it", "is its record trustworthy" and "does this unit pass DSCSA / the EU passport rules". Every failing check cites the clause it enforces — quote the clause, not just the verdict. IMPORTANT: verdicts are readiness signals, never a legal compliance determination, and the response says so. Never report one as confirmation that a product is compliant.

{
  "type": "object",
  "properties": {
    "unit_id": {
      "type": "string",
      "description": "The unit id (cun_...). Use find_unit first if you only have a scan."
    },
    "pack": {
      "type": "string",
      "description": "Optional: \"dscsa\" or \"dpp\". Omit to judge under every pack."
    }
  },
  "required": [
    "unit_id"
  ]
}

Resolve anything a scanner or a person can produce — a chip UID, a GS1 Digital Link URI, or a GTIN plus serial — to a unit, and return its history and verdicts. This is the tool for "what is this thing in front of me". An identifier that resolves to nothing is NOT the same as one that fails verification: the first means we have never seen it, the second means we have and it did not check out. Report them differently.

{
  "type": "object",
  "properties": {
    "uid": {
      "type": "string",
      "maxLength": 64,
      "description": "Chip UID read from a tap."
    },
    "upi": {
      "type": "string",
      "description": "Unique product identifier — usually a GS1 Digital Link URL."
    },
    "gtin": {
      "type": "string"
    },
    "serial": {
      "type": "string"
    }
  }
}

Sweep this organisation's units and report which regulatory checks are failing across the portfolio, how many units each affects, and examples to open. This is the tool for "which of my units have a broken custody chain", "what is failing right now", "what will not pass on 18 February" and "how are we doing overall". Counts are exact for the units swept; the response says when it hit its cap rather than implying it saw everything. An empty findings list means nothing failed among the units swept — it does not mean the organisation is compliant.

{
  "type": "object",
  "properties": {
    "pack": {
      "type": "string",
      "description": "Optional: \"dscsa\" or \"dpp\". Omit to sweep under every pack."
    },
    "status": {
      "type": "string",
      "description": "Optional: only units in this state (in_transit, in_stock, dispensed, recalled...)."
    },
    "limit": {
      "type": "number",
      "description": "Units to sweep, default 100, maximum 300."
    }
  }
}

Read the PUBLIC view of a published Digital Product Passport hosted by Aeroz, by its GS1 Digital Link (e.g. https://id.aeroz.io/01/09506000134352/21/ABC123) or its passport id (dpp_...). Returns the signed passport fields everyone may see, the version and its date, recall status and the item's links. Fields restricted to repairers, recyclers or authorities are listed as withheld, never shown. This reads the record only: it does NOT prove the physical item in front of you is genuine — use verify_chip with a fresh chip tap for that. A link from another resolver is refused, not fetched. Works without an API key. Passports of sandbox organisations are not public in production.

{
  "type": "object",
  "properties": {
    "digital_link": {
      "type": "string",
      "description": "A GS1 Digital Link on id.aeroz.io (query string is ignored)."
    },
    "dpp_id": {
      "type": "string",
      "description": "A passport id, dpp_ followed by 26 characters."
    },
    "version": {
      "type": "number",
      "description": "Optional: a specific version (with dpp_id)."
    },
    "date": {
      "type": "string",
      "description": "Optional: the passport as it stood on this ISO-8601 date (with dpp_id)."
    }
  }
}

Check a passport credential (a vc+jwt issued by Aeroz) against Aeroz's published signing keys. Returns valid:true with the issuer, product id, passportVersion and validFrom when the signature checks out and the credential is an Aeroz Digital Product Passport, or valid:false with the reason (including "revoked by the issuer" and "not an Aeroz passport credential"). A valid result means Aeroz issued exactly this content and has not revoked it; it does not mean the passport is the latest version — compare passportVersion with get_passport. Works without an API key.

{
  "type": "object",
  "properties": {
    "jwt": {
      "type": "string",
      "description": "The compact vc+jwt credential."
    }
  },
  "required": [
    "jwt"
  ]
}