{ "openapi": "3.1.0", "info": { "title": "Raposza Network Operations Feed API", "version": "1", "summary": "Read-only view of what is deployed and scheduled on the Canton Network, and where every fact came from.", "description": "Every endpoint is a read of the current publication. Nothing is written through this API: there is no write route, no authentication and no session. Every response to a path under /api/ carries the identifier of the publication it was served from, in the X-Raposza-Publication header and, for list endpoints, in the body, so two readers can establish that they saw the same state.\n\nBefore the first publication exists the api serves a corpus generated at startup: no events, three networks with null values, and the source list with state UNKNOWN. metadata.content, read from /api/v1/status, says which case applies.", "license": { "name": "Apache-2.0", "identifier": "Apache-2.0" }, "x-copyright": "Copyright 2026 bentzn", "x-spdx": "SPDX-License-Identifier: Apache-2.0", "x-author": "Author Claude/bentzn" }, "servers": [ { "url": "/", "description": "The host serving this document" } ], "paths": { "/api/v1/status": { "get": { "operationId": "status", "summary": "Service state and the current publication", "responses": { "200": { "description": "Service state", "headers": { "X-Raposza-Publication": { "$ref": "#/components/headers/X-Raposza-Publication" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Status" } } } } } } }, "/api/v1/networks": { "get": { "operationId": "networks", "summary": "All three networks", "description": "Always DEVNET, TESTNET and MAINNET, in that order, with null values where nothing states a value, beside the latest Splice release that exists.", "responses": { "200": { "description": "The networks", "headers": { "X-Raposza-Publication": { "$ref": "#/components/headers/X-Raposza-Publication" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "publicationId", "spliceLatest", "networks" ], "properties": { "publicationId": { "type": "string", "description": "Publication the records come from" }, "spliceLatest": { "type": [ "string", "null" ], "description": "The highest Splice release the Splice tags endpoint carries, withdrawn tags excluded, compared segment by segment as numbers. Not per network: a release existing is not a network running it. Null where nothing states one.", "examples": [ "0.8.4" ] }, "spliceLatestEventId": { "type": [ "string", "null" ], "description": "The published event the latest release was read from; /api/v1/events/{id} carries its provenance" }, "networks": { "type": "array", "items": { "$ref": "#/components/schemas/Network" } } } } } } } } } }, "/api/v1/networks/{network}": { "get": { "operationId": "network", "summary": "One network", "parameters": [ { "name": "network", "in": "path", "required": true, "description": "Network name, matched case-insensitively", "schema": { "type": "string", "examples": [ "mainnet", "TESTNET", "devnet" ] } } ], "responses": { "200": { "description": "The network", "headers": { "X-Raposza-Publication": { "$ref": "#/components/headers/X-Raposza-Publication" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Network" } } } }, "404": { "description": "No record with that identifier in the current publication", "headers": { "X-Raposza-Publication": { "$ref": "#/components/headers/X-Raposza-Publication" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/events": { "get": { "operationId": "events", "summary": "Every published event", "description": "All events, including those whose date has passed and those withdrawn upstream (withdrawn: true). No query parameters are read.", "responses": { "200": { "description": "The events", "headers": { "X-Raposza-Publication": { "$ref": "#/components/headers/X-Raposza-Publication" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "publicationId", "events" ], "properties": { "publicationId": { "type": "string", "description": "Publication the records come from" }, "events": { "type": "array", "items": { "$ref": "#/components/schemas/Event" } } } } } } } } } }, "/api/v1/events/{id}": { "get": { "operationId": "event", "summary": "One event", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Event identifier, matched exactly", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The event", "headers": { "X-Raposza-Publication": { "$ref": "#/components/headers/X-Raposza-Publication" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Event" } } } }, "404": { "description": "No record with that identifier in the current publication", "headers": { "X-Raposza-Publication": { "$ref": "#/components/headers/X-Raposza-Publication" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/sources": { "get": { "operationId": "sources", "summary": "The sources and their health", "responses": { "200": { "description": "The sources", "headers": { "X-Raposza-Publication": { "$ref": "#/components/headers/X-Raposza-Publication" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "publicationId", "sources" ], "properties": { "publicationId": { "type": "string", "description": "Publication the records come from" }, "sources": { "type": "array", "items": { "$ref": "#/components/schemas/Source" } } } } } } } } } }, "/api/v1/planned": { "get": { "operationId": "planned", "summary": "The schedule of the coming weeks", "description": "Every event of the SV Operations Schedule dated from the publication's UTC date up to `days` days ahead, both ends included, by date, then network, then kind, then title. Cancelled events are included and carry their status; withdrawn ones are not. Upstream gives no time zone, so only the date is published.", "responses": { "200": { "description": "The schedule of the coming weeks", "headers": { "X-Raposza-Publication": { "$ref": "#/components/headers/X-Raposza-Publication" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "publicationId", "days", "planned" ], "properties": { "publicationId": { "type": "string", "description": "Publication the records come from" }, "days": { "type": "integer", "description": "How far ahead the list reaches" }, "planned": { "type": "array", "items": { "$ref": "#/components/schemas/Planned" } } } } } } } } } }, "/api/v1/changes": { "get": { "operationId": "changes", "summary": "Everything that changed in the weeks behind", "description": "Every revision of every event whose causing body was banked in the last `days` days, newest first. The revisions a source made at its first banked observation are not listed: they record that the feed began to look, not that anything happened upstream. observedAt is when the feed banked the body that showed the change, not when the change was made upstream. A revision in which only versionStatus moved is an observation failure or its recovery and is not listed. unwatched names the spans of the window, longer than 15 minutes, in which no source was polled.", "responses": { "200": { "description": "Everything that changed in the weeks behind", "headers": { "X-Raposza-Publication": { "$ref": "#/components/headers/X-Raposza-Publication" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "publicationId", "days", "changes" ], "properties": { "publicationId": { "type": "string", "description": "Publication the records come from" }, "days": { "type": "integer", "description": "How far back the log reaches" }, "from": { "type": [ "string", "null" ], "format": "date-time", "description": "Where the window starts" }, "unwatched": { "type": "array", "items": { "type": "object", "properties": { "from": { "type": "string", "format": "date-time" }, "to": { "type": "string", "format": "date-time" } } }, "description": "Spans in which nothing was polled, so nothing could be seen" }, "changes": { "type": "array", "items": { "$ref": "#/components/schemas/Change" } } } } } } } } } }, "/api/v1/prices": { "get": { "operationId": "prices", "summary": "The latest CC/USD price of every price source", "description": "Every price source in definition order with its newest successful reading and its newest attempt. VOTED is the amuletPrice of a network's open mining round, read from its DSO document: the rate the Super Validators vote and the ledger uses, not a market price. MARKET is one venue's spot ticker and AGGREGATE a price over venues. A price is in its quote currency; USDT is not USD. Values are decimals as text, exactly as the source gave them. Before any price is read every value is null, and before the first publication exists collecting and pollSeconds are null as well.", "responses": { "200": { "description": "The latest prices", "headers": { "X-Raposza-Publication": { "$ref": "#/components/headers/X-Raposza-Publication" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "publicationId", "prices" ], "properties": { "publicationId": { "type": "string", "description": "Publication the records come from" }, "pollSeconds": { "type": [ "integer", "null" ], "description": "Seconds between two reads of every source" }, "collecting": { "type": [ "boolean", "null" ], "description": "Whether this environment reads prices at all" }, "polledAt": { "type": [ "string", "null" ], "description": "When the last read of every source ran", "format": "date-time" }, "prices": { "type": "array", "items": { "$ref": "#/components/schemas/Price" } } } } } } } } } } }, "components": { "headers": { "X-Raposza-Publication": { "description": "Identifier of the publication the response was served from", "schema": { "type": "string", "examples": [ "pub_20260929T172255Z" ] } } }, "schemas": { "Error": { "type": "object", "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "NOT_FOUND" ] }, "message": { "type": "string" } } }, "Status": { "type": "object", "properties": { "service": { "type": "string", "const": "raposza-network-feed" }, "environment": { "type": "string", "description": "Environment name as configured on the host; local when unset", "examples": [ "prd", "rc", "stg", "dev", "local" ] }, "version": { "type": "string", "description": "Release of Raposza Net serving the request; unknown when the artifact carries none", "examples": [ "0.9.0" ] }, "buildId": { "type": "string", "description": "Build serving the request; unknown when unset", "examples": [ "20260929-f144635" ] }, "content": { "type": "string", "description": "What the publication is made of: OBSERVED, the index was read and carried events; EMPTY, the index was read and carried none; UNAVAILABLE, the index could not be read", "enum": [ "OBSERVED", "EMPTY", "UNAVAILABLE" ] }, "publicationId": { "type": "string", "examples": [ "pub_20260929T172255Z" ] }, "publishedAt": { "type": "string", "description": "When the publication was created, UTC, second precision", "format": "date-time" }, "publicationAgeSeconds": { "type": "integer", "format": "int64", "description": "Seconds since publishedAt; -1 when publishedAt cannot be parsed" }, "uptimeSeconds": { "type": "integer", "format": "int64", "description": "Seconds since this api process started" }, "sources": { "type": "array", "items": { "$ref": "#/components/schemas/Source" } } } }, "Network": { "type": "object", "properties": { "network": { "type": "string", "enum": [ "DEVNET", "TESTNET", "MAINNET" ] }, "splice": { "type": "object", "description": "What the SV Operations Schedule states. Scheduled is not running: a date that has arrived is not evidence that the upgrade happened.", "properties": { "scheduledVersion": { "type": [ "string", "null" ], "description": "The latest CONFIRMED NETWORK_UPGRADE that carries a version and whose date is on or before the publication's UTC date" }, "scheduledPrecision": { "type": [ "string", "null" ] }, "scheduledFrom": { "type": [ "string", "null" ], "description": "ISO date", "format": "date" }, "scheduledEventId": { "type": [ "string", "null" ] }, "scheduledSourceId": { "type": [ "string", "null" ], "description": "The source the scheduled version was read from; its url is in /api/v1/sources" }, "minimumVersion": { "type": [ "string", "null" ], "description": "The latest MINIMUM_SPLICE_VERSION that is not cancelled, carries a version and has arrived. Upstream writes it as 0.7.x, so it is published at MINOR precision" }, "minimumPrecision": { "type": [ "string", "null" ] }, "minimumFrom": { "type": [ "string", "null" ], "description": "ISO date", "format": "date" }, "minimumEventId": { "type": [ "string", "null" ] }, "minimumSourceId": { "type": [ "string", "null" ], "description": "The source the minimum version was read from" } } }, "next": { "type": "object", "description": "The earliest NETWORK_UPGRADE that is not cancelled and whose date is still ahead", "properties": { "eventId": { "type": [ "string", "null" ] }, "version": { "type": [ "string", "null" ] }, "status": { "type": [ "string", "null" ], "examples": [ "CONFIRMED", "TENTATIVE" ] }, "from": { "type": [ "string", "null" ], "description": "ISO date", "format": "date" }, "title": { "type": [ "string", "null" ], "description": "The upstream title of the upgrade" }, "sourceId": { "type": [ "string", "null" ], "description": "The source the next upgrade was read from" } } }, "deployment": { "type": "object", "description": "What the network reports it is RUNNING, read from its deployment endpoint. Every field null where nothing reports one. Identifiers are published as strings.", "properties": { "version": { "type": [ "string", "null" ] }, "precision": { "type": [ "string", "null" ] }, "svVersion": { "type": [ "string", "null" ] }, "migrationId": { "type": [ "string", "null" ] }, "serialId": { "type": [ "string", "null" ] }, "chainIdSuffix": { "type": [ "string", "null" ] }, "successorVersion": { "type": [ "string", "null" ] }, "legacyVersion": { "type": [ "string", "null" ] }, "eventId": { "type": [ "string", "null" ] }, "sourceId": { "type": [ "string", "null" ], "description": "The source the deployment was read from" } } }, "roster": { "type": "object", "description": "How far the Super Validator roster agrees with the scheduled version. Agreement between two published sources is not proof of what runs.", "properties": { "nodes": { "type": "integer" }, "scheduledVersion": { "type": [ "string", "null" ] }, "onScheduled": { "type": "integer", "description": "Nodes whose roster entry reports the scheduled version" }, "unreported": { "type": "integer", "description": "Nodes with no version at all" }, "unavailable": { "type": "integer", "description": "Nodes upstream could not read at the last banked roster" }, "versions": { "type": "array", "items": { "type": "object", "properties": { "version": { "type": "string" }, "count": { "type": "integer" } } }, "description": "By count, then version, highest first" } } }, "superValidators": { "type": "array", "description": "Every Super Validator node with the version it reports and the hosts it publishes, ordered by name. Empty where none is reported.", "items": { "type": "object", "properties": { "name": { "type": [ "string", "null" ] }, "version": { "type": [ "string", "null" ] }, "scan": { "type": [ "string", "null" ], "description": "Scan url the node publishes" }, "sequencers": { "type": [ "array", "null" ], "description": "Sequencer url per physical synchronizer serial, highest serial first. A node lists two while an upgrade is in flight. Null where no source this environment reads reports them.", "items": { "type": "object", "properties": { "serial": { "type": "string", "examples": [ "5" ] }, "url": { "type": "string" } } } }, "eventId": { "type": [ "string", "null" ] }, "versionStatus": { "type": [ "string", "null" ], "description": "UNAVAILABLE when upstream could not read this node's version at the last banked roster; version is then the last one read. Null when it was read" } } } }, "publicationId": { "type": "string" }, "updatedAt": { "type": "string", "format": "date-time" } } }, "Event": { "type": "object", "properties": { "id": { "type": "string" }, "schemaVersion": { "type": "integer", "const": 1 }, "kind": { "type": [ "string", "null" ], "examples": [ "NETWORK_UPGRADE", "MINIMUM_SPLICE_VERSION", "NETWORK_DEPLOYMENT", "SV_NODE", "SOFTWARE_RELEASE" ] }, "network": { "type": [ "string", "null" ], "description": "Null for an event that belongs to no network, such as a software release", "examples": [ "MAINNET" ] }, "status": { "type": [ "string", "null" ], "examples": [ "CONFIRMED", "TENTATIVE", "CANCELLED" ] }, "withdrawn": { "type": "boolean", "description": "True when the record is no longer present upstream. A withdrawn event states nothing and is kept for history" }, "effective": { "type": "object", "properties": { "from": { "type": [ "string", "null" ], "description": "ISO date", "format": "date" }, "to": { "type": [ "string", "null" ] }, "precision": { "type": "string", "description": "DATE when a date was read, UNKNOWN otherwise", "enum": [ "DATE", "UNKNOWN" ] } } }, "version": { "type": "object", "properties": { "value": { "type": [ "string", "null" ] }, "precision": { "type": [ "string", "null" ] }, "change": { "type": [ "string", "null" ] } } }, "title": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "upstream": { "type": "object", "description": "The source's own public record identifier", "properties": { "type": { "type": [ "string", "null" ] }, "ref": { "type": [ "string", "null" ] } } }, "commit_sha": { "type": [ "string", "null" ] }, "commit_time": { "type": [ "string", "null" ], "description": "Time of the commit behind a release tag. Not when the version became available" }, "deployment": { "type": "object", "properties": { "svVersion": { "type": [ "string", "null" ] }, "migrationId": { "type": [ "string", "null" ] }, "serialId": { "type": [ "string", "null" ] }, "chainIdSuffix": { "type": [ "string", "null" ] }, "successorVersion": { "type": [ "string", "null" ] }, "legacyVersion": { "type": [ "string", "null" ] } } }, "scan_url": { "type": [ "string", "null" ] }, "sequencers": { "type": [ "array", "null" ], "description": "Sequencer url per physical synchronizer serial, on a Super Validator node event. Null on every other kind.", "items": { "type": "object", "properties": { "serial": { "type": "string" }, "url": { "type": "string" } } } }, "revision": { "type": "integer" }, "firstObservedAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastBankedAt": { "type": [ "string", "null" ], "format": "date-time" }, "provenance": { "type": "array", "description": "One record per source that described the event", "items": { "type": "object", "properties": { "sourceId": { "type": [ "string", "null" ] }, "observationId": { "type": [ "string", "null" ] }, "normalizer": { "type": [ "string", "null" ] } } } }, "versionStatus": { "type": [ "string", "null" ], "description": "For a Super Validator node: UNAVAILABLE when upstream could not read its version; the version is then the last one read" } } }, "Source": { "type": "object", "properties": { "id": { "type": "string", "examples": [ "canton-foundation-sv-operations-schedule" ] }, "publisher": { "type": "string" }, "url": { "type": "string", "description": "The exact endpoint that is polled" }, "authority": { "type": "string", "examples": [ "OFFICIAL", "OFFICIAL_PROJECT", "GOVERNANCE" ] }, "pollSeconds": { "type": "integer" }, "enabled": { "type": "boolean" }, "state": { "type": "string", "description": "Collector state. UNKNOWN where the index holds no row for the source", "examples": [ "IDLE", "HEALTHY", "DEGRADED", "UNKNOWN" ] }, "lastSuccessAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastPolledAt": { "type": [ "string", "null" ], "format": "date-time", "description": "The last poll of this source, whatever its outcome" }, "lastChangedAt": { "type": [ "string", "null" ], "format": "date-time", "description": "The last poll that banked a new body" } } }, "Planned": { "type": "object", "properties": { "eventId": { "type": "string", "description": "The published event; /api/v1/events/{id} carries its provenance" }, "network": { "type": [ "string", "null" ], "examples": [ "MAINNET", "TESTNET", "DEVNET" ] }, "kind": { "type": "string", "examples": [ "NETWORK_UPGRADE", "TOPOLOGY_FREEZE", "PROTOCOL_UPGRADE", "MINIMUM_SPLICE_VERSION" ] }, "status": { "type": "string", "examples": [ "CONFIRMED", "TENTATIVE", "CANCELLED" ] }, "from": { "type": "string", "format": "date", "description": "ISO date, no time zone upstream" }, "to": { "type": [ "string", "null" ], "description": "ISO date, when upstream gives an end that differs from the start" }, "version": { "type": [ "string", "null" ], "examples": [ "0.9.2", "0.9" ] }, "versionPrecision": { "type": [ "string", "null" ], "examples": [ "PATCH", "MINOR" ] }, "title": { "type": [ "string", "null" ], "description": "The upstream title" }, "description": { "type": [ "string", "null" ], "description": "The upstream description, unparsed" }, "sourceId": { "type": "string", "description": "The source it was read from; its url is in /api/v1/sources" }, "observationId": { "type": "string", "description": "The banked body it was last read from" }, "lastBankedAt": { "type": [ "string", "null" ], "description": "When that body was banked", "format": "date-time" } } }, "Change": { "type": "object", "properties": { "observedAt": { "type": "string", "format": "date-time", "description": "When the feed banked the body that showed the change" }, "eventId": { "type": "string" }, "revision": { "type": "integer", "description": "The revision of the event this change made" }, "network": { "type": [ "string", "null" ], "examples": [ "MAINNET", "TESTNET", "DEVNET" ] }, "kind": { "type": "string" }, "subject": { "type": "string", "description": "The upstream reference of the record: a schedule id, a Super Validator name, a release tag" }, "title": { "type": [ "string", "null" ], "description": "The record's title as it stands now, where it has one" }, "types": { "type": "array", "items": { "type": "string", "enum": [ "EVENT_CREATED", "EVENT_CONFIRMED", "EVENT_CANCELLED", "EVENT_RESCHEDULED", "EVENT_VERSION_ATTACHED", "EVENT_WITHDRAWN", "EVENT_CORRECTED" ] } }, "changes": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "old": { "type": [ "string", "null" ] }, "new": { "type": [ "string", "null" ] } } } }, "sourceId": { "type": "string", "description": "The source whose body made the change" }, "observationId": { "type": "string", "description": "That body" }, "afterGap": { "type": [ "object", "null" ], "description": "Set when the change's source had not been polled for longer than twice its interval, and never less than 15 minutes, before the poll that showed it: the change was first seen at `to` and happened somewhere after `from`. from is null when the source had never been polled before", "properties": { "from": { "type": [ "string", "null" ], "format": "date-time" }, "to": { "type": "string", "format": "date-time" } } } } }, "Price": { "type": "object", "properties": { "id": { "type": "string", "examples": [ "dso-mainnet", "kraken-cc-usd" ] }, "venue": { "type": "string", "description": "The network or the venue that states the price", "examples": [ "MainNet", "Kraken" ] }, "network": { "type": [ "string", "null" ], "description": "The network of a voted rate; null for a venue", "examples": [ "MAINNET", "TESTNET", "DEVNET" ] }, "kind": { "type": "string", "examples": [ "VOTED", "MARKET", "AGGREGATE" ] }, "pair": { "type": "string", "examples": [ "CC/USD", "CC/USDT" ] }, "quote": { "type": "string", "description": "The currency the price is in", "examples": [ "USD", "USDT" ] }, "url": { "type": "string", "description": "The exact endpoint that is read" }, "bid": { "type": [ "string", "null" ], "description": "Best bid, a decimal as text; null for a voted rate and an aggregate" }, "ask": { "type": [ "string", "null" ], "description": "Best ask, a decimal as text; null for a voted rate and an aggregate" }, "last": { "type": [ "string", "null" ], "description": "The last price, or the voted rate, a decimal as text" }, "sourceTime": { "type": [ "string", "null" ], "description": "The source's own time; what it is, sourceTimeIs says", "format": "date-time" }, "sourceTimeIs": { "type": [ "string", "null" ], "description": "ROUND_OPENS when the round opens, TICKER the venue's ticker, RESPONSE the venue's response rather than a trade, UPDATED the aggregator's last update; null where the source carries no time", "examples": [ "ROUND_OPENS", "TICKER", "RESPONSE", "UPDATED" ] }, "round": { "type": [ "string", "null" ], "description": "The mining round of a voted rate" }, "readAt": { "type": [ "string", "null" ], "description": "When the values were read", "format": "date-time" }, "lastAttemptAt": { "type": [ "string", "null" ], "description": "The newest read of this source, whatever its outcome", "format": "date-time" }, "lastAttemptStatus": { "type": [ "string", "null" ], "description": "Its outcome. When it is not OK the values are from readAt", "examples": [ "OK", "HTTP_ERROR", "TRANSPORT_ERROR", "UNPARSED" ] }, "lastAttemptDetail": { "type": [ "string", "null" ], "description": "Why it failed" } } } } } }