{ "openapi": "3.1.0", "info": { "title": "Superb API", "version": "1.0.0", "description": "Attributed lexical data, contextual editorial previews, versioned datasets and source-grounded argument review. Review distinguishes local text checks from optional AI interpretation; neither performs external verification." }, "servers": [ { "url": "/" } ], "paths": { "/api/lexicon": { "get": { "operationId": "getLexiconRelease", "summary": "Source attribution and release statistics", "responses": { "200": { "description": "Release manifest", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Release" } } } }, "503": { "description": "Service temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "head": { "operationId": "getLexiconReleaseHeaders", "summary": "Headers and status without a response body", "parameters": [], "responses": { "200": { "description": "Release manifest" }, "503": { "description": "Service temporarily unavailable" } } } }, "/api/lexicon/words": { "get": { "operationId": "searchWords", "summary": "Find up to 20 words by prefix", "parameters": [ { "name": "prefix", "in": "query", "required": true, "description": "At least two characters; case-insensitive.", "schema": { "type": "string", "maxLength": 100 } } ], "responses": { "200": { "description": "Prefix matches", "content": { "application/json": { "schema": { "type": "object", "properties": { "prefix": { "type": "string" }, "words": { "type": "array", "items": { "type": "string" } } }, "required": [ "prefix", "words" ] } } } }, "400": { "description": "Malformed request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Word or meaning not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Service temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "head": { "operationId": "searchWordsHeaders", "summary": "Headers and status without a response body", "parameters": [ { "name": "prefix", "in": "query", "required": true, "description": "At least two characters; case-insensitive.", "schema": { "type": "string", "maxLength": 100 } } ], "responses": { "200": { "description": "Prefix matches" }, "400": { "description": "Malformed request" }, "404": { "description": "Word or meaning not found" }, "503": { "description": "Service temporarily unavailable" } } } }, "/api/lexicon/words/{word}": { "get": { "operationId": "getWord", "summary": "Definitions and meaning-specific relationships", "parameters": [ { "name": "word", "in": "path", "required": true, "description": "URL-encoded English word or phrase.", "schema": { "type": "string", "maxLength": 100 } }, { "name": "sense", "in": "query", "required": false, "description": "Optional exact meaning ID belonging to this word.", "schema": { "type": "string", "maxLength": 100 } } ], "responses": { "200": { "description": "Attributed word record", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Word" } } } }, "400": { "description": "Malformed request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Word or meaning not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Service temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "head": { "operationId": "getWordHeaders", "summary": "Headers and status without a response body", "parameters": [ { "name": "word", "in": "path", "required": true, "description": "URL-encoded English word or phrase.", "schema": { "type": "string", "maxLength": 100 } }, { "name": "sense", "in": "query", "required": false, "description": "Optional exact meaning ID belonging to this word.", "schema": { "type": "string", "maxLength": 100 } } ], "responses": { "200": { "description": "Attributed word record" }, "400": { "description": "Malformed request" }, "404": { "description": "Word or meaning not found" }, "503": { "description": "Service temporarily unavailable" } } } }, "/api/usage/scenes": { "get": { "operationId": "getUsageScenes", "summary": "Public editorial scenes", "parameters": [ { "name": "version", "in": "query", "schema": { "type": "string" }, "description": "Exact current version; unavailable releases return 409." }, { "name": "channel", "in": "query", "schema": { "enum": [ "caption", "message", "claim", "community" ] } } ], "responses": { "200": { "description": "Original examples and provenance", "content": { "application/json": { "schema": { "type": "object", "required": [ "release", "source", "status", "count", "records" ], "properties": { "release": { "type": "string" }, "status": { "const": "editorial-preview" }, "source": { "$ref": "#/components/schemas/UsageSource" }, "count": { "type": "integer" }, "records": { "type": "array", "items": { "$ref": "#/components/schemas/UsageScene" } } } } } } }, "400": { "description": "Unknown channel" }, "409": { "description": "Requested release unavailable" }, "503": { "description": "Release assets unavailable" } } } }, "/api/usage/contrasts": { "get": { "operationId": "getUsageContrasts", "summary": "Public editorial contrasts", "parameters": [ { "name": "version", "in": "query", "schema": { "type": "string" }, "description": "Exact current version; unavailable releases return 409." }, { "name": "channel", "in": "query", "schema": { "enum": [ "caption", "message", "claim", "community" ] } } ], "responses": { "200": { "description": "Original examples and provenance", "content": { "application/json": { "schema": { "type": "object", "required": [ "release", "source", "status", "count", "records" ], "properties": { "release": { "type": "string" }, "status": { "const": "editorial-preview" }, "source": { "$ref": "#/components/schemas/UsageSource" }, "count": { "type": "integer" }, "records": { "type": "array", "items": { "$ref": "#/components/schemas/UsageContrast" } } } } } } }, "400": { "description": "Unknown channel" }, "409": { "description": "Requested release unavailable" }, "503": { "description": "Release assets unavailable" } } } }, "/api/usage": { "get": { "operationId": "getUsageRelease", "summary": "Coverage, limitations, source and SHA-256 file hashes", "parameters": [ { "name": "version", "in": "query", "schema": { "type": "string" }, "description": "Exact current version; unavailable releases return 409." } ], "responses": { "200": { "description": "Release manifest" }, "409": { "description": "Requested release unavailable" }, "503": { "description": "Release assets unavailable" } } } }, "/api/usage/scenes/{id}": { "get": { "operationId": "getUsageScene", "summary": "One situation with three contrasting versions", "parameters": [ { "name": "version", "in": "query", "schema": { "type": "string" }, "description": "Exact current version; unavailable releases return 409." }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[a-z]+(?:-[a-z]+)*$" } } ], "responses": { "200": { "description": "Situation and provenance", "content": { "application/json": { "schema": { "type": "object", "properties": { "release": { "type": "string" }, "source": { "$ref": "#/components/schemas/UsageSource" }, "scene": { "$ref": "#/components/schemas/UsageScene" } } } } } }, "400": { "description": "Invalid ID" }, "404": { "description": "Unknown situation" }, "409": { "description": "Requested release unavailable" }, "503": { "description": "Release assets unavailable" } } } }, "/api/datasets": { "get": { "operationId": "listDatasets", "summary": "Discover public and protected dataset routes", "parameters": [], "responses": { "200": { "description": "Release data with source terms", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DatasetCatalog" } } } }, "400": { "description": "Malformed identifier/cursor or page outside release", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid or expired API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "API key lacks dataset entitlement", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unknown dataset, route or record", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Read-only endpoint", "content": { "text/plain": { "schema": { "type": "string" } } } }, "409": { "description": "Version or cursor no longer matches current release", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Missing storage, unavailable/revoked release or file integrity failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "Public datasets require no key. observed-language requires a scoped bearer key and a reviewed release. Public data is cached for one hour; private responses are no-store. Only current releases are served.", "security": [ {}, { "DatasetKey": [] } ] }, "head": { "operationId": "listDatasetsHeaders", "summary": "Discover public and protected dataset routes (headers only)", "parameters": [], "responses": { "200": { "description": "Release data with source terms", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DatasetCatalog" } } } }, "400": { "description": "Malformed identifier/cursor or page outside release", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid or expired API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "API key lacks dataset entitlement", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unknown dataset, route or record", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Read-only endpoint", "content": { "text/plain": { "schema": { "type": "string" } } } }, "409": { "description": "Version or cursor no longer matches current release", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Missing storage, unavailable/revoked release or file integrity failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "Public datasets require no key. observed-language requires a scoped bearer key and a reviewed release. Public data is cached for one hour; private responses are no-store. Only current releases are served.", "security": [ {}, { "DatasetKey": [] } ] }, "options": { "operationId": "listDatasetsPreflight", "parameters": [], "responses": { "204": { "description": "CORS permits GET, HEAD and Authorization" } } } }, "/api/datasets/{dataset}": { "get": { "operationId": "getDatasetManifest", "summary": "Inspect a versioned release manifest", "parameters": [ { "name": "dataset", "in": "path", "required": true, "schema": { "enum": [ "literary-context", "association-practice", "observed-language" ] } }, { "name": "version", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "description": "Pins the current release; unavailable versions return409. Local release archives do not imply historical API hosting." } ], "responses": { "200": { "description": "Release data with source terms", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DatasetManifest" } } } }, "400": { "description": "Malformed identifier/cursor or page outside release", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid or expired API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "API key lacks dataset entitlement", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unknown dataset, route or record", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Read-only endpoint", "content": { "text/plain": { "schema": { "type": "string" } } } }, "409": { "description": "Version or cursor no longer matches current release", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Missing storage, unavailable/revoked release or file integrity failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "Public datasets require no key. observed-language requires a scoped bearer key and a reviewed release. Public data is cached for one hour; private responses are no-store. Only current releases are served.", "security": [ {}, { "DatasetKey": [] } ] }, "head": { "operationId": "getDatasetManifestHeaders", "summary": "Inspect a versioned release manifest (headers only)", "parameters": [ { "name": "dataset", "in": "path", "required": true, "schema": { "enum": [ "literary-context", "association-practice", "observed-language" ] } }, { "name": "version", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "description": "Pins the current release; unavailable versions return409. Local release archives do not imply historical API hosting." } ], "responses": { "200": { "description": "Release data with source terms", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DatasetManifest" } } } }, "400": { "description": "Malformed identifier/cursor or page outside release", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid or expired API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "API key lacks dataset entitlement", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unknown dataset, route or record", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Read-only endpoint", "content": { "text/plain": { "schema": { "type": "string" } } } }, "409": { "description": "Version or cursor no longer matches current release", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Missing storage, unavailable/revoked release or file integrity failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "Public datasets require no key. observed-language requires a scoped bearer key and a reviewed release. Public data is cached for one hour; private responses are no-store. Only current releases are served.", "security": [ {}, { "DatasetKey": [] } ] }, "options": { "operationId": "getDatasetManifestPreflight", "parameters": [ { "name": "dataset", "in": "path", "required": true, "schema": { "enum": [ "literary-context", "association-practice", "observed-language" ] } } ], "responses": { "204": { "description": "CORS permits GET, HEAD and Authorization" } } } }, "/api/datasets/{dataset}/records": { "get": { "operationId": "getDatasetPage", "summary": "Read a page of at most 100 records", "parameters": [ { "name": "dataset", "in": "path", "required": true, "schema": { "enum": [ "literary-context", "association-practice", "observed-language" ] } }, { "name": "version", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "description": "Pins the current release; unavailable versions return409. Local release archives do not imply historical API hosting." }, { "name": "cursor", "in": "query", "schema": { "type": "string" }, "description": "Use nextCursor unchanged; omit for the first page. Cursor includes release identity." } ], "responses": { "200": { "description": "Release data with source terms", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DatasetPage" } } } }, "400": { "description": "Malformed identifier/cursor or page outside release", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid or expired API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "API key lacks dataset entitlement", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unknown dataset, route or record", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Read-only endpoint", "content": { "text/plain": { "schema": { "type": "string" } } } }, "409": { "description": "Version or cursor no longer matches current release", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Missing storage, unavailable/revoked release or file integrity failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "Public datasets require no key. observed-language requires a scoped bearer key and a reviewed release. Public data is cached for one hour; private responses are no-store. Only current releases are served.", "security": [ {}, { "DatasetKey": [] } ] }, "head": { "operationId": "getDatasetPageHeaders", "summary": "Read page headers without a response body", "parameters": [ { "name": "dataset", "in": "path", "required": true, "schema": { "enum": [ "literary-context", "association-practice", "observed-language" ] } }, { "name": "version", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "description": "Pins the current release; unavailable versions return409. Local release archives do not imply historical API hosting." }, { "name": "cursor", "in": "query", "schema": { "type": "string" }, "description": "Use nextCursor unchanged; omit for the first page. Cursor includes release identity." } ], "responses": { "200": { "description": "Release data with source terms", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DatasetPage" } } } }, "400": { "description": "Malformed identifier/cursor or page outside release", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid or expired API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "API key lacks dataset entitlement", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unknown dataset, route or record", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Read-only endpoint", "content": { "text/plain": { "schema": { "type": "string" } } } }, "409": { "description": "Version or cursor no longer matches current release", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Missing storage, unavailable/revoked release or file integrity failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "Public datasets require no key. observed-language requires a scoped bearer key and a reviewed release. Public data is cached for one hour; private responses are no-store. Only current releases are served.", "security": [ {}, { "DatasetKey": [] } ] }, "options": { "operationId": "getDatasetPagePreflight", "parameters": [ { "name": "dataset", "in": "path", "required": true, "schema": { "enum": [ "literary-context", "association-practice", "observed-language" ] } } ], "responses": { "204": { "description": "CORS permits GET, HEAD and Authorization" } } } }, "/api/datasets/{dataset}/records/{id}": { "get": { "operationId": "getDatasetRecord", "summary": "Read one stable record ID", "parameters": [ { "name": "dataset", "in": "path", "required": true, "schema": { "enum": [ "literary-context", "association-practice", "observed-language" ] } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 250 } }, { "name": "version", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "description": "Pins the current release; unavailable versions return409. Local release archives do not imply historical API hosting." } ], "responses": { "200": { "description": "Release data with source terms", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DatasetRecord" } } } }, "400": { "description": "Malformed identifier/cursor or page outside release", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid or expired API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "API key lacks dataset entitlement", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unknown dataset, route or record", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Read-only endpoint", "content": { "text/plain": { "schema": { "type": "string" } } } }, "409": { "description": "Version or cursor no longer matches current release", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Missing storage, unavailable/revoked release or file integrity failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "Public datasets require no key. observed-language requires a scoped bearer key and a reviewed release. Public data is cached for one hour; private responses are no-store. Only current releases are served.", "security": [ {}, { "DatasetKey": [] } ] }, "head": { "operationId": "getDatasetRecordHeaders", "summary": "Read one stable record ID (headers only)", "parameters": [ { "name": "dataset", "in": "path", "required": true, "schema": { "enum": [ "literary-context", "association-practice", "observed-language" ] } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 250 } }, { "name": "version", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "description": "Pins the current release; unavailable versions return409. Local release archives do not imply historical API hosting." } ], "responses": { "200": { "description": "Release data with source terms", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DatasetRecord" } } } }, "400": { "description": "Malformed identifier/cursor or page outside release", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid or expired API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "API key lacks dataset entitlement", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unknown dataset, route or record", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Read-only endpoint", "content": { "text/plain": { "schema": { "type": "string" } } } }, "409": { "description": "Version or cursor no longer matches current release", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Missing storage, unavailable/revoked release or file integrity failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "Public datasets require no key. observed-language requires a scoped bearer key and a reviewed release. Public data is cached for one hour; private responses are no-store. Only current releases are served.", "security": [ {}, { "DatasetKey": [] } ] }, "options": { "operationId": "getDatasetRecordPreflight", "parameters": [ { "name": "dataset", "in": "path", "required": true, "schema": { "enum": [ "literary-context", "association-practice", "observed-language" ] } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 250 } } ], "responses": { "204": { "description": "CORS permits GET, HEAD and Authorization" } } } }, "/api/datasets/{dataset}/download": { "get": { "operationId": "downloadDataset", "summary": "Download checksummed JSONL", "parameters": [ { "name": "dataset", "in": "path", "required": true, "schema": { "enum": [ "literary-context", "association-practice", "observed-language" ] } }, { "name": "version", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "description": "Pins the current release; unavailable versions return409. Local release archives do not imply historical API hosting." } ], "responses": { "200": { "description": "Release data with source terms", "content": { "application/x-ndjson": { "schema": { "type": "string" } } } }, "400": { "description": "Malformed identifier/cursor or page outside release", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid or expired API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "API key lacks dataset entitlement", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unknown dataset, route or record", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Read-only endpoint", "content": { "text/plain": { "schema": { "type": "string" } } } }, "409": { "description": "Version or cursor no longer matches current release", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Missing storage, unavailable/revoked release or file integrity failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "Public datasets require no key. observed-language requires a scoped bearer key and a reviewed release. Public data is cached for one hour; private responses are no-store. Only current releases are served.", "security": [ {}, { "DatasetKey": [] } ] }, "head": { "operationId": "downloadDatasetHeaders", "summary": "Download checksummed JSONL (headers only)", "parameters": [ { "name": "dataset", "in": "path", "required": true, "schema": { "enum": [ "literary-context", "association-practice", "observed-language" ] } }, { "name": "version", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "description": "Pins the current release; unavailable versions return409. Local release archives do not imply historical API hosting." } ], "responses": { "200": { "description": "Release data with source terms", "content": { "application/x-ndjson": { "schema": { "type": "string" } } } }, "400": { "description": "Malformed identifier/cursor or page outside release", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid or expired API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "API key lacks dataset entitlement", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unknown dataset, route or record", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Read-only endpoint", "content": { "text/plain": { "schema": { "type": "string" } } } }, "409": { "description": "Version or cursor no longer matches current release", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Missing storage, unavailable/revoked release or file integrity failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "Public datasets require no key. observed-language requires a scoped bearer key and a reviewed release. Public data is cached for one hour; private responses are no-store. Only current releases are served.", "security": [ {}, { "DatasetKey": [] } ] }, "options": { "operationId": "downloadDatasetPreflight", "parameters": [ { "name": "dataset", "in": "path", "required": true, "schema": { "enum": [ "literary-context", "association-practice", "observed-language" ] } } ], "responses": { "204": { "description": "CORS permits GET, HEAD and Authorization" } } } }, "/api/argument": { "get": { "operationId": "getArgumentCapabilities", "summary": "Review capabilities, bounds and editorial meaning notes", "responses": { "200": { "description": "Current service capabilities; not a guarantee of provider availability", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ArgumentCapabilities" } } } } } } }, "/api/argument/review": { "post": { "operationId": "reviewArgument", "summary": "Compare an argument with supplied source text", "description": "Default local mode matches wording only. Cloud mode requires consent and a scoped key. Source matching is not factual verification. Maximum body size 450000 bytes; all responses use no-store.", "security": [ {}, { "ArgumentKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ArgumentInput" } } } }, "responses": { "200": { "description": "Traceable text checks or model-assisted review", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/TextCheckReview" }, { "$ref": "#/components/schemas/ContextualReview" } ] } } } }, "400": { "description": "Invalid input or missing consent", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Key missing, invalid or expired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Key lacks argument-review entitlement", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request body too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "Unsupported content type", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Burst rate limit reached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Provider failure or invalid review", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Service unavailable or not configured", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/argument/transcribe": { "post": { "operationId": "transcribeArgumentSource", "summary": "Transcribe supplied audio for user review", "description": "Speech only; no visual analysis. Maximum multipart request size 20 MiB. MP3, MP4, M4A, WAV, WebM, MPEG, MPGA, OGG or FLAC. The app permits files up to 19 MiB and requires transcript review before use.", "security": [ { "ArgumentKey": [] } ], "parameters": [ { "in": "header", "name": "X-Superb-Consent", "required": true, "schema": { "const": "send-to-provider" } } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "file": { "type": "string", "format": "binary" } }, "required": [ "file" ] } } } }, "responses": { "200": { "description": "Editable transcript with explicit limits", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Transcription" } } } }, "400": { "description": "Invalid input or missing consent", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Key missing, invalid or expired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Key lacks argument-review entitlement", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request body too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "Unsupported content type", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Transcript empty or too long", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Burst rate limit reached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Provider failure or invalid review", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Service unavailable or not configured", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/contrasts/{id}/consensus": { "get": { "operationId": "getConsensus", "summary": "Read a Solana finalized-commitment consensus account; protocol status may still be challengeable", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{64}$" } }, { "name": "revision", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1 } } ], "responses": { "200": { "description": "Committed counts, roots, registered rule/evaluator and protocol state", "content": { "application/json": { "schema": { "type": "object" } } } }, "404": { "description": "No committed contrast or revision" }, "503": { "description": "Solana RPC unavailable or unconfigured" } } } }, "/v1/predict/consensus": { "post": { "operationId": "predictConsensus", "summary": "Return an observed finalized consensus or a provisional estimate for a committed contrast", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "contrastId" ], "properties": { "contrastId": { "type": "string", "pattern": "^[0-9a-f]{64}$" }, "revision": { "type": "integer", "minimum": 1 } } } } } }, "responses": { "200": { "description": "Observed or estimated protocol outcome; not linguistic truth", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/v1/predict/sense": { "post": { "operationId": "predictSense", "summary": "Deterministic contextual sense lookup for a passage and target", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "text", "target" ], "properties": { "text": { "type": "string" }, "target": { "type": "string" }, "release": { "type": "string" } } } } } }, "responses": { "200": { "description": "Contextual sense or explicit abstention", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Resolution" } } } } } } }, "/v1/verify/consensus": { "post": { "operationId": "verifyConsensus", "summary": "Verify finalized chain state and optionally replay the committed artifact", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "contrastId" ], "properties": { "contrastId": { "type": "string", "pattern": "^[0-9a-f]{64}$" }, "revision": { "type": "integer", "minimum": 1 }, "artifact": { "type": "object" } } } } } }, "responses": { "200": { "description": "Separate chainVerified and replayVerified flags; artifact required for verified=true", "content": { "application/json": { "schema": { "type": "object" } } } }, "409": { "description": "Consensus is not protocol finalized" }, "413": { "description": "Artifact exceeds 1 MB" } } } }, "/v1/releases/{id}/commitment": { "get": { "operationId": "getReleaseCommitment", "summary": "Read a semantic release commitment and its seed consensus from Solana", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{64}$" } } ], "responses": { "200": { "description": "Release roots, lineage and protocol state", "content": { "application/json": { "schema": { "type": "object" } } } }, "404": { "description": "Release commitment not found" } } } }, "/v1/verify/release": { "post": { "operationId": "verifyRelease", "summary": "Replay a finalized semantic release and every consensus member", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "releaseId" ], "properties": { "releaseId": { "type": "string", "pattern": "^[0-9a-f]{64}$" }, "artifact": { "type": "object" } } } } } }, "responses": { "200": { "description": "Separate chainVerified and replayVerified flags", "content": { "application/json": { "schema": { "type": "object" } } } }, "409": { "description": "Release is not protocol finalized" }, "413": { "description": "Artifact exceeds 1 MB or release has more than 32 members; use offline verifier" } } } }, "/v1/resolve": { "post": { "summary": "Resolve an explicit contextual expression", "responses": { "200": { "description": "Success; every v1 response includes x-request-id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Resolution" } } } }, "400": { "description": "Invalid input" }, "401": { "description": "Authentication required or expired" }, "403": { "description": "Scope or origin rejected" }, "409": { "description": "Conflict or expired assignment" }, "410": { "description": "Withdrawn release" }, "429": { "description": "Rate allowance exceeded" }, "503": { "description": "Required capability is not configured" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResolveInput" } } } } } }, "/v1/compare": { "post": { "summary": "Compare contextual sense candidates", "responses": { "200": { "description": "Success; every v1 response includes x-request-id.", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Invalid input" }, "401": { "description": "Authentication required or expired" }, "403": { "description": "Scope or origin rejected" }, "409": { "description": "Conflict or expired assignment" }, "410": { "description": "Withdrawn release" }, "429": { "description": "Rate allowance exceeded" }, "503": { "description": "Required capability is not configured" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "a": { "type": "string", "maxLength": 12000 }, "b": { "type": "string", "maxLength": 12000 }, "mode": { "enum": [ "deterministic", "jev" ] }, "consent": { "type": "boolean" }, "release": { "type": [ "string", "integer" ] }, "target": { "type": "string" } }, "required": [ "a", "b", "target" ] } } } } } }, "/v1/illuminate": { "post": { "summary": "Resolve occurrences with candidate mismatches and residuals", "responses": { "200": { "description": "Success; every v1 response includes x-request-id.", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Invalid input" }, "401": { "description": "Authentication required or expired" }, "403": { "description": "Scope or origin rejected" }, "409": { "description": "Conflict or expired assignment" }, "410": { "description": "Withdrawn release" }, "429": { "description": "Rate allowance exceeded" }, "503": { "description": "Required capability is not configured" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "text": { "type": "string" }, "targets": { "type": "array", "items": { "type": "string" } }, "mode": { "type": "string", "enum": [ "deterministic", "jev", "consensus" ], "default": "deterministic" }, "release": { "type": [ "string", "integer" ] } }, "required": [ "text", "targets" ] } } } } } }, "/v1/arguments/analyze": { "post": { "summary": "Extract inspectable claims and relations", "responses": { "200": { "description": "Success; every v1 response includes x-request-id.", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Invalid input" }, "401": { "description": "Authentication required or expired" }, "403": { "description": "Scope or origin rejected" }, "409": { "description": "Conflict or expired assignment" }, "410": { "description": "Withdrawn release" }, "429": { "description": "Rate allowance exceeded" }, "503": { "description": "Required capability is not configured" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyzeArgumentInput" } } } } } }, "/v1/claims/compare": { "post": { "summary": "Compare propositions with abstention", "responses": { "200": { "description": "Success; every v1 response includes x-request-id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClaimComparison" } } } }, "400": { "description": "Invalid input" }, "401": { "description": "Authentication required or expired" }, "403": { "description": "Scope or origin rejected" }, "409": { "description": "Conflict or expired assignment" }, "410": { "description": "Withdrawn release" }, "429": { "description": "Rate allowance exceeded" }, "503": { "description": "Required capability is not configured" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "a": { "type": "string", "maxLength": 12000 }, "b": { "type": "string", "maxLength": 12000 }, "mode": { "enum": [ "deterministic", "jev" ] }, "consent": { "type": "boolean" }, "release": { "type": [ "string", "integer" ] } }, "required": [ "a", "b" ] } } } } } }, "/v1/claims/evaluate-evidence": { "post": { "summary": "Assess supplied evidence fit without external verification", "responses": { "200": { "description": "Success; every v1 response includes x-request-id.", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Invalid input" }, "401": { "description": "Authentication required or expired" }, "403": { "description": "Scope or origin rejected" }, "409": { "description": "Conflict or expired assignment" }, "410": { "description": "Withdrawn release" }, "429": { "description": "Rate allowance exceeded" }, "503": { "description": "Required capability is not configured" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "claim": { "type": "string" }, "evidence": { "type": "array", "items": { "$ref": "#/components/schemas/EvidenceItem" }, "maxItems": 8 }, "mode": { "enum": [ "deterministic", "jev" ] }, "consent": { "type": "boolean" }, "store": { "type": "boolean" }, "release": { "type": [ "string", "integer" ] } }, "required": [ "claim", "evidence" ] } } } } } }, "/v1/observations": { "post": { "summary": "Submit a private observation pending independent validation", "responses": { "200": { "description": "Success; every v1 response includes x-request-id.", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Invalid input" }, "401": { "description": "Authentication required or expired" }, "403": { "description": "Scope or origin rejected" }, "409": { "description": "Conflict or expired assignment" }, "410": { "description": "Withdrawn release" }, "429": { "description": "Rate allowance exceeded" }, "503": { "description": "Required capability is not configured" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ObservationInput" } } } } } }, "/v1/me/wallet/challenge": { "post": { "summary": "Create a single-use signed wallet binding challenge", "responses": { "200": { "description": "Success; every v1 response includes x-request-id.", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Invalid input" }, "401": { "description": "Authentication required or expired" }, "403": { "description": "Scope or origin rejected" }, "409": { "description": "Conflict or expired assignment" }, "410": { "description": "Withdrawn release" }, "429": { "description": "Rate allowance exceeded" }, "503": { "description": "Required capability is not configured" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "wallet": { "type": "string" } }, "required": [ "wallet" ] } } } } } }, "/v1/me/wallet/bind": { "post": { "summary": "Bind a wallet by Ed25519 signature", "responses": { "200": { "description": "Success; every v1 response includes x-request-id.", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Invalid input" }, "401": { "description": "Authentication required or expired" }, "403": { "description": "Scope or origin rejected" }, "409": { "description": "Conflict or expired assignment" }, "410": { "description": "Withdrawn release" }, "429": { "description": "Rate allowance exceeded" }, "503": { "description": "Required capability is not configured" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "wallet": { "type": "string" }, "nonce": { "type": "string" }, "signature": { "type": "string" } }, "required": [ "wallet", "nonce", "signature" ] } } } } } }, "/v1/tasks/{id}/answer": { "post": { "summary": "Submit a judgment for an assigned human task", "responses": { "200": { "description": "Success; every v1 response includes x-request-id.", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Invalid input" }, "401": { "description": "Authentication required or expired" }, "403": { "description": "Scope or origin rejected" }, "409": { "description": "Conflict or expired assignment" }, "410": { "description": "Withdrawn release" }, "429": { "description": "Rate allowance exceeded" }, "503": { "description": "Required capability is not configured" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "answer": { "enum": [ "yes", "no", "unsure" ] } }, "required": [ "answer" ] } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/api/argument/import": { "post": { "summary": "Fetch a public HTTPS text source for review", "responses": { "200": { "description": "Success; every v1 response includes x-request-id.", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Invalid input" }, "401": { "description": "Authentication required or expired" }, "403": { "description": "Scope or origin rejected" }, "409": { "description": "Conflict or expired assignment" }, "410": { "description": "Withdrawn release" }, "429": { "description": "Rate allowance exceeded" }, "503": { "description": "Required capability is not configured" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string" }, "consent": { "const": true } }, "required": [ "url", "consent" ] } } } } } }, "/v1": { "get": { "summary": "Capabilities", "responses": { "200": { "description": "Success; every v1 response includes x-request-id.", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Invalid input" }, "401": { "description": "Authentication required or expired" }, "403": { "description": "Scope or origin rejected" }, "409": { "description": "Conflict or expired assignment" }, "410": { "description": "Withdrawn release" }, "429": { "description": "Rate allowance exceeded" }, "503": { "description": "Required capability is not configured" } } } }, "/v1/corpus": { "get": { "summary": "Corpus counts", "responses": { "200": { "description": "Success; every v1 response includes x-request-id.", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Invalid input" }, "401": { "description": "Authentication required or expired" }, "403": { "description": "Scope or origin rejected" }, "409": { "description": "Conflict or expired assignment" }, "410": { "description": "Withdrawn release" }, "429": { "description": "Rate allowance exceeded" }, "503": { "description": "Required capability is not configured" } } } }, "/v1/contexts": { "get": { "summary": "Public contribution contexts", "responses": { "200": { "description": "Success; every v1 response includes x-request-id.", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Invalid input" }, "401": { "description": "Authentication required or expired" }, "403": { "description": "Scope or origin rejected" }, "409": { "description": "Conflict or expired assignment" }, "410": { "description": "Withdrawn release" }, "429": { "description": "Rate allowance exceeded" }, "503": { "description": "Required capability is not configured" } }, "parameters": [ { "name": "target", "in": "query", "required": true, "schema": { "type": "string" } } ] } }, "/v1/practice": { "get": { "summary": "Reviewed practice contexts", "responses": { "200": { "description": "Success; every v1 response includes x-request-id.", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Invalid input" }, "401": { "description": "Authentication required or expired" }, "403": { "description": "Scope or origin rejected" }, "409": { "description": "Conflict or expired assignment" }, "410": { "description": "Withdrawn release" }, "429": { "description": "Rate allowance exceeded" }, "503": { "description": "Required capability is not configured" } }, "parameters": [ { "name": "target", "in": "query", "required": true, "schema": { "type": "string" } } ] } }, "/v1/releases": { "get": { "summary": "Release catalogue", "responses": { "200": { "description": "Success; every v1 response includes x-request-id.", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Invalid input" }, "401": { "description": "Authentication required or expired" }, "403": { "description": "Scope or origin rejected" }, "409": { "description": "Conflict or expired assignment" }, "410": { "description": "Withdrawn release" }, "429": { "description": "Rate allowance exceeded" }, "503": { "description": "Required capability is not configured" } } } }, "/v1/releases/{id}": { "get": { "summary": "Release manifest", "responses": { "200": { "description": "Success; every v1 response includes x-request-id.", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Invalid input" }, "401": { "description": "Authentication required or expired" }, "403": { "description": "Scope or origin rejected" }, "409": { "description": "Conflict or expired assignment" }, "410": { "description": "Withdrawn release" }, "429": { "description": "Rate allowance exceeded" }, "503": { "description": "Required capability is not configured" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/v1/releases/{id}/artifact": { "get": { "summary": "Committed reviewed artifact", "responses": { "200": { "description": "Success; every v1 response includes x-request-id.", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Invalid input" }, "401": { "description": "Authentication required or expired" }, "403": { "description": "Scope or origin rejected" }, "409": { "description": "Conflict or expired assignment" }, "410": { "description": "Withdrawn release" }, "429": { "description": "Rate allowance exceeded" }, "503": { "description": "Required capability is not configured" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/v1/epochs/{id}": { "get": { "summary": "Published epoch allocations", "responses": { "200": { "description": "Success; every v1 response includes x-request-id.", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Invalid input" }, "401": { "description": "Authentication required or expired" }, "403": { "description": "Scope or origin rejected" }, "409": { "description": "Conflict or expired assignment" }, "410": { "description": "Withdrawn release" }, "429": { "description": "Rate allowance exceeded" }, "503": { "description": "Required capability is not configured" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/v1/tasks/next": { "get": { "summary": "Reserve the next human task", "responses": { "200": { "description": "Success; every v1 response includes x-request-id.", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Invalid input" }, "401": { "description": "Authentication required or expired" }, "403": { "description": "Scope or origin rejected" }, "409": { "description": "Conflict or expired assignment" }, "410": { "description": "Withdrawn release" }, "429": { "description": "Rate allowance exceeded" }, "503": { "description": "Required capability is not configured" } } } }, "/v1/me": { "get": { "summary": "Contributor profile and allocations", "responses": { "200": { "description": "Success; every v1 response includes x-request-id.", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Invalid input" }, "401": { "description": "Authentication required or expired" }, "403": { "description": "Scope or origin rejected" }, "409": { "description": "Conflict or expired assignment" }, "410": { "description": "Withdrawn release" }, "429": { "description": "Rate allowance exceeded" }, "503": { "description": "Required capability is not configured" } } } } }, "components": { "schemas": { "Source": { "type": "object", "properties": { "name": { "type": "string" }, "url": { "type": "string", "format": "uri" }, "licence": { "type": "string" }, "licenceUrl": { "type": "string", "format": "uri" }, "sha256": { "type": "string" } }, "required": [ "name", "url", "licence", "licenceUrl" ] }, "Connection": { "type": "object", "properties": { "word": { "type": "string" }, "senseId": { "type": "string" }, "relation": { "type": "string" }, "type": { "type": "string" } }, "required": [ "word", "senseId", "relation", "type" ] }, "Sense": { "type": "object", "properties": { "id": { "type": "string" }, "synsetId": { "type": "string" }, "pos": { "type": "string" }, "definition": { "type": "string" }, "examples": { "type": "array", "items": { "type": "string" } }, "connections": { "type": "array", "items": { "$ref": "#/components/schemas/Connection" } } }, "required": [ "id", "synsetId", "pos", "definition", "examples", "connections" ] }, "Word": { "type": "object", "properties": { "word": { "type": "string" }, "pronunciations": { "type": "array", "items": { "type": "string" } }, "senses": { "type": "array", "items": { "$ref": "#/components/schemas/Sense" } }, "source": { "$ref": "#/components/schemas/Source" }, "usageNotes": { "type": "object", "properties": { "release": { "$ref": "#/components/schemas/MeaningRelease" }, "notes": { "type": "array", "items": { "$ref": "#/components/schemas/MeaningNote" } } }, "required": [ "release", "notes" ] } }, "required": [ "word", "senses", "pronunciations", "source" ] }, "Release": { "type": "object", "properties": { "source": { "$ref": "#/components/schemas/Source" }, "words": { "type": "integer" }, "senses": { "type": "integer" }, "connections": { "type": "integer" }, "prefixLength": { "type": "integer" }, "shards": { "type": "array", "items": { "type": "string" } } }, "required": [ "source", "words", "senses", "connections", "prefixLength", "shards" ] }, "Error": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] }, "UsageSource": { "type": "object", "required": [ "name", "licence", "url", "authorship" ], "properties": { "name": { "type": "string" }, "licence": { "type": "string" }, "url": { "type": "string" }, "authorship": { "type": "string" } } }, "UsageScene": { "type": "object", "required": [ "id", "channel", "context", "original", "hinge", "variants", "challenge", "boundary" ], "properties": { "id": { "type": "string" }, "channel": { "type": "string" }, "title": { "type": "string" }, "context": { "type": "string" }, "original": { "type": "string" }, "hinge": { "type": "string" }, "challenge": { "type": "string" }, "boundary": { "type": "string" }, "variants": { "type": "array", "minItems": 3, "maxItems": 3, "items": { "type": "object", "required": [ "intent", "text", "explanation" ], "properties": { "intent": { "type": "string" }, "text": { "type": "string" }, "explanation": { "type": "string" } } } } } }, "UsageContrast": { "type": "object", "required": [ "id", "groupId", "release", "context", "before", "after", "intendedEffect", "expectedObservation", "notInferable", "provenance", "review", "evaluation" ], "properties": { "id": { "type": "string" }, "groupId": { "type": "string" }, "release": { "type": "string" }, "language": { "type": "string" }, "channel": { "type": "string" }, "context": { "type": "string" }, "before": { "type": "string" }, "after": { "type": "string" }, "intendedEffect": { "type": "string" }, "expectedObservation": { "type": "string" }, "notInferable": { "type": "string" }, "provenance": { "$ref": "#/components/schemas/UsageSource" }, "review": { "type": "object", "properties": { "status": { "const": "unreviewed" }, "independentReviewers": { "const": 0 } } }, "evaluation": { "type": "object", "properties": { "type": { "const": "qualitative-contrast" }, "goldLabel": { "type": "null" }, "splitUnit": { "const": "groupId" }, "task": { "type": "string" } } } } }, "DatasetManifest": { "type": "object", "required": [ "schemaVersion", "dataset", "version", "status", "count", "pageSize", "source", "files" ], "properties": { "schemaVersion": { "const": 1 }, "dataset": { "type": "string" }, "version": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "status": { "type": "string" }, "count": { "type": "integer", "minimum": 1 }, "pageSize": { "const": 100 }, "source": { "type": "object" }, "files": { "type": "object", "additionalProperties": { "type": "object", "required": [ "bytes", "sha256" ], "properties": { "bytes": { "type": "integer", "minimum": 0 }, "sha256": { "type": "string", "pattern": "^[a-f0-9]{64}$" } } } } } }, "LiteraryRecord": { "type": "object", "required": [ "id", "text", "provenance" ], "properties": { "id": { "type": "string" }, "text": { "type": "string" }, "topic": { "type": [ "string", "null" ] }, "words": { "type": "array" }, "provenance": { "type": "object", "required": [ "work", "author", "year", "source", "url", "licence", "retrieved" ] } } }, "AssociationRecord": { "type": "object", "required": [ "id", "word", "tier", "associates" ], "properties": { "id": { "type": "string" }, "word": { "type": "string" }, "tier": { "type": "integer" }, "associates": { "type": "array", "items": { "type": "object", "required": [ "word", "connection", "evidenceKinds" ], "properties": { "word": { "type": "string" }, "connection": { "type": "string" }, "evidenceKinds": { "type": "array", "items": { "enum": [ "definition-crossing", "literary-cooccurrence", "lexical-or-editorial-unresolved", "editorial" ] } } } } } } }, "ReviewedEvidenceRecord": { "type": "object", "required": [ "id", "groupId", "eventFamily", "split", "rubricVersion", "observation", "claim" ], "properties": { "id": { "type": "string" }, "groupId": { "type": "string" }, "eventFamily": { "type": "string" }, "split": { "enum": [ "development", "validation", "holdout" ] }, "rubricVersion": { "type": "string" }, "observation": { "type": "object", "required": [ "id", "sourceId", "sourceUrl", "text", "publishedAt", "observedAt", "rights" ] }, "claim": { "type": "object", "required": [ "id", "observationId", "span", "modality", "attributedSpeaker", "interpretation", "notInferable", "reviews" ], "description": "Reviewed interpretation; exact Unicode code-point span; no assumed speaker intent or outcome." } } }, "DatasetPage": { "type": "object", "required": [ "dataset", "version", "status", "source", "total", "count", "nextCursor", "records" ], "properties": { "dataset": { "type": "string" }, "version": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "status": { "type": "string" }, "source": { "type": "object" }, "total": { "type": "integer" }, "count": { "type": "integer", "maximum": 100 }, "nextCursor": { "type": [ "string", "null" ] }, "records": { "type": "array", "maxItems": 100, "items": { "oneOf": [ { "$ref": "#/components/schemas/LiteraryRecord" }, { "$ref": "#/components/schemas/AssociationRecord" }, { "$ref": "#/components/schemas/ReviewedEvidenceRecord" } ] } } } }, "DatasetRecord": { "type": "object", "required": [ "dataset", "version", "source", "record" ], "properties": { "dataset": { "type": "string" }, "version": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "source": { "type": "object" }, "record": { "oneOf": [ { "$ref": "#/components/schemas/LiteraryRecord" }, { "$ref": "#/components/schemas/AssociationRecord" }, { "$ref": "#/components/schemas/ReviewedEvidenceRecord" } ] } } }, "DatasetCatalog": { "type": "object", "required": [ "schemaVersion", "datasets" ], "properties": { "schemaVersion": { "const": 1 }, "datasets": { "type": "array", "items": { "type": "object", "required": [ "id", "kind", "manifest", "records" ] } } } }, "MeaningNote": { "type": "object", "properties": { "word": { "type": "string" }, "readings": { "type": "array", "items": { "type": "string" } }, "example": { "type": "string" }, "question": { "type": "string" } }, "required": [ "word", "readings", "example", "question" ] }, "MeaningRelease": { "type": "object", "properties": { "version": { "type": "string" }, "language": { "const": "en" }, "status": { "const": "editorial-preview" }, "source": { "type": "object", "properties": { "name": { "type": "string" }, "authorship": { "type": "string" }, "licence": { "const": "CC BY 4.0" }, "url": { "type": "string", "format": "uri" } }, "required": [ "name", "authorship", "licence", "url" ] }, "scope": { "type": "string" } }, "required": [ "version", "language", "status", "source", "scope" ] }, "ArgumentSource": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[a-zA-Z0-9_-]{1,64}$" }, "label": { "type": "string", "minLength": 1, "maxLength": 200 }, "text": { "type": "string", "minLength": 1, "maxLength": 24000, "description": "At most 600 sentences; retained verbatim." }, "url": { "type": "string", "maxLength": 2000, "description": "Optional HTTP(S) source URL without credentials; never fetched." } }, "required": [ "id", "label", "text" ] }, "ArgumentInput": { "type": "object", "properties": { "text": { "type": "string", "minLength": 1, "maxLength": 12000, "description": "At most 100 sentences; whitespace-only text is rejected." }, "context": { "type": "string", "maxLength": 2000 }, "reply": { "type": "string", "maxLength": 12000 }, "sources": { "type": "array", "maxItems": 4, "items": { "$ref": "#/components/schemas/ArgumentSource" } }, "mode": { "type": "string", "enum": [ "local", "cloud" ], "default": "local" }, "consent": { "type": "boolean", "description": "Must be true for cloud review." } }, "required": [ "text", "sources" ] }, "ArgumentCitation": { "type": "object", "properties": { "sourceId": { "type": "string" }, "start": { "type": "integer", "minimum": 0, "description": "Inclusive UTF-16 offset in original text." }, "end": { "type": "integer", "minimum": 1, "description": "Exclusive UTF-16 offset in original text." }, "quote": { "type": "string" } }, "required": [ "sourceId", "start", "end", "quote" ] }, "TextCheckStatement": { "type": "object", "properties": { "id": { "type": "string" }, "start": { "type": "integer", "minimum": 0, "description": "Inclusive UTF-16 offset in original text." }, "end": { "type": "integer", "minimum": 1, "description": "Exclusive UTF-16 offset in original text." }, "quote": { "type": "string" }, "status": { "enum": [ "no_source", "no_match", "related_text" ] }, "matches": { "type": "array", "items": { "$ref": "#/components/schemas/ArgumentCitation" } }, "cautions": { "type": "array", "items": { "type": "object", "properties": { "code": { "enum": [ "number", "negation", "scope", "certainty" ] }, "text": { "type": "string" } }, "required": [ "code", "text" ] } } }, "required": [ "id", "start", "end", "quote", "status", "matches", "cautions" ] }, "TextCheckReview": { "type": "object", "properties": { "version": { "type": "string" }, "method": { "const": "text-checks" }, "externalVerification": { "const": "not_performed" }, "summary": { "type": "string" }, "statements": { "type": "array", "items": { "$ref": "#/components/schemas/TextCheckStatement" } }, "meanings": { "type": "array", "items": { "$ref": "#/components/schemas/MeaningNote" } }, "meaningRelease": { "$ref": "#/components/schemas/MeaningRelease" }, "limits": { "type": "array", "items": { "type": "string" } } }, "required": [ "version", "method", "externalVerification", "summary", "statements", "meanings", "meaningRelease", "limits" ] }, "ContextualReview": { "type": "object", "properties": { "version": { "type": "string" }, "method": { "const": "model-assisted" }, "model": { "type": "string" }, "externalVerification": { "const": "not_performed" }, "review": { "type": "object", "properties": { "summary": { "type": "string" }, "claims": { "type": "array", "minItems": 1, "maxItems": 12, "items": { "type": "object", "properties": { "quote": { "type": "string" }, "assessment": { "enum": [ "supported", "contradicted", "insufficient", "not_factual" ] }, "explanation": { "type": "string" }, "citations": { "type": "array", "items": { "$ref": "#/components/schemas/ArgumentCitation" } }, "nextCheck": { "type": "string" } }, "required": [ "quote", "assessment", "explanation", "citations", "nextCheck" ] } }, "communication": { "type": "array", "maxItems": 6, "items": { "type": "object", "properties": { "term": { "type": "string" }, "readings": { "type": "array", "items": { "type": "string" } }, "explanation": { "type": "string" }, "question": { "type": "string" } }, "required": [ "term", "readings", "explanation", "question" ] } }, "revision": { "type": "string" } }, "required": [ "summary", "claims", "communication", "revision" ] }, "lexicon": { "type": "object", "properties": { "source": { "$ref": "#/components/schemas/Source" }, "entries": { "type": "array", "items": { "type": "object", "properties": { "word": { "type": "string" }, "senses": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "definition": { "type": "string" }, "pos": { "type": "string" } }, "required": [ "id", "definition", "pos" ] } } }, "required": [ "word", "senses" ] } }, "scope": { "type": "string" } }, "required": [ "source", "entries", "scope" ] }, "meaningRelease": { "$ref": "#/components/schemas/MeaningRelease" } }, "required": [ "version", "method", "model", "externalVerification", "review", "lexicon", "meaningRelease" ] }, "ArgumentCapabilities": { "type": "object", "properties": { "version": { "type": "string" }, "localChecks": { "const": true }, "cloudReview": { "type": "boolean" }, "authentication": { "type": "string" }, "limits": { "type": "object", "properties": { "text": { "type": "integer" }, "context": { "type": "integer" }, "sources": { "type": "integer" }, "sourceText": { "type": "integer" }, "statements": { "type": "integer" }, "sourcePassages": { "type": "integer" }, "bodyBytes": { "type": "integer" } }, "required": [ "text", "context", "sources", "sourceText", "statements", "sourcePassages", "bodyBytes" ] }, "notes": { "$ref": "#/components/schemas/MeaningRelease" }, "meanings": { "type": "array", "items": { "$ref": "#/components/schemas/MeaningNote" } } }, "required": [ "version", "localChecks", "cloudReview", "authentication", "limits", "notes", "meanings" ] }, "Transcription": { "type": "object", "properties": { "text": { "type": "string" }, "method": { "const": "audio-transcription" }, "reviewRequired": { "const": true }, "visualContentAssessed": { "const": false } }, "required": [ "text", "method", "reviewRequired", "visualContentAssessed" ] }, "SemanticRelease": { "type": "object", "properties": { "version": { "type": "string" }, "hash": { "type": [ "string", "null" ] }, "model": { "type": "string" }, "epoch": { "type": [ "integer", "null" ] } }, "required": [ "version", "hash", "model", "epoch" ] }, "ResolveInput": { "type": "object", "properties": { "text": { "type": "string", "minLength": 1, "maxLength": 12000 }, "target": { "type": "string", "maxLength": 100 }, "span": { "type": "array", "items": { "type": "integer", "minimum": 0 }, "minItems": 2, "maxItems": 2 }, "release": { "type": [ "string", "integer" ] }, "mode": { "type": "string", "enum": [ "deterministic", "jev", "consensus" ], "default": "deterministic" }, "inventory": { "type": "string", "enum": [ "accepted", "reference" ], "default": "accepted", "description": "For /v1/resolve: reference uses the current editorial inventory and cannot be combined with release. It is not an accepted consensus snapshot." } }, "required": [ "text" ] }, "Resolution": { "type": "object", "properties": { "target": { "type": "string" }, "span": { "anyOf": [ { "type": "array", "items": { "type": "integer", "minimum": 0 }, "minItems": 2, "maxItems": 2 }, { "type": "null" } ] }, "sense": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "gloss": { "type": "string" } }, "required": [ "id", "gloss" ] }, { "type": "null" } ] }, "status": { "enum": [ "candidate", "unresolved", "not_found" ] }, "abstention": { "enum": [ "NO_SUPPORTED_SENSE", "AMBIGUOUS_TARGET", null ] }, "confidence": { "type": [ "number", "null" ] }, "selectedProbability": { "type": [ "number", "null" ] }, "calibrated": { "const": false }, "alternatives": { "type": "array", "items": { "type": "object" } }, "evidence": { "type": "array", "items": { "type": "object" } }, "release": { "$ref": "#/components/schemas/SemanticRelease" } }, "required": [ "target", "span", "sense", "status", "abstention", "confidence", "selectedProbability", "calibrated", "alternatives", "evidence", "release" ] }, "ArgumentMessage": { "type": "object", "properties": { "id": { "type": "string" }, "text": { "type": "string", "maxLength": 12000 }, "author": { "type": "string" }, "replyTo": { "type": "string" }, "quotedMessageId": { "type": "string" }, "createdAt": { "type": "string" } }, "required": [ "id", "text" ] }, "AnalyzeArgumentInput": { "type": "object", "properties": { "messages": { "type": "array", "items": { "$ref": "#/components/schemas/ArgumentMessage" }, "minItems": 1, "maxItems": 20 }, "focusMessageId": { "type": "string" }, "maxClaims": { "type": "integer", "minimum": 1, "maximum": 40 }, "mode": { "enum": [ "deterministic", "jev" ] }, "consent": { "type": "boolean" }, "store": { "type": "boolean" }, "release": { "type": [ "string", "integer" ] } }, "required": [ "messages" ] }, "ClaimComparison": { "type": "object", "properties": { "relation": { "enum": [ "equivalent", "entails", "contradicts", "compatible", "different_scope", "different_strength", "different_referent", "unrelated", "uncertain" ] }, "confidence": { "type": [ "number", "null" ] }, "calibrated": { "const": false }, "differences": { "type": "array", "items": { "type": "object" } }, "basis": { "type": "string" }, "release": { "$ref": "#/components/schemas/SemanticRelease" } }, "required": [ "relation", "confidence", "calibrated", "differences", "basis", "release" ] }, "EvidenceItem": { "type": "object", "properties": { "id": { "type": "string" }, "excerpt": { "type": "string", "maxLength": 24000 }, "title": { "type": "string" }, "publisher": { "type": "string" }, "url": { "type": "string", "format": "uri" }, "publishedAt": { "type": "string" }, "sourceType": { "enum": [ "primary", "secondary", "unknown" ] } }, "required": [ "id", "excerpt" ] }, "ObservationInput": { "type": "object", "properties": { "source": { "type": "object", "properties": { "platform": { "type": "string" }, "externalId": { "type": "string" }, "authorExternalId": { "type": "string" }, "url": { "type": "string" } }, "required": [ "platform", "externalId" ] }, "observedText": { "type": "string", "maxLength": 12000 }, "textHash": { "type": "string" }, "targets": { "type": "array", "items": { "type": "string" }, "minItems": 1, "maxItems": 12 }, "analysisId": { "type": "string" }, "residuals": { "type": "array", "items": { "type": "object", "properties": { "expression": { "type": "string" }, "reason": { "type": "string" }, "score": { "type": "number", "minimum": 0, "maximum": 1 } }, "required": [ "expression", "reason", "score" ] } }, "rights": { "type": "object", "properties": { "analysis": { "const": true }, "display": { "type": "boolean" }, "redistribute": { "type": "boolean" }, "training": { "type": "boolean" }, "basis": { "type": "string" } }, "required": [ "analysis", "display", "redistribute", "training", "basis" ] } }, "required": [ "source", "observedText", "targets", "rights" ] } }, "securitySchemes": { "DatasetKey": { "type": "http", "scheme": "bearer", "description": "Active, unexpired DATA_KEYS entry with datasets containing observed-language; dictionary scope is required for the legacy private-word endpoint." }, "ArgumentKey": { "type": "http", "scheme": "bearer", "description": "A Superb key with the argument-review entitlement; required only for cloud review and transcription." } } } }