Developers / REST API

A typed REST API for sensor data.

A documented REST surface for the TRL-4 demonstrator - single sign-on with role-based access control, an independent public verifier, and predictable JSON resources across the four representative source types. No published API spec yet covers these routes.

SurfaceDocumented REST routes (no Level Zero OpenAPI spec yet) AuthSingle sign-on with role-based access control per route (SAML SSO roadmap) Basehttps://api.levelzero.fr/api/level-zero

Principles

What works today: submit a representative input and get back a signed, hash-chained canonical product you can verify against the public trust anchor - end to end and reproducibly, backed by an automated test suite in CI and a reproducible demo bundle. The roadmap caveats below say what is not yet built.

  • Standards-aligned. Responses are canonical JSON (schema lz.canonical.v1), GeoJSON feeds, a machine-readable JSON Schema (Draft 2020-12), and an OGC SensorThings 1.1 alignment crosswalk - a field-mapping table, not a certified SensorThings server. STAC and CCSDS emitters are roadmap, not shipped.
  • Signed provenance, not silence. Every ingested product is Ed25519-signed and hash-chained into an append-only chain of custody enforced at the database layer - updates and deletes are blocked, so records can't be silently changed.

Authentication

Two modes:

  • Single sign-on (SSO) - for human users and dashboards, with scoped roles per Collection and per pipeline.
  • Role-based access control - every route is guarded by a named permission (levelzero.read, levelzero.ingest, levelzero.verify), enforced per tenant.
curl -H "Authorization: Bearer $LZ_KEY" \
     https://api.levelzero.fr/api/level-zero/products

Resources

ResourcePathNotes
JSON Schema/schema, /schema/jsonCanonical product schema (Draft 2020-12).
Products/products, /feed/productsList canonical products; JSON feed.
Corroboration/corroboration/events, /corroboration/feed.geojsonBounded corroboration candidates (75 km / 30 min gate); GeoJSON feed.
Verifier/public/verify, /public/trust-anchorIndependent public verifier pinned to a published trust anchor; forged keys rejected as untrusted_key.
Ingest/ingestSubmit representative / synthetic / replayed inputs; conditions them into a canonical product.
Interop/interop/ogc-sensorthingsOGC SensorThings 1.1 alignment crosswalk (mapping table).
Demo runs/demo-runsReproduce the deterministic golden demo bundle.
Webhooks/webhooksGeneric platform feature (signed outbound deliveries); not yet wired to Level Zero events.

Errors

Errors follow RFC 7807 problem details with a stable type URI, a human title, an HTTP status, a detail string, and a request-scoped instance.

HTTP/1.1 422 Unprocessable Content
Content-Type: application/problem+json

{
  "type": "https://errors.levelzero.fr/level-zero/invalid-product",
  "title": "Invalid canonical product",
  "status": 422,
  "detail": "confidence must be between 0.0 and 1.0",
  "instance": "urn:req:01H..."
}

Idempotency

Rate limits

As a TRL-4 demonstrator, the API is not yet rate-limited; published rate-limit headers and quotas are roadmap for an operational release.

Versioning

The demonstrator API is unversioned and may change as the pipeline evolves. A URL-pinned versioning and deprecation policy is planned for an operational release.

[ Ready to integrate ]