{ "openapi": "3.1.0", "info": { "title": "NarcoScope Public Evidence API", "version": "1.6.0", "description": "Read-only access to NarcoScope's aggregate official-data overview, country-year illicit-economy atlas, privacy-minimized public designations, citation-gated newsroom, and non-joinable Seiche and Palimpsest context lanes. No endpoint provides point-of-sale, real-time, navigable, synthesis-route, or yield information; no federation endpoint creates a shared score, composite, causal inference, or culpability inference." }, "servers": [ { "url": "https://narcoscope.com/api/v1" } ], "externalDocs": { "description": "API and MCP quickstart", "url": "https://narcoscope.com/developers/" }, "components": { "schemas": { "Envelope": { "type": "object", "required": [ "ok", "resource", "data" ], "properties": { "ok": { "type": "boolean", "const": true }, "resource": { "type": "string" }, "data": { "type": "object", "additionalProperties": true } }, "additionalProperties": false }, "PalimpsestBriContext": { "$schema": "https://json-schema.org/draft/2020-12/schema", "$id": "https://narcoscope.com/schemas/narcoscope-palimpsest-bri-envelope-v1.schema.json", "$defs": { "artifact": { "$schema": "https://json-schema.org/draft/2020-12/schema", "$id": "https://narcoscope.com/data/narcoscope-palimpsest-bri-v1.schema.json", "title": "NarcoScope Palimpsest BRI parallel-context bridge", "type": "object", "required": [ "$schema", "schemaVersion", "artifactId", "dataAsOf", "scope", "provenance", "sourceReadiness", "claimSemantics", "targetCoverage", "economicContext", "usePolicy", "limitations" ], "properties": { "$schema": { "const": "./narcoscope-palimpsest-bri-v1.schema.json" }, "schemaVersion": { "const": "narcoscope.palimpsest.bri-context.v1" }, "artifactId": { "const": "narcoscope.palimpsest.bri-parallel-context" }, "dataAsOf": { "$ref": "#/$defs/dateTime" }, "scope": { "type": "string", "minLength": 1 }, "provenance": { "$ref": "#/$defs/provenance" }, "sourceReadiness": { "$ref": "#/$defs/sourceReadiness" }, "claimSemantics": { "$ref": "#/$defs/claimSemantics" }, "targetCoverage": { "type": "array", "minItems": 5, "maxItems": 5, "items": { "$ref": "#/$defs/targetArea" } }, "economicContext": { "$ref": "#/$defs/economicContext" }, "usePolicy": { "$ref": "#/$defs/usePolicy" }, "limitations": { "type": "array", "minItems": 8, "items": { "type": "string", "minLength": 1 }, "uniqueItems": true } }, "additionalProperties": false, "$defs": { "sha256": { "type": "string", "pattern": "^[0-9a-f]{64}$" }, "commit": { "type": "string", "pattern": "^[0-9a-f]{40}$" }, "gitOid": { "type": "string", "pattern": "^(?:[0-9a-f]{40}|[0-9a-f]{64})$" }, "dateTime": { "type": "string", "format": "date-time" }, "uri": { "type": "string", "format": "uri" }, "nullableYear": { "type": [ "integer", "null" ], "minimum": 1900, "maximum": 2200 }, "stringArray": { "type": "array", "items": { "type": "string", "minLength": 1 }, "uniqueItems": true }, "countMap": { "type": "object", "minProperties": 1, "additionalProperties": { "type": "integer", "minimum": 0 } }, "optionalCountMap": { "type": "object", "additionalProperties": { "type": "integer", "minimum": 0 } }, "sourceDescriptor": { "type": "object", "required": [ "path", "canonicalUrl", "bytes", "sha256", "gitBlobOid" ], "properties": { "path": { "type": "string", "minLength": 1 }, "canonicalUrl": { "$ref": "#/$defs/uri" }, "railwayMirrorUrl": { "$ref": "#/$defs/uri" }, "bytes": { "type": "integer", "minimum": 1 }, "sha256": { "$ref": "#/$defs/sha256" }, "gitBlobOid": { "$ref": "#/$defs/gitOid" } }, "additionalProperties": false }, "sourceArtifacts": { "type": "object", "required": [ "observatory", "economics", "pagesPublicationReceipt" ], "properties": { "observatory": { "$ref": "#/$defs/sourceDescriptor" }, "economics": { "$ref": "#/$defs/sourceDescriptor" }, "pagesPublicationReceipt": { "$ref": "#/$defs/sourceDescriptor" } }, "additionalProperties": false }, "pagesPublication": { "type": "object", "required": [ "verificationState", "sourceRevision", "sourceTreeOid", "receiptBytes", "receiptSha256", "verifiedAt", "freshUntil", "availabilitySemantics", "servedResources" ], "properties": { "verificationState": { "const": "served_resource_receipt_validated" }, "sourceRevision": { "$ref": "#/$defs/commit" }, "sourceTreeOid": { "$ref": "#/$defs/gitOid" }, "receiptBytes": { "type": "integer", "minimum": 1 }, "receiptSha256": { "$ref": "#/$defs/sha256" }, "verifiedAt": { "$ref": "#/$defs/dateTime" }, "freshUntil": { "$ref": "#/$defs/dateTime" }, "availabilitySemantics": { "type": "string", "minLength": 1 }, "servedResources": { "type": "array", "minItems": 3, "maxItems": 3, "items": { "$ref": "#/$defs/sourceDescriptor" } } }, "additionalProperties": false }, "release": { "type": "object", "required": [ "producer", "verificationState", "canonicalBaseUrl", "railwayMirrorBaseUrl", "deploymentId", "sourceRevision", "sourceTreeOid", "artifactTreeSha256", "artifactManifest", "receiptBytes", "receiptSha256", "verifiedAt", "verificationSemantics", "pagesPublication" ], "properties": { "producer": { "const": "Palimpsest" }, "verificationState": { "const": "release_receipt_validated" }, "canonicalBaseUrl": { "const": "https://palimpsest.info" }, "railwayMirrorBaseUrl": { "$ref": "#/$defs/uri" }, "deploymentId": { "type": "string", "minLength": 1 }, "sourceRevision": { "$ref": "#/$defs/commit" }, "sourceTreeOid": { "$ref": "#/$defs/gitOid" }, "artifactTreeSha256": { "$ref": "#/$defs/sha256" }, "artifactManifest": { "type": "object", "required": [ "schemaVersion", "bytes", "sha256", "fileCount", "totalBytes" ], "properties": { "schemaVersion": { "const": "palimpsest.railway-static-release.v1" }, "bytes": { "type": "integer", "minimum": 1 }, "sha256": { "$ref": "#/$defs/sha256" }, "fileCount": { "type": "integer", "minimum": 1 }, "totalBytes": { "type": "integer", "minimum": 1 } }, "additionalProperties": false }, "receiptBytes": { "type": "integer", "minimum": 1 }, "receiptSha256": { "$ref": "#/$defs/sha256" }, "verifiedAt": { "$ref": "#/$defs/dateTime" }, "verificationSemantics": { "type": "string", "minLength": 1 }, "pagesPublication": { "$ref": "#/$defs/pagesPublication" } }, "additionalProperties": false }, "provenance": { "type": "object", "required": [ "producer", "consumer", "sourcePin", "schema", "release", "sourceArtifacts" ], "properties": { "producer": { "const": "Palimpsest" }, "consumer": { "const": "NarcoScope" }, "sourcePin": { "type": "object", "required": [ "path", "schemaVersion", "bytes", "sha256" ], "properties": { "path": { "const": "scripts/bridge/palimpsest-bri-source-pin.json" }, "schemaVersion": { "const": "narcoscope.palimpsest.bri-source-pin.v1" }, "bytes": { "type": "integer", "minimum": 1 }, "sha256": { "$ref": "#/$defs/sha256" } }, "additionalProperties": false }, "schema": { "type": "object", "required": [ "path", "id", "bytes", "sha256" ], "properties": { "path": { "const": "public/data/narcoscope-palimpsest-bri-v1.schema.json" }, "id": { "const": "https://narcoscope.com/data/narcoscope-palimpsest-bri-v1.schema.json" }, "bytes": { "type": "integer", "minimum": 1 }, "sha256": { "$ref": "#/$defs/sha256" } }, "additionalProperties": false }, "release": { "$ref": "#/$defs/release" }, "sourceArtifacts": { "$ref": "#/$defs/sourceArtifacts" } }, "additionalProperties": false }, "sourceReadiness": { "type": "object", "required": [ "sourceCount", "buildReadySourceCount", "implementationStates", "rightsStatusCounts", "buildReadyGaps" ], "properties": { "sourceCount": { "type": "integer", "minimum": 1 }, "buildReadySourceCount": { "type": "integer", "minimum": 0 }, "implementationStates": { "type": "object", "required": [ "adapter_ready", "blocked", "link_only", "live", "planned" ], "properties": { "adapter_ready": { "type": "integer", "minimum": 0 }, "blocked": { "type": "integer", "minimum": 0 }, "link_only": { "type": "integer", "minimum": 0 }, "live": { "type": "integer", "minimum": 0 }, "planned": { "type": "integer", "minimum": 0 } }, "additionalProperties": false }, "rightsStatusCounts": { "$ref": "#/$defs/countMap" }, "buildReadyGaps": { "$ref": "#/$defs/stringArray" } }, "additionalProperties": false }, "claimSemantics": { "type": "object", "required": [ "classificationRule", "sourceClassCounts", "authorityRoleCounts", "claimClassCounts", "officialOrAdministrativeSourceIds", "independentObservationSourceIds", "modeledOrAnalyticalSourceIds" ], "properties": { "classificationRule": { "type": "string", "minLength": 1 }, "sourceClassCounts": { "$ref": "#/$defs/countMap" }, "authorityRoleCounts": { "$ref": "#/$defs/countMap" }, "claimClassCounts": { "$ref": "#/$defs/countMap" }, "officialOrAdministrativeSourceIds": { "$ref": "#/$defs/stringArray" }, "independentObservationSourceIds": { "$ref": "#/$defs/stringArray" }, "modeledOrAnalyticalSourceIds": { "$ref": "#/$defs/stringArray" } }, "additionalProperties": false }, "sourceSummary": { "type": "object", "required": [ "sourceId", "implementationState", "sourceClass", "authorityRole", "rightsStatus", "claimClasses" ], "properties": { "sourceId": { "type": "string", "pattern": "^[a-z0-9_]+$" }, "implementationState": { "enum": [ "adapter_ready", "blocked", "link_only", "live", "planned" ] }, "sourceClass": { "type": "string", "minLength": 1 }, "authorityRole": { "type": "string", "minLength": 1 }, "rightsStatus": { "type": "string", "minLength": 1 }, "claimClasses": { "$ref": "#/$defs/stringArray" } }, "additionalProperties": false }, "target": { "type": "object", "required": [ "targetId", "label", "targetType", "evidenceStatus", "requiredCoverage", "sourceReadiness", "sources" ], "properties": { "targetId": { "type": "string", "pattern": "^[a-z0-9_]+$" }, "label": { "type": "string", "minLength": 1 }, "targetType": { "type": "string", "minLength": 1 }, "evidenceStatus": { "type": "string", "minLength": 1 }, "requiredCoverage": { "$ref": "#/$defs/stringArray" }, "sourceReadiness": { "type": "object", "required": [ "sourceCount", "buildReadySourceCount", "implementationStates" ], "properties": { "sourceCount": { "type": "integer", "minimum": 1 }, "buildReadySourceCount": { "type": "integer", "minimum": 0 }, "implementationStates": { "$ref": "#/$defs/countMap" } }, "additionalProperties": false }, "sources": { "type": "array", "minItems": 1, "items": { "$ref": "#/$defs/sourceSummary" } } }, "additionalProperties": false }, "targetArea": { "type": "object", "required": [ "areaId", "label", "targets" ], "properties": { "areaId": { "enum": [ "cpec", "gwadar", "cmec", "kyaukpyu", "balochistan" ] }, "label": { "type": "string", "minLength": 1 }, "targets": { "type": "array", "minItems": 1, "items": { "$ref": "#/$defs/target" } } }, "additionalProperties": false }, "coverageWindow": { "type": "object", "required": [ "fromYear", "toYear", "yearCount" ], "properties": { "fromYear": { "$ref": "#/$defs/nullableYear" }, "toYear": { "$ref": "#/$defs/nullableYear" }, "yearCount": { "type": "integer", "minimum": 0 } }, "additionalProperties": false }, "unavailableCoverage": { "type": "object", "required": [ "fromYear", "toYear", "yearCount", "reasonCounts" ], "properties": { "fromYear": { "$ref": "#/$defs/nullableYear" }, "toYear": { "$ref": "#/$defs/nullableYear" }, "yearCount": { "type": "integer", "minimum": 0 }, "reasonCounts": { "$ref": "#/$defs/optionalCountMap" } }, "additionalProperties": false }, "indicatorCoverage": { "type": "object", "required": [ "seriesId", "indicatorId", "unit", "annualCoverage", "sourceRowCount", "observed", "forecast", "unavailable" ], "properties": { "seriesId": { "type": "string", "minLength": 1 }, "indicatorId": { "type": "string", "minLength": 1 }, "unit": { "type": "string", "minLength": 1 }, "annualCoverage": { "$ref": "#/$defs/coverageWindow" }, "sourceRowCount": { "type": "integer", "minimum": 1 }, "observed": { "$ref": "#/$defs/coverageWindow" }, "forecast": { "$ref": "#/$defs/coverageWindow" }, "unavailable": { "$ref": "#/$defs/unavailableCoverage" } }, "additionalProperties": false }, "countryCoverage": { "type": "object", "required": [ "countryCode", "country", "indicatorCount", "sourceRowCount", "observedRowCount", "forecastRowCount", "unavailableRowCount", "indicators" ], "properties": { "countryCode": { "enum": [ "CHN", "MMR", "PAK" ] }, "country": { "enum": [ "China", "Myanmar", "Pakistan" ] }, "indicatorCount": { "type": "integer", "minimum": 1 }, "sourceRowCount": { "type": "integer", "minimum": 1 }, "observedRowCount": { "type": "integer", "minimum": 0 }, "forecastRowCount": { "type": "integer", "minimum": 0 }, "unavailableRowCount": { "type": "integer", "minimum": 0 }, "indicators": { "type": "array", "minItems": 1, "items": { "$ref": "#/$defs/indicatorCoverage" } } }, "additionalProperties": false }, "economicContext": { "type": "object", "required": [ "schemaVersion", "generatedAt", "collectionId", "source", "rights", "clocks", "hashPointers", "contextPolicy", "coverage" ], "properties": { "schemaVersion": { "const": "palimpsest.bri-economic-observations.v1" }, "generatedAt": { "$ref": "#/$defs/dateTime" }, "collectionId": { "$ref": "#/$defs/sha256" }, "source": { "type": "object", "required": [ "sourceId", "name", "publisher", "attribution", "catalogUrl" ], "properties": { "sourceId": { "const": "world_bank_wdi" }, "name": { "type": "string", "minLength": 1 }, "publisher": { "type": "string", "minLength": 1 }, "attribution": { "type": "string", "minLength": 1 }, "catalogUrl": { "$ref": "#/$defs/uri" } }, "additionalProperties": false }, "rights": { "type": "object", "required": [ "license", "licenseUrl", "redistributionStatus", "rightsEvidenceUrl", "attribution" ], "properties": { "license": { "type": "string", "minLength": 1 }, "licenseUrl": { "$ref": "#/$defs/uri" }, "redistributionStatus": { "type": "string", "minLength": 1 }, "rightsEvidenceUrl": { "$ref": "#/$defs/uri" }, "attribution": { "type": "string", "minLength": 1 } }, "additionalProperties": false }, "clocks": { "type": "object", "required": [ "generatedAt", "datasetLastUpdated", "sourceReleaseUpperBound", "retrievedAt" ], "properties": { "generatedAt": { "$ref": "#/$defs/dateTime" }, "datasetLastUpdated": { "type": "string", "format": "date" }, "sourceReleaseUpperBound": { "$ref": "#/$defs/dateTime" }, "retrievedAt": { "$ref": "#/$defs/dateTime" } }, "additionalProperties": false }, "hashPointers": { "type": "object", "required": [ "observationsSha256", "registrySha256", "rawResponseSha256s" ], "properties": { "observationsSha256": { "$ref": "#/$defs/sha256" }, "registrySha256": { "$ref": "#/$defs/sha256" }, "rawResponseSha256s": { "type": "array", "minItems": 1, "items": { "$ref": "#/$defs/sha256" }, "uniqueItems": true } }, "additionalProperties": false }, "contextPolicy": { "type": "object", "required": [ "aggregateLevel", "scope", "causalityBoundary", "missingValuePolicy", "forecastPolicy", "downstreamSemantics" ], "properties": { "aggregateLevel": { "const": "country" }, "scope": { "const": "national_economic_context" }, "causalityBoundary": { "const": "not_evidence_of_bri_causality" }, "missingValuePolicy": { "const": "source_null_remains_unavailable" }, "forecastPolicy": { "type": "string", "minLength": 1 }, "downstreamSemantics": { "type": "object", "required": [ "observed", "forecast", "unavailable", "join_boundary" ], "properties": { "observed": { "type": "string", "minLength": 1 }, "forecast": { "type": "string", "minLength": 1 }, "unavailable": { "type": "string", "minLength": 1 }, "join_boundary": { "type": "string", "minLength": 1 } }, "additionalProperties": false } }, "additionalProperties": false }, "coverage": { "type": "object", "required": [ "totals", "countries" ], "properties": { "totals": { "type": "object", "required": [ "countries", "indicators", "sourceRows", "observedRows", "forecastRows", "unavailableRows" ], "properties": { "countries": { "const": 3 }, "indicators": { "type": "integer", "minimum": 1 }, "sourceRows": { "type": "integer", "minimum": 1 }, "observedRows": { "type": "integer", "minimum": 0 }, "forecastRows": { "type": "integer", "minimum": 0 }, "unavailableRows": { "type": "integer", "minimum": 0 } }, "additionalProperties": false }, "countries": { "type": "array", "minItems": 3, "maxItems": 3, "items": { "$ref": "#/$defs/countryCoverage" } } }, "additionalProperties": false } }, "additionalProperties": false }, "usePolicy": { "type": "object", "required": [ "lane", "allowedUse", "crossLaneJoinPolicy", "displayRelationship", "prohibitions" ], "properties": { "lane": { "const": "parallel_context_only" }, "allowedUse": { "type": "string", "minLength": 1 }, "crossLaneJoinPolicy": { "const": "prohibited" }, "displayRelationship": { "type": "string", "minLength": 1 }, "prohibitions": { "type": "object", "required": [ "drugConflictInfrastructureCausalJoin", "actorClassification", "bilateralRouteInference", "guiltInference", "politicalMovementClassification", "projectAttributionFromNationalSeries", "tacticalOrNavigableUse" ], "properties": { "drugConflictInfrastructureCausalJoin": { "const": "prohibited" }, "actorClassification": { "const": "prohibited" }, "bilateralRouteInference": { "const": "prohibited" }, "guiltInference": { "const": "prohibited" }, "politicalMovementClassification": { "const": "prohibited" }, "projectAttributionFromNationalSeries": { "const": "prohibited" }, "tacticalOrNavigableUse": { "const": "prohibited" } }, "additionalProperties": false } }, "additionalProperties": false } } } }, "type": "object", "required": [ "schema", "data", "links", "interpretation" ], "properties": { "schema": { "const": "narcoscope.api.palimpsest-bri-envelope.v1" }, "data": { "$ref": "#/$defs/artifact" }, "links": { "type": "object", "required": [ "canonical", "sha256", "schema" ], "properties": { "canonical": { "type": "string", "format": "uri" }, "sha256": { "type": "string", "format": "uri" }, "schema": { "const": "https://narcoscope.com/data/narcoscope-palimpsest-bri-v1.schema.json" } }, "additionalProperties": false }, "interpretation": { "type": "string", "minLength": 1 } }, "additionalProperties": false }, "PalimpsestBriRestEnvelope": { "type": "object", "required": [ "ok", "resource", "data" ], "properties": { "ok": { "const": true }, "resource": { "const": "palimpsest-bri" }, "data": { "$ref": "#/components/schemas/PalimpsestBriContext" } }, "additionalProperties": false }, "Pagination": { "type": "object", "required": [ "limit", "matched", "returned", "has_more", "next_cursor" ], "properties": { "limit": { "type": "integer", "minimum": 1, "maximum": 100 }, "matched": { "type": "integer", "minimum": 0 }, "returned": { "type": "integer", "minimum": 0, "maximum": 100 }, "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ], "pattern": "^[A-Za-z0-9_-]+$", "maxLength": 2048 } }, "additionalProperties": false }, "AtlasData": { "type": "object", "required": [ "schema", "status", "query", "sources", "page", "records", "limitations" ], "properties": { "schema": { "const": "narcoscope.api.atlas.v1" }, "status": { "enum": [ "available", "partial", "unavailable" ] }, "query": { "type": "object", "required": [ "domain", "iso3", "year" ], "properties": { "domain": { "enum": [ "all", "firearms_tracing", "organized_crime" ] }, "iso3": { "type": [ "string", "null" ], "pattern": "^[A-Z]{3}$" }, "year": { "type": [ "integer", "null" ], "minimum": 1900, "maximum": 2200 } }, "additionalProperties": false }, "sources": { "type": "array", "minItems": 1, "maxItems": 2, "items": { "type": "object", "required": [ "domain", "status", "record_count", "metadata", "error" ], "properties": { "domain": { "enum": [ "firearms_tracing", "organized_crime" ] }, "status": { "enum": [ "available", "unavailable" ] }, "record_count": { "type": [ "integer", "null" ], "minimum": 0 }, "metadata": { "type": [ "object", "null" ], "additionalProperties": true }, "error": { "type": [ "object", "null" ], "additionalProperties": true } }, "additionalProperties": false } }, "page": { "$ref": "#/components/schemas/Pagination" }, "records": { "type": "array", "maxItems": 100, "items": { "type": "object", "required": [ "domain", "meta", "data" ], "properties": { "domain": { "enum": [ "firearms_tracing", "organized_crime" ] }, "meta": { "type": "object", "additionalProperties": true }, "data": { "type": "object", "additionalProperties": true } }, "additionalProperties": false } }, "limitations": { "type": "array", "minItems": 4, "items": { "type": "string", "minLength": 1 } } }, "additionalProperties": false }, "EntitiesData": { "type": "object", "required": [ "schema", "status", "query", "source", "page", "records", "disclaimer", "privacy", "error" ], "properties": { "schema": { "const": "narcoscope.api.entities.v1" }, "status": { "enum": [ "available", "unavailable" ] }, "query": { "type": "object", "required": [ "entity_type", "program", "country", "query" ], "properties": { "entity_type": { "enum": [ "aircraft", "individual", "organization", "vessel", null ] }, "program": { "enum": [ "ILLICIT-DRUGS-EO14059", "SDNT", "SDNTK", "TCO", null ] }, "country": { "type": [ "string", "null" ] }, "query": { "type": [ "string", "null" ] } }, "additionalProperties": false }, "source": { "type": [ "object", "null" ], "additionalProperties": true }, "page": { "$ref": "#/components/schemas/Pagination" }, "records": { "type": "array", "maxItems": 100, "items": { "type": "object", "required": [ "ofac_entity_number", "name", "entity_type", "programs", "countries", "meta" ], "properties": { "ofac_entity_number": { "type": "integer", "minimum": 1 }, "name": { "type": "string", "minLength": 1 }, "entity_type": { "enum": [ "aircraft", "individual", "organization", "vessel" ] }, "programs": { "type": "array", "minItems": 1, "items": { "enum": [ "ILLICIT-DRUGS-EO14059", "SDNT", "SDNTK", "TCO" ] } }, "countries": { "type": "array", "items": { "type": "string", "minLength": 1 } }, "meta": { "type": "object", "required": [ "evidence_class", "adjudication", "source", "source_url", "downloaded_at" ], "properties": { "evidence_class": { "const": "administrative_action" }, "adjudication": { "const": false }, "source": { "type": "string", "minLength": 1 }, "source_url": { "type": "string", "format": "uri", "pattern": "^https://" }, "downloaded_at": { "type": "string", "minLength": 1 } }, "additionalProperties": false } }, "additionalProperties": false } }, "disclaimer": { "type": "string", "minLength": 1 }, "privacy": { "type": "object", "required": [ "returned_fields", "withheld_fields", "query_scope" ], "properties": { "returned_fields": { "type": "array", "minItems": 5, "items": { "type": "string" } }, "withheld_fields": { "type": "array", "minItems": 5, "items": { "type": "string" } }, "query_scope": { "type": "string", "minLength": 1 } }, "additionalProperties": false }, "error": { "type": [ "object", "null" ], "additionalProperties": true } }, "additionalProperties": false }, "FederationData": { "type": "object", "required": [ "schema", "status", "retrieved_at", "query", "lanes", "policy", "limitations" ], "properties": { "schema": { "const": "narcoscope.api.federation.v1" }, "status": { "enum": [ "available", "partial", "unavailable" ] }, "retrieved_at": { "type": "string", "format": "date-time" }, "query": { "type": "object", "required": [ "lane" ], "properties": { "lane": { "enum": [ "all", "palimpsest-bri", "palimpsest-newswire-rights", "seiche-capital-markets", "seiche-global-money-atlas", "seiche-money-markets", "seiche-summary" ] } }, "additionalProperties": false }, "lanes": { "type": "array", "minItems": 1, "maxItems": 6, "items": { "type": "object", "required": [ "id", "product", "availability", "evidence_status", "upstream_schema", "upstream_status", "source_url", "retrieved_at", "clocks", "scope", "citation", "transport", "data", "error", "boundaries" ], "properties": { "id": { "type": "string", "minLength": 1 }, "product": { "enum": [ "Palimpsest", "Seiche" ] }, "availability": { "enum": [ "available", "restricted", "unavailable" ] }, "evidence_status": { "enum": [ "derived", "observed", "restricted", "structural", "unavailable" ] }, "upstream_schema": { "type": [ "string", "null" ] }, "upstream_status": { "type": [ "string", "null" ] }, "source_url": { "type": "string", "format": "uri", "pattern": "^https://" }, "retrieved_at": { "type": "string", "format": "date-time" }, "clocks": { "type": [ "object", "null" ], "additionalProperties": true }, "scope": { "type": [ "object", "null" ], "additionalProperties": true }, "citation": { "type": [ "object", "null" ], "additionalProperties": true }, "transport": { "type": [ "object", "null" ], "additionalProperties": true }, "data": { "type": [ "object", "null" ], "additionalProperties": true }, "error": { "type": [ "object", "null" ], "additionalProperties": true }, "boundaries": { "type": "array", "minItems": 2, "items": { "type": "string", "minLength": 1 } } }, "additionalProperties": false } }, "policy": { "type": "object", "required": [ "mode", "cross_lane_join", "composite_generation", "causal_inference", "culpability_inference", "missing_value_policy" ], "properties": { "mode": { "const": "read_only_parallel_context" }, "cross_lane_join": { "const": "prohibited" }, "composite_generation": { "const": "prohibited" }, "causal_inference": { "const": "prohibited" }, "culpability_inference": { "const": "prohibited" }, "missing_value_policy": { "const": "unavailable_not_zero" } }, "additionalProperties": false }, "limitations": { "type": "array", "minItems": 4, "items": { "type": "string", "minLength": 1 } } }, "additionalProperties": false }, "AtlasRestEnvelope": { "type": "object", "required": [ "ok", "resource", "data" ], "properties": { "ok": { "const": true }, "resource": { "const": "atlas" }, "data": { "$ref": "#/components/schemas/AtlasData" } }, "additionalProperties": false }, "EntitiesRestEnvelope": { "type": "object", "required": [ "ok", "resource", "data" ], "properties": { "ok": { "const": true }, "resource": { "const": "entities" }, "data": { "$ref": "#/components/schemas/EntitiesData" } }, "additionalProperties": false }, "FederationRestEnvelope": { "type": "object", "required": [ "ok", "resource", "data" ], "properties": { "ok": { "const": true }, "resource": { "const": "federation" }, "data": { "$ref": "#/components/schemas/FederationData" } }, "additionalProperties": false }, "UnavailableEnvelope": { "type": "object", "required": [ "ok", "resource", "error", "message", "data" ], "properties": { "ok": { "const": false }, "resource": { "enum": [ "atlas", "entities", "federation" ] }, "error": { "const": "unavailable" }, "message": { "type": "string", "minLength": 1 }, "data": { "oneOf": [ { "$ref": "#/components/schemas/AtlasData" }, { "$ref": "#/components/schemas/EntitiesData" }, { "$ref": "#/components/schemas/FederationData" } ] } }, "additionalProperties": false }, "Error": { "type": "object", "required": [ "ok", "error", "message" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" }, "message": { "type": "string" } }, "additionalProperties": false }, "GlobalMarketCatalog": { "type": "object", "additionalProperties": false, "required": [ "schema", "status", "generatedAt", "unavailableDatasets", "limitations", "datasets", "relatedResources" ], "properties": { "schema": { "const": "narcoscope.global-market-catalog.v1" }, "status": { "type": "string", "enum": [ "available", "partial", "unavailable" ] }, "generatedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "unavailableDatasets": { "type": "array", "items": { "type": "string", "enum": [ "global-drugs", "global-arms-economy" ] }, "maxItems": 2 }, "limitations": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 2000 }, "maxItems": 60 }, "datasets": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "id", "title", "sha256", "generatedAt", "sources", "indicators", "coverage", "limitations" ], "properties": { "id": { "type": "string", "enum": [ "global-drugs", "global-arms-economy" ] }, "title": { "type": "string", "minLength": 1, "maxLength": 240 }, "sha256": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "generatedAt": { "type": "string", "format": "date-time" }, "sources": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "id", "name", "publisher", "url", "downloadUrl", "license", "licenseUrl", "retrievedAt", "sha256", "bytes", "notes" ], "properties": { "id": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:-]{0,159}$" }, "name": { "type": "string", "minLength": 1, "maxLength": 1000 }, "publisher": { "type": "string", "minLength": 1, "maxLength": 1000 }, "url": { "type": "string", "format": "uri", "pattern": "^https://", "maxLength": 4096 }, "downloadUrl": { "type": "string", "format": "uri", "pattern": "^https://", "maxLength": 4096 }, "license": { "type": "string", "minLength": 1, "maxLength": 1000 }, "licenseUrl": { "type": "string", "format": "uri", "pattern": "^https://", "maxLength": 4096 }, "retrievedAt": { "type": "string", "format": "date-time" }, "sha256": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "bytes": { "type": "integer", "minimum": 1 }, "notes": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 2000 }, "maxItems": 60 } } }, "maxItems": 80 }, "indicators": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "id", "sourceId", "market", "label", "unit", "measureType", "description", "limitations", "featured", "coverage", "dimensions" ], "properties": { "id": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:-]{0,159}$" }, "sourceId": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:-]{0,159}$" }, "market": { "type": "string", "enum": [ "drugs", "arms", "economy" ] }, "label": { "type": "string", "minLength": 1, "maxLength": 500 }, "unit": { "type": "string", "minLength": 1, "maxLength": 500 }, "measureType": { "type": "string", "minLength": 1, "maxLength": 500 }, "description": { "type": "string", "minLength": 1, "maxLength": 2500 }, "limitations": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 2000 }, "maxItems": 60 }, "featured": { "type": "boolean" }, "coverage": { "type": "object", "additionalProperties": false, "required": [ "observations", "numericObservations", "reported", "estimated", "unavailable", "firstPeriod", "lastPeriod", "firstNumericPeriod", "lastNumericPeriod" ], "properties": { "observations": { "type": "integer", "minimum": 0 }, "numericObservations": { "type": "integer", "minimum": 0 }, "reported": { "type": "integer", "minimum": 0 }, "estimated": { "type": "integer", "minimum": 0 }, "unavailable": { "type": "integer", "minimum": 0 }, "firstPeriod": { "anyOf": [ { "type": "string", "pattern": "^(18|19|20|21)[0-9]{2}(-(0[1-9]|1[0-2]))?$" }, { "type": "null" } ] }, "lastPeriod": { "anyOf": [ { "type": "string", "pattern": "^(18|19|20|21)[0-9]{2}(-(0[1-9]|1[0-2]))?$" }, { "type": "null" } ] }, "firstNumericPeriod": { "anyOf": [ { "type": "string", "pattern": "^(18|19|20|21)[0-9]{2}(-(0[1-9]|1[0-2]))?$" }, { "type": "null" } ] }, "lastNumericPeriod": { "anyOf": [ { "type": "string", "pattern": "^(18|19|20|21)[0-9]{2}(-(0[1-9]|1[0-2]))?$" }, { "type": "null" } ] } } }, "dimensions": { "type": "object", "additionalProperties": false, "required": [ "geographies", "categories", "subgroups", "selections" ], "properties": { "geographies": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "code", "name", "level" ], "properties": { "code": { "type": "string", "minLength": 1, "maxLength": 180 }, "name": { "type": "string", "minLength": 1, "maxLength": 180 }, "level": { "type": "string", "enum": [ "country", "region", "city", "world" ] } } }, "maxItems": 500000 }, "categories": { "type": "array", "items": { "type": "string", "minLength": 0, "maxLength": 500 }, "maxItems": 500000 }, "subgroups": { "type": "array", "items": { "type": "string", "minLength": 0, "maxLength": 500 }, "maxItems": 500000 }, "selections": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "category", "subgroup", "firstPeriod", "lastPeriod", "lastNumericPeriod", "latestNumericObservations" ], "properties": { "category": { "type": "string", "minLength": 0, "maxLength": 500 }, "subgroup": { "type": "string", "minLength": 0, "maxLength": 500 }, "firstPeriod": { "anyOf": [ { "type": "string", "pattern": "^(18|19|20|21)[0-9]{2}(-(0[1-9]|1[0-2]))?$" }, { "type": "null" } ] }, "lastPeriod": { "anyOf": [ { "type": "string", "pattern": "^(18|19|20|21)[0-9]{2}(-(0[1-9]|1[0-2]))?$" }, { "type": "null" } ] }, "lastNumericPeriod": { "anyOf": [ { "type": "string", "pattern": "^(18|19|20|21)[0-9]{2}(-(0[1-9]|1[0-2]))?$" }, { "type": "null" } ] }, "latestNumericObservations": { "type": "integer", "minimum": 0 } } }, "maxItems": 500000 } } } } }, "maxItems": 500 }, "coverage": { "type": "object", "additionalProperties": false, "required": [ "observations", "numericObservations", "reported", "estimated", "unavailable", "firstPeriod", "lastPeriod", "firstNumericPeriod", "lastNumericPeriod" ], "properties": { "observations": { "type": "integer", "minimum": 0 }, "numericObservations": { "type": "integer", "minimum": 0 }, "reported": { "type": "integer", "minimum": 0 }, "estimated": { "type": "integer", "minimum": 0 }, "unavailable": { "type": "integer", "minimum": 0 }, "firstPeriod": { "anyOf": [ { "type": "string", "pattern": "^(18|19|20|21)[0-9]{2}(-(0[1-9]|1[0-2]))?$" }, { "type": "null" } ] }, "lastPeriod": { "anyOf": [ { "type": "string", "pattern": "^(18|19|20|21)[0-9]{2}(-(0[1-9]|1[0-2]))?$" }, { "type": "null" } ] }, "firstNumericPeriod": { "anyOf": [ { "type": "string", "pattern": "^(18|19|20|21)[0-9]{2}(-(0[1-9]|1[0-2]))?$" }, { "type": "null" } ] }, "lastNumericPeriod": { "anyOf": [ { "type": "string", "pattern": "^(18|19|20|21)[0-9]{2}(-(0[1-9]|1[0-2]))?$" }, { "type": "null" } ] } } }, "limitations": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 2000 }, "maxItems": 60 } } }, "maxItems": 2 }, "relatedResources": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "id", "title", "url", "description" ], "properties": { "id": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:-]{0,159}$" }, "title": { "type": "string", "minLength": 1, "maxLength": 240 }, "url": { "type": "string", "minLength": 1, "maxLength": 4096 }, "description": { "type": "string", "minLength": 1, "maxLength": 2000 } } }, "maxItems": 10 } } }, "MarketObservations": { "type": "object", "additionalProperties": false, "required": [ "schema", "status", "generatedAt", "unavailableDatasets", "limitations", "filters", "pagination", "datasets", "indicators", "sources", "observations" ], "properties": { "schema": { "const": "narcoscope.market-observations.v1" }, "status": { "type": "string", "enum": [ "available", "partial", "unavailable" ] }, "generatedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "unavailableDatasets": { "type": "array", "items": { "type": "string", "enum": [ "global-drugs", "global-arms-economy" ] }, "maxItems": 2 }, "limitations": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 2000 }, "maxItems": 60 }, "filters": { "type": "object", "additionalProperties": false, "required": [ "dataset", "indicator", "geo", "category", "subgroup", "from", "to" ], "properties": { "dataset": { "anyOf": [ { "type": "string", "enum": [ "global-drugs", "global-arms-economy" ] }, { "type": "null" } ] }, "indicator": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 160 }, { "type": "null" } ] }, "geo": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 180 }, { "type": "null" } ] }, "category": { "anyOf": [ { "type": "string", "minLength": 0, "maxLength": 500 }, { "type": "null" } ] }, "subgroup": { "anyOf": [ { "type": "string", "minLength": 0, "maxLength": 500 }, { "type": "null" } ] }, "from": { "anyOf": [ { "type": "string", "pattern": "^(18|19|20|21)[0-9]{2}(-(0[1-9]|1[0-2]))?$" }, { "type": "null" } ] }, "to": { "anyOf": [ { "type": "string", "pattern": "^(18|19|20|21)[0-9]{2}(-(0[1-9]|1[0-2]))?$" }, { "type": "null" } ] } } }, "pagination": { "type": "object", "additionalProperties": false, "required": [ "page", "limit", "total", "pages", "nextPage" ], "properties": { "page": { "type": "integer", "minimum": 1, "maximum": 1000000 }, "limit": { "type": "integer", "minimum": 1, "maximum": 500 }, "total": { "type": "integer", "minimum": 0 }, "pages": { "type": "integer", "minimum": 0 }, "nextPage": { "anyOf": [ { "type": "integer", "minimum": 2 }, { "type": "null" } ] } } }, "datasets": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "id", "sha256", "generatedAt" ], "properties": { "id": { "type": "string", "enum": [ "global-drugs", "global-arms-economy" ] }, "sha256": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "generatedAt": { "type": "string", "format": "date-time" } } }, "maxItems": 2 }, "indicators": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "id", "sourceId", "market", "label", "unit", "measureType", "description", "limitations", "datasetId" ], "properties": { "id": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:-]{0,159}$" }, "sourceId": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:-]{0,159}$" }, "market": { "type": "string", "enum": [ "drugs", "arms", "economy" ] }, "label": { "type": "string", "minLength": 1, "maxLength": 500 }, "unit": { "type": "string", "minLength": 1, "maxLength": 500 }, "measureType": { "type": "string", "minLength": 1, "maxLength": 500 }, "description": { "type": "string", "minLength": 1, "maxLength": 2500 }, "limitations": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 2000 }, "maxItems": 60 }, "datasetId": { "type": "string", "enum": [ "global-drugs", "global-arms-economy" ] } } }, "maxItems": 1000 }, "sources": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "id", "name", "publisher", "url", "downloadUrl", "license", "licenseUrl", "retrievedAt", "sha256", "bytes", "notes", "datasetId" ], "properties": { "id": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:-]{0,159}$" }, "name": { "type": "string", "minLength": 1, "maxLength": 1000 }, "publisher": { "type": "string", "minLength": 1, "maxLength": 1000 }, "url": { "type": "string", "format": "uri", "pattern": "^https://", "maxLength": 4096 }, "downloadUrl": { "type": "string", "format": "uri", "pattern": "^https://", "maxLength": 4096 }, "license": { "type": "string", "minLength": 1, "maxLength": 1000 }, "licenseUrl": { "type": "string", "format": "uri", "pattern": "^https://", "maxLength": 4096 }, "retrievedAt": { "type": "string", "format": "date-time" }, "sha256": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "bytes": { "type": "integer", "minimum": 1 }, "notes": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 2000 }, "maxItems": 60 }, "datasetId": { "type": "string", "enum": [ "global-drugs", "global-arms-economy" ] } } }, "maxItems": 160 }, "observations": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "id", "indicatorId", "geoCode", "geoName", "geoLevel", "period", "category", "subgroup", "value", "lower", "upper", "status", "sourceLocator", "datasetId", "sourceId", "unit", "measureType" ], "properties": { "id": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:-]{0,159}$" }, "indicatorId": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:-]{0,159}$" }, "geoCode": { "type": "string", "minLength": 1, "maxLength": 180 }, "geoName": { "type": "string", "minLength": 1, "maxLength": 180 }, "geoLevel": { "type": "string", "enum": [ "country", "region", "city", "world" ] }, "period": { "type": "string", "pattern": "^(18|19|20|21)[0-9]{2}(-(0[1-9]|1[0-2]))?$" }, "category": { "type": "string", "minLength": 0, "maxLength": 500 }, "subgroup": { "type": "string", "minLength": 0, "maxLength": 500 }, "value": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "lower": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "upper": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "status": { "type": "string", "enum": [ "reported", "estimated", "unavailable" ] }, "sourceLocator": { "type": "string", "minLength": 1, "maxLength": 2000 }, "datasetId": { "type": "string", "enum": [ "global-drugs", "global-arms-economy" ] }, "sourceId": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:-]{0,159}$" }, "unit": { "type": "string", "minLength": 1, "maxLength": 500 }, "measureType": { "type": "string", "minLength": 1, "maxLength": 500 } } }, "maxItems": 500 } } } }, "responses": { "Success": { "description": "Published NarcoScope artifact", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "PalimpsestBriSuccess": { "description": "Verified BRI response envelope whose data is the exact packaged artifact value", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PalimpsestBriRestEnvelope" } } } }, "AtlasSuccess": { "description": "Country-year illicit-economy atlas response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AtlasRestEnvelope" } } } }, "EntitiesSuccess": { "description": "Privacy-minimized OFAC designation response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EntitiesRestEnvelope" } } } }, "FederationSuccess": { "description": "Separate Seiche and Palimpsest evidence lanes", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FederationRestEnvelope" } } } }, "Unavailable": { "description": "Typed unavailable evidence; absence is not zero coverage", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnavailableEnvelope" } } } }, "BadRequest": { "description": "Invalid resource parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "paths": { "/capabilities": { "get": { "operationId": "listNarcoScopeCapabilities", "summary": "Discover product capabilities, access points, audiences, and safety boundaries", "responses": { "200": { "$ref": "#/components/responses/Success" } } } }, "/overview": { "get": { "operationId": "getNarcoScopeOverview", "summary": "Read bounded headline aggregates from the bundled official datasets", "responses": { "200": { "$ref": "#/components/responses/Success" } } } }, "/newsroom": { "get": { "operationId": "getNarcoScopeNewsroom", "summary": "List deterministic analyses and their publication-gate receipts", "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 25, "default": 10 } } ], "responses": { "200": { "$ref": "#/components/responses/Success" } } } }, "/story": { "get": { "operationId": "getNarcoScopeStory", "summary": "Read one newsroom story as metadata, machine brief, or cited dossier", "parameters": [ { "name": "slug", "in": "query", "required": true, "schema": { "type": "string", "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$" } }, { "name": "artifact", "in": "query", "schema": { "type": "string", "enum": [ "metadata", "machine-brief", "dossier" ], "default": "machine-brief" } } ], "responses": { "200": { "$ref": "#/components/responses/Success" }, "400": { "$ref": "#/components/responses/BadRequest" } } } }, "/palimpsest-bridge": { "get": { "operationId": "getNarcoScopePalimpsestBridge", "summary": "Read the official-only China aggregate and its claim boundaries", "responses": { "200": { "$ref": "#/components/responses/Success" } } } }, "/palimpsest-corridors": { "get": { "operationId": "getNarcoScopePalimpsestCorridors", "summary": "Read official country aggregates for China, Pakistan, and Myanmar under a geography-and-time-only join contract", "responses": { "200": { "$ref": "#/components/responses/Success" } } } }, "/palimpsest-bri": { "get": { "operationId": "getNarcoScopePalimpsestBriContext", "summary": "Read pinned BRI source readiness and national economic coverage as a parallel, non-joinable context lane", "description": "Returns CPEC, Gwadar, CMEC, Kyaukpyu, and Balochistan target readiness plus World Bank WDI country-indicator-year coverage counts. Drug-conflict-infrastructure causal joins, actor classification, bilateral route inference, guilt, political-movement classification, project attribution from national series, and tactical or navigable use are prohibited.", "responses": { "200": { "$ref": "#/components/responses/PalimpsestBriSuccess" }, "500": { "description": "The packaged artifact, sidecar, schema, or semantic boundary failed closed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/atlas": { "get": { "operationId": "getNarcoScopeIllicitEconomyAtlas", "summary": "Page country-year organized-crime and firearms-tracing observations", "description": "Returns the two source-native domains as separate records with their original metadata, per-record availability, caveats, and null-versus-zero distinction intact. The API never combines the domains into a shared score.", "parameters": [ { "name": "domain", "in": "query", "schema": { "type": "string", "enum": [ "all", "firearms_tracing", "organized_crime" ], "default": "all" } }, { "name": "iso3", "in": "query", "description": "Case-insensitive ISO 3166-1 alpha-3 country code.", "schema": { "type": "string", "pattern": "^[A-Za-z]{3}$" } }, { "name": "year", "in": "query", "schema": { "type": "integer", "minimum": 1900, "maximum": 2200 } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 } }, { "name": "cursor", "in": "query", "description": "Opaque stable keyset cursor bound to the complete filter set.", "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]+$", "maxLength": 2048 } } ], "responses": { "200": { "$ref": "#/components/responses/AtlasSuccess" }, "400": { "$ref": "#/components/responses/BadRequest" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/entities": { "get": { "operationId": "getNarcoScopePublicDesignations", "summary": "Page privacy-minimized public OFAC designation identities", "description": "Returns only stable public entity number, official name, entity type, programs, and countries. Aliases and subject-level sensitive fields are withheld. A designation is an administrative action, not proof of guilt or an adjudication.", "parameters": [ { "name": "entity_type", "in": "query", "schema": { "type": "string", "enum": [ "aircraft", "individual", "organization", "vessel" ] } }, { "name": "program", "in": "query", "schema": { "type": "string", "enum": [ "ILLICIT-DRUGS-EO14059", "SDNT", "SDNTK", "TCO" ] } }, { "name": "country", "in": "query", "description": "Exact country label after case-insensitive normalization.", "schema": { "type": "string", "minLength": 1, "maxLength": 100 } }, { "name": "query", "in": "query", "description": "Case-insensitive substring search over official names only; aliases are neither searched nor returned.", "schema": { "type": "string", "minLength": 1, "maxLength": 120 } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 } }, { "name": "cursor", "in": "query", "description": "Opaque stable keyset cursor bound to the complete filter set.", "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]+$", "maxLength": 2048 } } ], "responses": { "200": { "$ref": "#/components/responses/EntitiesSuccess" }, "400": { "$ref": "#/components/responses/BadRequest" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/federation": { "get": { "operationId": "getNarcoScopeFederatedContext", "summary": "Read separate Seiche and Palimpsest public evidence lanes", "description": "Fetches selected public Seiche world-market sections or its global money atlas with one GET, a 15-second whole-response deadline, a 2,000,000-byte ceiling, and zero retries. Palimpsest BRI and the pinned historical newswire-rights receipt remain separate lanes. Values are never joined, averaged into a composite, or used to infer causality or culpability.", "parameters": [ { "name": "lane", "in": "query", "schema": { "type": "string", "enum": [ "all", "palimpsest-bri", "palimpsest-newswire-rights", "seiche-capital-markets", "seiche-global-money-atlas", "seiche-money-markets", "seiche-summary" ], "default": "all" } } ], "responses": { "200": { "$ref": "#/components/responses/FederationSuccess" }, "400": { "$ref": "#/components/responses/BadRequest" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/connected-research": { "get": { "summary": "Connected China and regional research", "description": "Source-linked China economic findings, CPEC, Balochistan, BRI and Myanmar research questions, dated reporting and national economic indicators. Optional hash-bound China evidence observatory summaries add economic histories, EU-reported trade, methodology cases and reviewed acquisition counts. SAFE quantities remain private; gaps do not establish concealment, actor relationships or causality.", "responses": { "200": { "description": "Hash-verified packaged research snapshot", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/markets": { "get": { "operationId": "getMarketCatalog", "summary": "Discover granular drugs, arms and informal-economy evidence", "description": "Indicator-specific countries, categories, subgroups, native units, numeric and unavailable coverage, source hashes and source-specific reuse restrictions. Legacy atlas and drug histories remain linked but are not recounted.", "responses": { "200": { "description": "Source-bound published data. Partial coverage lists unavailable datasets explicitly.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "ok", "resource", "data" ], "properties": { "ok": { "const": true }, "resource": { "const": "markets" }, "data": { "$ref": "#/components/schemas/GlobalMarketCatalog" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/market-observations": { "get": { "operationId": "queryMarketObservations", "summary": "Query granular native-unit observations", "description": "Bounded source-dimension filtering with source locators, dataset hashes, exact units, uncertainty and missing values. Duplicate and unknown parameters are rejected. A valid empty query returns zero matches; missing datasets remain unavailable. Source-specific licenses remain attached.", "parameters": [ { "name": "dataset", "in": "query", "required": false, "description": "Dataset ID from the catalog. Omit to query both available datasets.", "schema": { "type": "string", "enum": [ "global-drugs", "global-arms-economy" ] } }, { "name": "indicator", "in": "query", "required": false, "description": "Exact source-native indicator ID from the catalog.", "schema": { "type": "string", "minLength": 1, "maxLength": 160 } }, { "name": "geo", "in": "query", "required": false, "description": "Exact geography code from indicator dimensions; no implicit country-name mapping.", "schema": { "type": "string", "minLength": 1, "maxLength": 180 } }, { "name": "category", "in": "query", "required": false, "description": "Exact category. Empty string matches empty categories; omitted means all.", "schema": { "type": "string", "maxLength": 500 } }, { "name": "subgroup", "in": "query", "required": false, "description": "Exact subgroup. Empty string matches empty subgroups; omitted means all.", "schema": { "type": "string", "maxLength": 500 } }, { "name": "from", "in": "query", "required": false, "description": "Inclusive first year or month. A row must fit wholly within the requested interval; annual rows are not disaggregated.", "schema": { "type": "string", "pattern": "^(18|19|20|21)[0-9]{2}(-(0[1-9]|1[0-2]))?$" } }, { "name": "to", "in": "query", "required": false, "description": "Inclusive last year or month. Native source periods are preserved.", "schema": { "type": "string", "pattern": "^(18|19|20|21)[0-9]{2}(-(0[1-9]|1[0-2]))?$" } }, { "name": "page", "in": "query", "required": false, "description": "One-based page in stable dataset/indicator/geography/category/subgroup/period order. Retain dataset hashes across pages and restart if they change.", "schema": { "type": "integer", "minimum": 1, "maximum": 1000000, "default": 1 } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum returned observations per page. No automatic market-size aggregation or unit conversion.", "schema": { "type": "integer", "minimum": 1, "maximum": 500, "default": 200 } } ], "responses": { "200": { "description": "Source-bound published data. Partial coverage lists unavailable datasets explicitly.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "ok", "resource", "data" ], "properties": { "ok": { "const": true }, "resource": { "const": "market-observations" }, "data": { "$ref": "#/components/schemas/MarketObservations" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/research-network": { "get": { "summary": "Palimpsest research catalog with separate Seiche funding context", "parameters": [ { "name": "topic", "in": "query", "schema": { "type": "string", "enum": [ "all", "china", "regions", "information_controls", "model_evaluations", "funding", "institutions", "liquidity", "global_data" ], "default": "all" } }, { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0, "maximum": 1000, "default": 0 } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 25, "default": 12 } } ], "responses": { "200": { "description": "Source-attributed connected research; preserve stale and restricted states" }, "400": { "description": "Invalid or duplicate arguments" }, "503": { "description": "Upstream unavailable or incompatible" } } } } } }