Skip to content

HTTP API

Every instance serves its web pages and a machine API from the same host. All routes are GET. They need no authentication and allow cross-origin requests (Access-Control-Allow-Origin: *).

Interactive reference

Each instance has an interactive reference of its machine API at /docs, with a console to try requests. It is generated from the OpenAPI 3.1 contract at /openapi.json and /openapi.yaml.

Machine API

<hub> is the domain of a hub that the instance follows, such as iscc.id. ISCC-ID parameters accept any letter case, with or without the ISCC: or did:iscc: prefix.

Evidence

Route Returns
/inclusion/<iscc_id>.bundle The proof bundle for an ISCC-ID, as a JSON download
/<hub>/log/inclusion?iscc_id=<id> Inclusion proof of the ISCC-ID's record against the accepted checkpoint. If several records name the ID, &index=<n> picks one
/<hub>/log/consistency?from=<size> Consistency proof from an earlier size to the accepted size
/<hub>/log/verify?iscc_id=<id> verify-for-me: the monitor's own verdict, the weaker path

For the consistency route, from can be any size from 0 to the accepted size, with or without a recorded checkpoint at that size. A larger from returns 400. 404 means no accepted checkpoint yet, or a tile is not mirrored.

Mirror

These routes serve the monitor's mirror of the hub's log at tlog-tiles paths. Standard tlog-tiles clients can read the log from the monitor instead of the hub.

Route Returns
/<hub>/log/checkpoint The last hub-signed checkpoint that the monitor accepted
/<hub>/log/tile/<path> A hash tile or entry bundle, such as tile/0/000 or tile/entries/000
/<hub>/log/entries?index=<n> The bytes of the single record at position n
/<hub>/log/checkpoint.ots[?size=<n>] The OpenTimestamps proof of the accepted root, or of the root accepted at size n

Operations

Route Returns
/healthz Liveness and database readiness
/version The running build
/metrics Prometheus metrics. Often not public, see Monitoring

Web pages

The pages work without JavaScript and load nothing from other sites. They are not part of the OpenAPI contract.

Route Page
/ Start page: ISCC-ID lookup and every hub with its status
/inclusion/<iscc_id> Certificate of Inclusion
/<hub> A hub's page: status, coverage, checkpoints and Bitcoin anchors
/<hub>/log/ The hub's mirrored log
/<hub>/log/records The hub's records, newest first
/<hub>/log/record?index=<n> One record
/docs Interactive API reference

Examples

Get the monitor's verdict:

curl "https://monitor.iscc.io/iscc.id/log/verify?iscc_id=ISCC:MEIGKV5N6NTVF4AB"

{
  "iscc_id": "ISCC:MEIGKV5N6NTVF4AB",
  "hub_status": "verified",
  "tree_size": 220,
  "root": "ILlsIpVPzNH4BGP8hM2I+roOSakYq+qyx67H+21yIq0=",
  "leaf_index": 0,
  "included": true,
  "verified": true,
  "reason": ""
}

If the monitor cannot verify an ISCC-ID, it still returns 200, with "verified": false and a reason.

Get the bytes of that record:

curl "https://monitor.iscc.io/iscc.id/log/entries?index=0"