{ "openapi": "3.1.0", "info": { "title": "ecbyts shared-model Edge API", "version": "1.0.0", "description": "Model data API. Obtain the project endpoint from your deployment administrator. POST requires a user access token. Governed share codes undergo caller authorization, recipient/owner checks, expiration and revocation. An encoded inline model instead contains caller-supplied data: it is processed without a stored-share lookup and has no server-side revocation guarantee. Neither form is a login credential. Scientific call/evaluate operations run in the client tier and are not offered by this endpoint. Always inspect ok: application errors can use HTTP 200. This source contract does not establish deployed-version parity." }, "servers": [ { "url": "https://{projectRef}.supabase.co/functions/v1", "variables": { "projectRef": { "default": "your-project-ref", "description": "Project reference supplied by the deployment administrator." } } } ], "paths": { "/ecbt-api/snapshot": { "post": { "operationId": "readAuthorizedSnapshot", "summary": "Read an exact authorized immutable online snapshot", "description": "Requires a user token even in legacy-open mode. Checks purpose, recipient epoch and exact grant through the snapshot RPC. Returns only the stored online slice; no model fallback or decryption. Requires the snapshot migrations and matching Edge deployment. Generated value/table/sum SDK facades do not yet wrap this separate route.", "security": [{ "UserBearer": [] }], "requestBody": { "required": true, "description": "UTF-8 JSON body limited to 8192 bytes and a five-second read deadline.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": ["snapshotId", "purpose", "epoch"], "properties": { "snapshotId": { "type": "string", "pattern": "^[0-9a-fA-F]{8}-([0-9a-fA-F]{4}-){3}[0-9a-fA-F]{12}$" }, "purpose": { "type": "string", "minLength": 3, "maxLength": 1000, "description": "Exact stored purpose; at least three non-padding characters." }, "epoch": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 } } } } } }, "responses": { "200": { "description": "Authorized stored payload only, with a 1 MiB upstream byte limit before JSON parsing. Does not prove upstream minimization or cryptographic correctness.", "content": { "application/json": { "schema": { "type": "object", "required": ["ok", "kind", "data"], "properties": { "ok": { "const": true }, "kind": { "const": "snapshot" }, "data": { "type": ["object", "array"] } } } } } }, "400": { "description": "Invalid snapshot binding or request shape." }, "405": { "description": "Snapshot route only supports POST and OPTIONS." }, "408": { "description": "Snapshot request body read deadline exceeded." }, "413": { "description": "Snapshot request body exceeds 8192 bytes." }, "401": { "$ref": "#/components/responses/AuthenticationRequired" }, "403": { "description": "Snapshot access denied; no model fallback." }, "429": { "description": "Rate limit exceeded." }, "503": { "description": "Missing configuration, unavailable RPC or invalid/oversized upstream response." } } } }, "/ecbt-api": { "get": { "operationId": "getEcbtApiHealth", "summary": "Inspect public health and supported operations", "security": [], "responses": { "200": { "description": "Public health response. GET does not read a model.", "content": { "application/json": { "schema": { "type": "object", "required": ["ok", "kind", "functions"], "properties": { "ok": { "const": true }, "kind": { "const": "health" }, "functions": { "type": "array", "items": { "enum": ["value", "table", "sum"] } }, "authMode": { "enum": ["enforce", "legacy-open"] } } } } } } } }, "post": { "operationId": "querySharedEcbtModel", "summary": "Read or aggregate an authorized model", "description": "Current rate limit: 30 requests per minute per client IP. Authentication occurs before this limiter. The operator emergency legacy-open mode is outside this integration contract. No write, reshare or encrypted-download operation is exposed. sum currently performs addition only; client-side avg/min/max/percentile options do not apply here.", "security": [{ "UserBearer": [] }], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["fn", "args"], "properties": { "fn": { "enum": ["value", "table", "sum"] }, "args": { "type": "array", "minItems": 1, "maxItems": 3, "items": { "type": "string" }, "description": "Resource key followed by the operation arguments. For sum, the optional third argument can only be sum." } }, "oneOf": [ { "properties": { "fn": { "const": "table" }, "args": { "maxItems": 1 } } }, { "properties": { "fn": { "const": "value" }, "args": { "minItems": 2, "maxItems": 2 } } }, { "properties": { "fn": { "const": "sum" }, "args": { "minItems": 2, "prefixItems": [ { "type": "string" }, { "type": "string" }, { "const": "sum" } ] } } } ], "additionalProperties": false }, "examples": { "table": { "value": { "fn": "table", "args": ["SHARE_CODE_FROM_OWNER"] } }, "value": { "value": { "fn": "value", "args": ["SHARE_CODE_FROM_OWNER", "parameters.depth"] } }, "sum": { "value": { "fn": "sum", "args": ["SHARE_CODE_FROM_OWNER", "parameters.depth"] } } } } } }, "responses": { "200": { "description": "Result or application error. value reads the first element; table returns header, rows and matrix; sum returns a number. Inspect ok even when HTTP succeeds.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/Result" }, { "$ref": "#/components/schemas/Error" } ] } } } }, "400": { "description": "Unsupported aggregation: the Edge sum operation supports addition only. Other client-tier operations are rejected rather than silently returning a sum.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "$ref": "#/components/responses/AuthenticationRequired" }, "403": { "description": "Share inaccessible, expired or revoked, or caller is not an authorized owner/recipient.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Authentication service unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } } }, "components": { "securitySchemes": { "UserBearer": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "User access token. Never distribute service-role or management credentials to consumers." } }, "schemas": { "Result": { "oneOf": [ { "$ref": "#/components/schemas/ValueResult" }, { "$ref": "#/components/schemas/TableResult" }, { "$ref": "#/components/schemas/ScalarResult" } ] }, "ValueResult": { "type": "object", "required": ["ok", "kind", "data"], "properties": { "ok": { "const": true }, "kind": { "const": "value" }, "data": { "type": "object", "required": ["field", "found"], "properties": { "field": { "type": "string" }, "found": { "type": "boolean" }, "value": { "description": "Resolved field value; omitted when found is false. Explicit null is a present value." } } } } }, "TableResult": { "type": "object", "required": ["ok", "kind", "data"], "properties": { "ok": { "const": true }, "kind": { "const": "table" }, "data": { "type": "object", "required": ["header", "rows", "matrix"], "properties": { "header": { "type": "array", "items": { "type": "string" } }, "rows": { "type": "array", "items": { "$ref": "#/components/schemas/TableRow" } }, "matrix": { "type": "array", "items": { "$ref": "#/components/schemas/TableRow" }, "description": "Header followed by data rows." } } } } }, "TableRow": { "type": "array", "items": {}, "description": "JSON cells; missing element properties serialize as null." }, "ScalarResult": { "type": "object", "required": ["ok", "kind", "data"], "properties": { "ok": { "const": true }, "kind": { "const": "scalar" }, "data": { "type": "number" } } }, "Error": { "type": "object", "required": ["ok", "error"], "properties": { "ok": { "const": false }, "error": { "type": "object", "required": ["code"], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } }, "responses": { "AuthenticationRequired": { "description": "Missing, invalid or expired user token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }