{ "openapi": "3.1.0", "info": { "title": "Event Canon", "version": "0.1.0", "description": "Bounded JetStream notifications. Rebuild from source APIs, not event history. Every protected operation also requires eventcanon.access in the explicitly selected organization." }, "security": [ { "bearer": [] } ], "paths": { "/v1/inspection": { "get": { "operationId": "inspectChannels", "summary": "Read authorized channels and selected-organization listeners; requires eventcanon.inspect", "parameters": [ { "name": "X-EventCanon-Organization", "in": "header", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 } } ], "responses": { "200": { "description": "200", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Inspection" } } } }, "400": { "description": "400", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "401", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "403", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "404", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "409", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "429", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "500", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "503", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request body rejected by HTTP framework." }, "415": { "description": "Request body rejected by HTTP framework." }, "422": { "description": "Request body rejected by HTTP framework." } } } }, "/v1/events": { "post": { "operationId": "publish", "summary": "Publish a minimal notification; requires eventcanon.publish", "parameters": [ { "name": "X-EventCanon-Organization", "in": "header", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^[!-~]{1,200}$" } } ], "responses": { "201": { "description": "201", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Published" } } } }, "400": { "description": "400", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "401", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "403", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "404", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "409", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "429", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "500", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "503", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request body rejected by HTTP framework." }, "415": { "description": "Request body rejected by HTTP framework." }, "422": { "description": "Request body rejected by HTTP framework." } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Publish" } } } } } }, "/v1/subscriptions": { "post": { "operationId": "subscribe", "summary": "Create a future-only resource subscription; requires eventcanon.subscribe", "parameters": [ { "name": "X-EventCanon-Organization", "in": "header", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^[!-~]{1,200}$" } } ], "responses": { "201": { "description": "201", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Subscription" } } } }, "400": { "description": "400", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "401", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "403", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "404", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "409", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "429", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "500", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "503", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request body rejected by HTTP framework." }, "415": { "description": "Request body rejected by HTTP framework." }, "422": { "description": "Request body rejected by HTTP framework." }, "200": { "description": "200", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Subscription" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Subscribe" } } } } } }, "/v1/subscriptions/{id}": { "get": { "operationId": "subscription", "summary": "Inspect owned subscription", "parameters": [ { "name": "X-EventCanon-Organization", "in": "header", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^esub_[0-9]{30}$" } } ], "responses": { "200": { "description": "200", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Subscription" } } } }, "400": { "description": "400", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "401", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "403", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "404", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "409", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "429", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "500", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "503", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request body rejected by HTTP framework." }, "415": { "description": "Request body rejected by HTTP framework." }, "422": { "description": "Request body rejected by HTTP framework." } } }, "delete": { "operationId": "deleteSubscription", "summary": "Delete owned subscription", "parameters": [ { "name": "X-EventCanon-Organization", "in": "header", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^esub_[0-9]{30}$" } } ], "responses": { "204": { "description": "204" }, "400": { "description": "400", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "401", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "403", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "404", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "409", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "429", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "500", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "503", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request body rejected by HTTP framework." }, "415": { "description": "Request body rejected by HTTP framework." }, "422": { "description": "Request body rejected by HTTP framework." } } } }, "/v1/subscriptions/{id}/reset": { "post": { "operationId": "reset", "summary": "Establish a new subscription epoch before reconciling authoritative state", "parameters": [ { "name": "X-EventCanon-Organization", "in": "header", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^esub_[0-9]{30}$" } } ], "responses": { "200": { "description": "200", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Subscription" } } } }, "400": { "description": "400", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "401", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "403", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "404", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "409", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "429", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "500", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "503", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request body rejected by HTTP framework." }, "415": { "description": "Request body rejected by HTTP framework." }, "422": { "description": "Request body rejected by HTTP framework." } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Epoch" } } } } } }, "/v1/subscriptions/{id}/reconciled": { "post": { "operationId": "reconciled", "summary": "Declare finite reconciliation complete for this epoch", "parameters": [ { "name": "X-EventCanon-Organization", "in": "header", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^esub_[0-9]{30}$" } } ], "responses": { "200": { "description": "200", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Subscription" } } } }, "400": { "description": "400", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "401", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "403", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "404", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "409", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "429", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "500", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "503", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request body rejected by HTTP framework." }, "415": { "description": "Request body rejected by HTTP framework." }, "422": { "description": "Request body rejected by HTTP framework." } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Epoch" } } } } } }, "/v1/subscriptions/{id}/events": { "get": { "operationId": "deliver", "summary": "Wait for a bounded notification batch; 409 requires reset and reconciliation", "parameters": [ { "name": "X-EventCanon-Organization", "in": "header", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^esub_[0-9]{30}$" } } ], "responses": { "200": { "description": "200", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Batch" } } } }, "400": { "description": "400", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "401", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "403", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "404", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "409", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "429", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "500", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "503", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request body rejected by HTTP framework." }, "415": { "description": "Request body rejected by HTTP framework." }, "422": { "description": "Request body rejected by HTTP framework." } } } }, "/v1/subscriptions/{id}/acks": { "post": { "operationId": "acknowledge", "summary": "Acknowledge a receipt after durable processing", "parameters": [ { "name": "X-EventCanon-Organization", "in": "header", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^esub_[0-9]{30}$" } } ], "responses": { "204": { "description": "204" }, "400": { "description": "400", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "401", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "403", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "404", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "409", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "429", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "500", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "503", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request body rejected by HTTP framework." }, "415": { "description": "Request body rejected by HTTP framework." }, "422": { "description": "Request body rejected by HTTP framework." } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Ack" } } } } } }, "/health/live": { "get": { "operationId": "live", "security": [], "responses": { "204": { "description": "204" } } } }, "/health/ready": { "get": { "operationId": "ready", "security": [], "responses": { "204": { "description": "204" }, "503": { "description": "503", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "500", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } } }, "components": { "securitySchemes": { "bearer": { "type": "http", "scheme": "bearer" } }, "schemas": { "Scope": { "type": "object", "additionalProperties": false, "properties": { "source": { "type": "string", "pattern": "^[a-z0-9-]{1,64}$" }, "owner_organization": { "type": "string", "minLength": 1, "maxLength": 200 }, "resource": { "type": "string", "pattern": "^[a-z]{1,12}_[0-9]{30}$" } }, "required": [ "source", "owner_organization", "resource" ] }, "Publish": { "type": "object", "additionalProperties": false, "properties": { "scope": { "$ref": "#/components/schemas/Scope" }, "event_type": { "type": "string", "pattern": "^[A-Za-z0-9.-]{1,128}$" }, "affected_resource": { "type": "string", "pattern": "^[a-z]{1,12}_[0-9]{30}$" }, "revision": { "type": "string", "pattern": "^[0-9]{1,20}$", "description": "Unsigned 64-bit revision, encoded as decimal text." } }, "required": [ "scope", "event_type", "affected_resource", "revision" ] }, "Published": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "pattern": "^evt_[0-9]{30}$" } }, "required": [ "id" ] }, "Subscribe": { "type": "object", "additionalProperties": false, "properties": { "scope": { "$ref": "#/components/schemas/Scope" } }, "required": [ "scope" ] }, "Subscription": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "pattern": "^esub_[0-9]{30}$" }, "epoch": { "type": "string", "pattern": "^[0-9a-f]{64}$" }, "reconciliation_required": { "type": "boolean" }, "reset_required": { "type": "boolean" }, "scope": { "$ref": "#/components/schemas/Scope" } }, "required": [ "id", "epoch", "reconciliation_required", "reset_required", "scope" ] }, "Epoch": { "type": "object", "additionalProperties": false, "properties": { "epoch": { "type": "string", "pattern": "^[0-9a-f]{64}$" } }, "required": [ "epoch" ] }, "Ack": { "type": "object", "additionalProperties": false, "properties": { "epoch": { "type": "string", "pattern": "^[0-9a-f]{64}$" }, "receipt": { "type": "string", "pattern": "^edlv_[0-9]{30}$" } }, "required": [ "epoch", "receipt" ] }, "Notification": { "type": "object", "additionalProperties": false, "properties": { "specversion": { "const": "1.0" }, "id": { "type": "string", "pattern": "^evt_[0-9]{30}$" }, "source": { "type": "string", "format": "uri-reference" }, "type": { "type": "string" }, "subject": { "type": "string", "pattern": "^[a-z]{1,12}_[0-9]{30}$" }, "time": { "type": "string", "format": "date-time" }, "datacontenttype": { "const": "application/json" }, "ownerissuer": { "type": "string" }, "ownerorg": { "type": "string" }, "actingorg": { "type": "string" }, "data": { "type": "object", "additionalProperties": false, "properties": { "resource": { "type": "string", "pattern": "^[a-z]{1,12}_[0-9]{30}$" }, "revision": { "type": "string" }, "publisher": { "type": "string" } }, "required": [ "resource", "revision", "publisher" ] } }, "required": [ "specversion", "id", "source", "type", "subject", "time", "datacontenttype", "ownerissuer", "ownerorg", "actingorg", "data" ] }, "Batch": { "type": "object", "additionalProperties": false, "properties": { "epoch": { "type": "string", "pattern": "^[0-9a-f]{64}$" }, "reconciliation_required": { "type": "boolean" }, "deliveries": { "type": "array", "maxItems": 16, "items": { "type": "object", "additionalProperties": false, "properties": { "receipt": { "type": "string", "pattern": "^edlv_[0-9]{30}$" }, "event": { "$ref": "#/components/schemas/Notification" } }, "required": [ "receipt", "event" ] } } }, "required": [ "epoch", "reconciliation_required", "deliveries" ] }, "Error": { "type": "object", "additionalProperties": false, "properties": { "error": { "type": "string" } }, "required": [ "error" ] }, "Listener": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "pattern": "^esub_[0-9]{30}$" }, "subject": { "type": "string" }, "health": { "enum": [ "ready", "reconciling", "reset_required", "unavailable" ] }, "receiving": { "type": "boolean" }, "last_activity": { "type": "string", "format": "date-time" }, "pending": { "type": [ "string", "null" ], "pattern": "^[0-9]+$", "description": "Exact broker count as decimal text; null means unavailable." }, "unacknowledged": { "type": [ "string", "null" ], "pattern": "^[0-9]+$", "description": "Exact broker count as decimal text; null means unavailable." }, "redelivered": { "type": [ "string", "null" ], "pattern": "^[0-9]+$", "description": "Exact broker count as decimal text; null means unavailable." } }, "required": [ "id", "subject", "health", "receiving", "last_activity", "pending", "unacknowledged", "redelivered" ] }, "Channel": { "type": "object", "additionalProperties": false, "properties": { "scope": { "$ref": "#/components/schemas/Scope" }, "first_seen": { "type": "string", "format": "date-time" }, "last_published": { "type": [ "string", "null" ], "format": "date-time" }, "listeners": { "type": "array", "items": { "$ref": "#/components/schemas/Listener" } } }, "required": [ "scope", "first_seen", "last_published", "listeners" ] }, "Inspection": { "type": "object", "additionalProperties": false, "properties": { "organization": { "type": "string" }, "observed_at": { "type": "string", "format": "date-time" }, "retention_seconds": { "type": "integer" }, "channels": { "type": "array", "items": { "$ref": "#/components/schemas/Channel" } } }, "required": [ "organization", "observed_at", "retention_seconds", "channels" ] } } } }