{ "openapi": "3.1.0", "info": { "title": "CCA Corporate Entities API", "version": "0.1.0", "description": "Public, read-only corporate identity graph and intelligence API.\n\nCanonical IDs use the neutral `ecgc-<12 lowercase base36>` namespace. Legal\nform, public/private status, nonprofit status, fund status, and government\nownership are mutable, effective-dated facts and are never encoded in IDs.\n\nPublic reads are mirror-only. The service never fetches upstream records on\na request path. Every response identifies its cycle, sources, cache state,\nupstream state, response time, and known limitations.\n", "contact": { "name": "Cooperative Computing Alliance", "url": "https://coopalliance.org/" }, "license": { "name": "Source-specific public data licenses", "url": "https://corporations.datasourceapi.com/api/v1/sources" } }, "servers": [ { "url": "https://corporations.datasourceapi.com/api/v1", "description": "Production" } ], "tags": [ { "name": "Service" }, { "name": "Discovery" }, { "name": "Resolution" }, { "name": "Entities" }, { "name": "History" }, { "name": "Operations" }, { "name": "Administration" } ], "paths": { "/": { "get": { "tags": [ "Service" ], "operationId": "describeService", "summary": "Describe the service", "responses": { "200": { "$ref": "#/components/responses/Success" }, "default": { "$ref": "#/components/responses/Error" } } } }, "/health": { "get": { "tags": [ "Service" ], "operationId": "getHealth", "summary": "Process liveness and control-database probe", "responses": { "200": { "$ref": "#/components/responses/Success" }, "503": { "$ref": "#/components/responses/Error" }, "default": { "$ref": "#/components/responses/Error" } } } }, "/ready": { "get": { "tags": [ "Service" ], "operationId": "getReadiness", "summary": "Deep readiness including every configured shard", "responses": { "200": { "$ref": "#/components/responses/Success" }, "503": { "$ref": "#/components/responses/Error" }, "default": { "$ref": "#/components/responses/Error" } } } }, "/status": { "get": { "tags": [ "Service" ], "operationId": "getStatus", "summary": "Corpus, release, source, and shard-capacity status", "responses": { "200": { "$ref": "#/components/responses/Success" }, "default": { "$ref": "#/components/responses/Error" } } } }, "/capacity": { "get": { "tags": [ "Operations" ], "operationId": "getCapacity", "summary": "D1 capacity and rollover status", "description": "Every D1 database has a non-increasable 10 GB limit. This service begins\nrollover at 7.0 GB, refuses projected writes at 7.5 GB, and targets 5.0 GB\nor less after rebalancing.\n", "responses": { "200": { "$ref": "#/components/responses/Success" }, "default": { "$ref": "#/components/responses/Error" } } } }, "/limitations": { "get": { "tags": [ "Service" ], "operationId": "getLimitations", "summary": "Machine-readable data limitations", "responses": { "200": { "$ref": "#/components/responses/Success" }, "default": { "$ref": "#/components/responses/Error" } } } }, "/sources": { "get": { "tags": [ "Service" ], "operationId": "getSources", "summary": "Source catalog, licenses, cadence, and latest release", "responses": { "200": { "$ref": "#/components/responses/Success" }, "default": { "$ref": "#/components/responses/Error" } } } }, "/stats": { "get": { "tags": [ "Discovery" ], "operationId": "getStatistics", "summary": "Precomputed corpus statistics", "responses": { "200": { "$ref": "#/components/responses/Success" }, "default": { "$ref": "#/components/responses/Error" } } } }, "/analytics": { "get": { "tags": [ "Discovery" ], "operationId": "analyzeEntities", "summary": "Aggregate the current published entity projection", "parameters": [ { "name": "group_by", "in": "query", "schema": { "enum": [ "country", "region", "entity_type", "status", "sic", "naics" ], "default": "entity_type" } }, { "name": "metric", "in": "query", "schema": { "enum": [ "count", "sum_revenue", "sum_employees", "avg_employees" ], "default": "count" } }, { "$ref": "#/components/parameters/Country" }, { "$ref": "#/components/parameters/EntityType" } ], "responses": { "200": { "$ref": "#/components/responses/Success" }, "default": { "$ref": "#/components/responses/Error" } } } }, "/analytics/evidence": { "get": { "tags": [ "Discovery" ], "operationId": "getAnalyticsEvidence", "summary": "List immutable releases supporting aggregate results", "responses": { "200": { "$ref": "#/components/responses/Success" }, "default": { "$ref": "#/components/responses/Error" } } } }, "/search": { "get": { "tags": [ "Discovery" ], "operationId": "searchEntities", "summary": "Full-text corporate entity search", "parameters": [ { "$ref": "#/components/parameters/SearchQuery" }, { "$ref": "#/components/parameters/EntityType" }, { "$ref": "#/components/parameters/Country" }, { "$ref": "#/components/parameters/Region" }, { "$ref": "#/components/parameters/EntityStatus" }, { "$ref": "#/components/parameters/Limit" } ], "responses": { "200": { "description": "Search results", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Envelope" }, { "type": "object", "properties": { "data": { "type": "object", "required": [ "query", "result_count", "results" ], "properties": { "query": { "type": "string" }, "result_count": { "type": "integer" }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/EntitySummary" } } } } } } ] } } } }, "400": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/query": { "get": { "tags": [ "Discovery" ], "operationId": "queryEntities", "summary": "Filter and sort structured entity fields", "parameters": [ { "$ref": "#/components/parameters/EntityType" }, { "$ref": "#/components/parameters/Country" }, { "$ref": "#/components/parameters/Region" }, { "$ref": "#/components/parameters/EntityStatus" }, { "name": "city", "in": "query", "schema": { "type": "string" } }, { "name": "postal_code", "in": "query", "schema": { "type": "string" } }, { "name": "sic", "in": "query", "schema": { "type": "string" } }, { "name": "naics", "in": "query", "schema": { "type": "string" } }, { "name": "employees_min", "in": "query", "schema": { "type": "integer", "minimum": 0 } }, { "name": "employees_max", "in": "query", "schema": { "type": "integer", "minimum": 0 } }, { "name": "revenue_min", "in": "query", "schema": { "type": "number" } }, { "name": "revenue_max", "in": "query", "schema": { "type": "number" } }, { "name": "assets_min", "in": "query", "schema": { "type": "number" } }, { "name": "assets_max", "in": "query", "schema": { "type": "number" } }, { "name": "net_income_min", "in": "query", "schema": { "type": "number" } }, { "name": "net_income_max", "in": "query", "schema": { "type": "number" } }, { "name": "sort", "in": "query", "schema": { "enum": [ "name", "revenue", "employees", "assets", "net_income", "updated" ] } }, { "name": "order", "in": "query", "schema": { "enum": [ "asc", "desc" ] } }, { "$ref": "#/components/parameters/Limit" }, { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0, "maximum": 100 } } ], "responses": { "200": { "$ref": "#/components/responses/Success" }, "400": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/resolve/{scheme}/{value}": { "get": { "tags": [ "Resolution" ], "operationId": "resolveIdentifier", "summary": "Resolve an external identifier to a canonical entity", "parameters": [ { "name": "scheme", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/IdentifierScheme" } }, { "name": "value", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "$ref": "#/components/responses/Entity" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "description": "Identifier is ambiguous", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/domain/{domain}": { "get": { "tags": [ "Resolution" ], "operationId": "resolveDomain", "summary": "Resolve a corporate domain", "parameters": [ { "name": "domain", "in": "path", "required": true, "schema": { "type": "string", "example": "apple.com" } } ], "responses": { "200": { "$ref": "#/components/responses/Entity" }, "404": { "$ref": "#/components/responses/Error" } } } }, "/entities/{mci}": { "get": { "tags": [ "Entities" ], "operationId": "getEntity", "summary": "Get the current canonical entity bundle", "parameters": [ { "$ref": "#/components/parameters/Mci" } ], "responses": { "200": { "$ref": "#/components/responses/Entity" }, "404": { "$ref": "#/components/responses/Error" } } } }, "/companies/{mci}": { "get": { "tags": [ "Entities" ], "operationId": "getCompany", "summary": "Compatibility alias for the canonical entity bundle", "description": "Returns the same canonical legal-entity bundle as `/entities/{mci}`.", "parameters": [ { "$ref": "#/components/parameters/Mci" } ], "responses": { "200": { "$ref": "#/components/responses/Entity" }, "404": { "$ref": "#/components/responses/Error" } } } }, "/entities/{mci}/identifiers": { "get": { "tags": [ "Entities" ], "operationId": "getEntityIdentifiers", "summary": "Get active identifier claims", "parameters": [ { "$ref": "#/components/parameters/Mci" } ], "responses": { "200": { "$ref": "#/components/responses/Success" }, "default": { "$ref": "#/components/responses/Error" } } } }, "/entities/{mci}/relations": { "get": { "tags": [ "Entities" ], "operationId": "getEntityRelations", "summary": "Get effective corporate relationship claims", "parameters": [ { "$ref": "#/components/parameters/Mci" }, { "name": "type", "in": "query", "schema": { "$ref": "#/components/schemas/RelationshipType" } } ], "responses": { "200": { "$ref": "#/components/responses/Success" }, "default": { "$ref": "#/components/responses/Error" } } } }, "/entities/{mci}/tree": { "get": { "tags": [ "Entities" ], "operationId": "getEntityTree", "summary": "Traverse the effective corporate relationship graph", "parameters": [ { "$ref": "#/components/parameters/Mci" }, { "name": "direction", "in": "query", "schema": { "enum": [ "up", "down", "both" ], "default": "both" } }, { "name": "depth", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 5, "default": 3 } } ], "responses": { "200": { "$ref": "#/components/responses/Success" }, "default": { "$ref": "#/components/responses/Error" } } } }, "/entities/{mci}/financials": { "get": { "tags": [ "Entities" ], "operationId": "getEntityFinancials", "summary": "Get current financial and workforce facts", "parameters": [ { "$ref": "#/components/parameters/Mci" } ], "responses": { "200": { "$ref": "#/components/responses/Success" }, "default": { "$ref": "#/components/responses/Error" } } } }, "/entities/{mci}/xbrl": { "get": { "tags": [ "Entities" ], "operationId": "getEntityXbrlFacts", "summary": "Get normalized XBRL facts available in the current entity snapshot", "parameters": [ { "$ref": "#/components/parameters/Mci" }, { "name": "tag", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "$ref": "#/components/responses/Success" }, "default": { "$ref": "#/components/responses/Error" } } } }, "/entities/{mci}/xbrl/tags": { "get": { "tags": [ "Entities" ], "operationId": "getEntityXbrlTags", "summary": "List XBRL tags available in the current entity snapshot", "parameters": [ { "$ref": "#/components/parameters/Mci" } ], "responses": { "200": { "$ref": "#/components/responses/Success" }, "default": { "$ref": "#/components/responses/Error" } } } }, "/entities/{mci}/provenance": { "get": { "tags": [ "Entities" ], "operationId": "getEntityProvenance", "summary": "Get field and identifier provenance", "parameters": [ { "$ref": "#/components/parameters/Mci" } ], "responses": { "200": { "$ref": "#/components/responses/Success" }, "default": { "$ref": "#/components/responses/Error" } } } }, "/entities/{mci}/history": { "get": { "tags": [ "History" ], "operationId": "getEntityHistory", "summary": "List immutable versions", "parameters": [ { "$ref": "#/components/parameters/Mci" }, { "$ref": "#/components/parameters/Limit" } ], "responses": { "200": { "$ref": "#/components/responses/Success" }, "default": { "$ref": "#/components/responses/Error" } } } }, "/entities/{mci}/snapshots/{version_id}": { "get": { "tags": [ "History" ], "operationId": "getEntitySnapshot", "summary": "Get one immutable entity snapshot", "parameters": [ { "$ref": "#/components/parameters/Mci" }, { "name": "version_id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^ver-[0-9a-f]{32}$" } } ], "responses": { "200": { "$ref": "#/components/responses/Entity" }, "404": { "$ref": "#/components/responses/Error" } } } }, "/entities/{mci}/changes": { "get": { "tags": [ "History" ], "operationId": "getEntityChanges", "summary": "Get recent field changes for one entity", "parameters": [ { "$ref": "#/components/parameters/Mci" }, { "$ref": "#/components/parameters/Limit" } ], "responses": { "200": { "$ref": "#/components/responses/Success" }, "default": { "$ref": "#/components/responses/Error" } } } }, "/entities/{mci}/compare": { "get": { "tags": [ "History" ], "operationId": "compareEntityVersions", "summary": "Compare two immutable entity versions", "parameters": [ { "$ref": "#/components/parameters/Mci" }, { "name": "from", "in": "query", "required": true, "schema": { "type": "string" } }, { "name": "to", "in": "query", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "$ref": "#/components/responses/Success" }, "default": { "$ref": "#/components/responses/Error" } } } }, "/entities/{mci}/raw": { "get": { "tags": [ "History" ], "operationId": "getEntityRawReferences", "summary": "List immutable raw archive and snapshot references", "parameters": [ { "$ref": "#/components/parameters/Mci" } ], "responses": { "200": { "$ref": "#/components/responses/Success" }, "default": { "$ref": "#/components/responses/Error" } } } }, "/entities/{mci}/schools": { "get": { "tags": [ "Entities" ], "operationId": "getEntitySchools", "summary": "Resolve schools linked by authoritative EIN or domain evidence", "parameters": [ { "$ref": "#/components/parameters/Mci" } ], "responses": { "200": { "$ref": "#/components/responses/Success" }, "default": { "$ref": "#/components/responses/Error" } } } }, "/entities/{mci}/incidents": { "get": { "tags": [ "Entities" ], "operationId": "getEntityNearbyIncidents", "summary": "Get violence incidents geographically near the entity headquarters", "parameters": [ { "$ref": "#/components/parameters/Mci" }, { "$ref": "#/components/parameters/Radius" }, { "$ref": "#/components/parameters/Limit" } ], "responses": { "200": { "$ref": "#/components/responses/Success" }, "default": { "$ref": "#/components/responses/Error" } } } }, "/entities/{mci}/filings": { "get": { "tags": [ "Entities" ], "operationId": "getEntityFilingLinks", "summary": "Get direct authoritative filing links", "parameters": [ { "$ref": "#/components/parameters/Mci" } ], "responses": { "200": { "$ref": "#/components/responses/Success" }, "default": { "$ref": "#/components/responses/Error" } } } }, "/entities/{mci}/registry": { "get": { "tags": [ "Entities" ], "operationId": "getEntityRegistryLinks", "summary": "Get authoritative registration identifier references", "parameters": [ { "$ref": "#/components/parameters/Mci" } ], "responses": { "200": { "$ref": "#/components/responses/Success" }, "default": { "$ref": "#/components/responses/Error" } } } }, "/changes": { "get": { "tags": [ "History" ], "operationId": "getChanges", "summary": "Get the global recent change feed", "parameters": [ { "name": "mci", "in": "query", "schema": { "$ref": "#/components/schemas/Mci" } }, { "name": "field", "in": "query", "schema": { "type": "string" } }, { "name": "since", "in": "query", "schema": { "type": "string", "format": "date-time" } }, { "name": "until", "in": "query", "schema": { "type": "string", "format": "date-time" } }, { "name": "cursor", "in": "query", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/Limit" } ], "responses": { "200": { "$ref": "#/components/responses/Success" }, "default": { "$ref": "#/components/responses/Error" } } } }, "/changes/archives": { "get": { "tags": [ "History" ], "operationId": "getChangeArchives", "summary": "List immutable R2 pages for the permanent historical change feed", "parameters": [ { "$ref": "#/components/parameters/Limit" } ], "responses": { "200": { "$ref": "#/components/responses/Success" }, "default": { "$ref": "#/components/responses/Error" } } } }, "/nearest": { "get": { "tags": [ "Discovery" ], "operationId": "getNearestEntity", "summary": "Find the nearest known corporate location", "parameters": [ { "$ref": "#/components/parameters/Latitude" }, { "$ref": "#/components/parameters/Longitude" }, { "$ref": "#/components/parameters/Radius" } ], "responses": { "200": { "$ref": "#/components/responses/Success" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/nearby": { "get": { "tags": [ "Discovery" ], "operationId": "getNearbyEntities", "summary": "Find known corporate locations within a radius", "parameters": [ { "$ref": "#/components/parameters/Latitude" }, { "$ref": "#/components/parameters/Longitude" }, { "$ref": "#/components/parameters/Radius" }, { "$ref": "#/components/parameters/Limit" } ], "responses": { "200": { "$ref": "#/components/responses/Success" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/admin/status": { "get": { "tags": [ "Administration" ], "operationId": "getDeepStatus", "summary": "Get authenticated resource-level status and topology", "security": [ { "AdminKey": [] } ], "responses": { "200": { "$ref": "#/components/responses/Success" }, "401": { "$ref": "#/components/responses/Error" }, "default": { "$ref": "#/components/responses/Error" } } } }, "/admin/capacity": { "get": { "tags": [ "Administration" ], "operationId": "getDeepCapacity", "summary": "Get authenticated per-shard D1 capacity telemetry", "security": [ { "AdminKey": [] } ], "responses": { "200": { "$ref": "#/components/responses/Success" }, "401": { "$ref": "#/components/responses/Error" }, "default": { "$ref": "#/components/responses/Error" } } } }, "/admin/releases/start": { "post": { "tags": [ "Administration" ], "operationId": "startRelease", "security": [ { "AdminKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "release_id", "source_key", "cycle", "schema_version", "expected_count" ], "properties": { "release_id": { "type": "string" }, "source_key": { "type": "string" }, "cycle": { "type": "string" }, "schema_version": { "type": "integer", "minimum": 1 }, "expected_count": { "type": "integer", "minimum": 0 } } } } } }, "responses": { "200": { "$ref": "#/components/responses/Success" }, "401": { "$ref": "#/components/responses/Error" } } } }, "/admin/releases/{release_id}": { "get": { "tags": [ "Administration" ], "operationId": "getRelease", "security": [ { "AdminKey": [] } ], "parameters": [ { "$ref": "#/components/parameters/ReleaseId" } ], "responses": { "200": { "$ref": "#/components/responses/Success" }, "401": { "$ref": "#/components/responses/Error" } } } }, "/admin/releases/{release_id}/archive": { "post": { "tags": [ "Administration" ], "operationId": "archiveReleaseJson", "security": [ { "AdminKey": [] } ], "parameters": [ { "$ref": "#/components/parameters/ReleaseId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "kind", "data" ], "properties": { "kind": { "type": "string" }, "source_url": { "type": [ "string", "null" ], "format": "uri" }, "data": {} } } } } }, "responses": { "200": { "$ref": "#/components/responses/Success" }, "409": { "$ref": "#/components/responses/Error" } } } }, "/admin/releases/{release_id}/archive-bytes": { "put": { "tags": [ "Administration" ], "operationId": "archiveReleaseBytes", "summary": "Archive exact upstream bytes before normalization", "security": [ { "AdminKey": [] } ], "parameters": [ { "$ref": "#/components/parameters/ReleaseId" }, { "name": "kind", "in": "query", "required": true, "schema": { "type": "string" } }, { "name": "source_url", "in": "query", "schema": { "type": "string", "format": "uri" } } ], "requestBody": { "required": true, "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" } }, "application/json": { "schema": { "type": "string", "format": "binary" } } } }, "responses": { "200": { "$ref": "#/components/responses/Success" }, "409": { "$ref": "#/components/responses/Error" } } } }, "/admin/releases/{release_id}/entities": { "post": { "tags": [ "Administration" ], "operationId": "stageEntities", "security": [ { "AdminKey": [] } ], "parameters": [ { "$ref": "#/components/parameters/ReleaseId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "entities" ], "properties": { "entities": { "type": "array", "minItems": 1, "maxItems": 100, "items": { "$ref": "#/components/schemas/EntityIngest" } } } } } } }, "responses": { "200": { "$ref": "#/components/responses/Success" }, "409": { "$ref": "#/components/responses/Error" }, "503": { "description": "Capacity metrics are stale or projected storage reaches 7.5 GB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/admin/releases/{release_id}/promote": { "post": { "tags": [ "Administration" ], "operationId": "promoteRelease", "security": [ { "AdminKey": [] } ], "parameters": [ { "$ref": "#/components/parameters/ReleaseId" } ], "responses": { "200": { "$ref": "#/components/responses/Success" }, "409": { "$ref": "#/components/responses/Error" } } } }, "/admin/releases/{release_id}/abort": { "post": { "tags": [ "Administration" ], "operationId": "abortRelease", "summary": "Abort a staging release and retire its pending claims", "security": [ { "AdminKey": [] } ], "parameters": [ { "$ref": "#/components/parameters/ReleaseId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "reason" ], "properties": { "reason": { "type": "string", "maxLength": 1000 } } } } } }, "responses": { "200": { "$ref": "#/components/responses/Success" }, "409": { "$ref": "#/components/responses/Error" } } } }, "/admin/capacity/report": { "post": { "tags": [ "Administration" ], "operationId": "reportCapacity", "description": "Called by external monitoring after reading D1 GraphQL metrics.", "security": [ { "AdminKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "shards" ], "properties": { "shards": { "type": "array", "minItems": 1, "maxItems": 32, "items": { "type": "object", "required": [ "binding", "observed_bytes", "growth_bytes_per_day", "observed_at" ], "properties": { "binding": { "type": "string" }, "observed_bytes": { "type": "integer", "minimum": 0 }, "growth_bytes_per_day": { "type": "number", "minimum": 0 }, "observed_at": { "type": "string", "format": "date-time" }, "database_id": { "type": "string" } } } } } } } } }, "responses": { "200": { "$ref": "#/components/responses/Success" }, "default": { "$ref": "#/components/responses/Error" } } } } }, "components": { "securitySchemes": { "AdminKey": { "type": "apiKey", "in": "header", "name": "X-Admin-Key" } }, "parameters": { "Mci": { "name": "mci", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/Mci" } }, "ReleaseId": { "name": "release_id", "in": "path", "required": true, "schema": { "type": "string" } }, "SearchQuery": { "name": "q", "in": "query", "required": true, "schema": { "type": "string", "minLength": 2, "maxLength": 160 } }, "EntityType": { "name": "type", "in": "query", "schema": { "$ref": "#/components/schemas/EntityType" } }, "EntityStatus": { "name": "status", "in": "query", "schema": { "$ref": "#/components/schemas/EntityStatus" } }, "Country": { "name": "country", "in": "query", "schema": { "type": "string", "minLength": 2, "maxLength": 2 } }, "Region": { "name": "region", "in": "query", "schema": { "type": "string" } }, "Limit": { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 } }, "Latitude": { "name": "lat", "in": "query", "required": true, "schema": { "type": "number", "minimum": -90, "maximum": 90 } }, "Longitude": { "name": "lon", "in": "query", "required": true, "schema": { "type": "number", "minimum": -180, "maximum": 180 } }, "Radius": { "name": "radius_km", "in": "query", "schema": { "type": "number", "minimum": 0.1, "maximum": 500 } } }, "responses": { "Success": { "description": "Successful fleet envelope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" }, "examples": { "service": { "$ref": "#/components/examples/ServiceSuccess" } } } } }, "Entity": { "description": "Canonical entity bundle", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Envelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/EntityBundle" } } } ] }, "examples": { "entity": { "$ref": "#/components/examples/EntitySuccess" } } } } }, "Error": { "description": "Error fleet envelope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "notFound": { "$ref": "#/components/examples/NotFoundError" } } } } }, "RateLimited": { "description": "Request rate limit exceeded", "headers": { "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "rateLimited": { "$ref": "#/components/examples/RateLimitError" } } } } } }, "examples": { "ServiceSuccess": { "value": { "request_status": "success", "message": null, "error_code": null, "data": { "service": "cca-entities", "version": "0.1.0" }, "meta": { "request_id": "example-request", "cache": { "status": "miss", "layer": "origin", "ttl_seconds": 60 }, "upstream": { "status": "skipped", "degraded_sources": [] }, "sources": [], "cycle": null, "release": null, "as_of": "2026-09-04T00:00:00Z", "response_time_ms": 4.2, "limitations": "https://corporations.datasourceapi.com/api/v1/limitations" } } }, "EntitySuccess": { "value": { "request_status": "success", "message": null, "error_code": null, "data": { "mci": "ecgc-7xk9m2pqw4nt", "legal_name": "Example Corporation", "entity_type": "corporation", "status": "active", "cycle": "fy2025", "updated_at": "2026-09-04T00:00:00Z", "identifiers": [], "relationships": [], "workforce": { "employees": null, "employees_as_of": null, "contractor_count": null, "contractor_note": "Not reported" }, "financials": {}, "provenance": {}, "source": { "authority": "Example registry" } }, "meta": { "request_id": "example-request", "cache": { "status": "hit", "layer": "edge", "ttl_seconds": 3600 }, "upstream": { "status": "skipped", "degraded_sources": [] }, "sources": [ { "authority": "Example registry" } ], "cycle": "fy2025", "release": "example-release", "as_of": "2026-09-04T00:00:00Z", "response_time_ms": 2.1, "limitations": "https://corporations.datasourceapi.com/api/v1/limitations" } } }, "NotFoundError": { "value": { "request_status": "error", "message": "Entity was not found.", "error_code": "ERROR_NOT_FOUND", "data": null, "meta": { "request_id": "example-request", "cache": { "status": "bypass", "layer": "none", "ttl_seconds": 0 }, "upstream": { "status": "skipped", "degraded_sources": [] }, "sources": [], "cycle": null, "release": null, "as_of": "2026-09-04T00:00:00Z", "response_time_ms": 1.5, "limitations": "https://corporations.datasourceapi.com/api/v1/limitations" } } }, "RateLimitError": { "value": { "request_status": "error", "message": "Request rate limit exceeded.", "error_code": "ERROR_RATE_LIMITED", "data": null, "meta": { "request_id": "example-request", "cache": { "status": "bypass", "layer": "none", "ttl_seconds": 0 }, "upstream": { "status": "skipped", "degraded_sources": [] }, "sources": [], "cycle": null, "release": null, "as_of": "2026-09-04T00:00:00Z", "response_time_ms": 0.8, "limitations": "https://corporations.datasourceapi.com/api/v1/limitations" } } } }, "schemas": { "Mci": { "type": "string", "pattern": "^ecgc-[0-9a-z]{12}$", "example": "ecgc-7xk9m2pqw4nt" }, "EntityType": { "type": "string", "enum": [ "corporation", "nonprofit", "fund", "government-enterprise", "other" ] }, "EntityStatus": { "type": "string", "enum": [ "active", "inactive", "merged", "converted", "deregistered", "suspended", "unknown" ] }, "IdentifierScheme": { "type": "string", "enum": [ "cik", "lei", "ein", "ticker", "ticker-exchange", "domain", "state-entity", "opencorporates", "isin", "cusip", "duns", "rssd", "gvkey", "wikidata", "fortune-rank", "legacy-mci" ] }, "RelationshipType": { "type": "string", "enum": [ "parent", "ultimate-parent", "subsidiary", "branch", "predecessor", "successor", "joint-venture", "affiliate", "controls" ] }, "Source": { "type": "object", "additionalProperties": false, "required": [ "authority" ], "properties": { "authority": { "type": "string" }, "dataset": { "type": "string" }, "document": { "type": "string" }, "source_url": { "type": "string", "format": "uri" }, "retrieved_at": { "type": "string", "format": "date-time" }, "extracted_at": { "type": "string", "format": "date-time" }, "license": { "type": "string" }, "sha256": { "type": "string", "pattern": "^[0-9a-f]{64}$" } } }, "Identifier": { "type": "object", "required": [ "scheme", "value", "source" ], "properties": { "scheme": { "$ref": "#/components/schemas/IdentifierScheme" }, "value": { "type": "string" }, "confidence": { "enum": [ "authoritative", "derived", "curated", "inferred" ] }, "source": { "$ref": "#/components/schemas/Source" }, "valid_from": { "type": [ "string", "null" ] }, "valid_to": { "type": [ "string", "null" ] }, "deprecated": { "type": "boolean" }, "notes": { "type": [ "string", "null" ] } } }, "Address": { "type": "object", "properties": { "street": { "type": [ "string", "null" ] }, "city": { "type": [ "string", "null" ] }, "region": { "type": [ "string", "null" ] }, "postal_code": { "type": [ "string", "null" ] }, "country": { "type": [ "string", "null" ] }, "latitude": { "type": [ "number", "null" ] }, "longitude": { "type": [ "number", "null" ] }, "precision": { "type": [ "string", "null" ], "enum": [ "rooftop", "interpolated", "street", "postal", "place", null ] } } }, "Relationship": { "type": "object", "required": [ "type", "target_mci", "source" ], "properties": { "type": { "$ref": "#/components/schemas/RelationshipType" }, "target_mci": { "$ref": "#/components/schemas/Mci" }, "ownership_pct": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100 }, "confidence": { "enum": [ "authoritative", "derived", "curated", "inferred" ] }, "valid_from": { "type": [ "string", "null" ] }, "valid_to": { "type": [ "string", "null" ] }, "source": { "$ref": "#/components/schemas/Source" } } }, "EntitySummary": { "type": "object", "required": [ "mci", "legal_name", "entity_type", "status", "cycle", "updated_at" ], "properties": { "mci": { "$ref": "#/components/schemas/Mci" }, "legal_name": { "type": "string" }, "trade_name": { "type": [ "string", "null" ] }, "entity_type": { "$ref": "#/components/schemas/EntityType" }, "status": { "$ref": "#/components/schemas/EntityStatus" }, "city": { "type": [ "string", "null" ] }, "region": { "type": [ "string", "null" ] }, "country": { "type": [ "string", "null" ] }, "jurisdiction": { "type": [ "string", "null" ] }, "ticker": { "type": [ "string", "null" ] }, "domain": { "type": [ "string", "null" ] }, "sic": { "type": [ "string", "null" ] }, "naics": { "type": [ "string", "null" ] }, "employees": { "type": [ "integer", "null" ] }, "revenue_usd": { "type": [ "number", "null" ] }, "latitude": { "type": [ "number", "null" ] }, "longitude": { "type": [ "number", "null" ] }, "cycle": { "type": "string" }, "updated_at": { "type": "string", "format": "date-time" } } }, "EntityBundle": { "allOf": [ { "$ref": "#/components/schemas/EntitySummary" }, { "type": "object", "required": [ "identifiers", "relationships", "workforce", "financials", "provenance", "source" ], "properties": { "release_id": { "type": "string" }, "incorporation_date": { "type": [ "string", "null" ] }, "entity_form": { "type": [ "string", "null" ] }, "website": { "type": [ "string", "null" ] }, "phone": { "type": [ "string", "null" ] }, "address": { "oneOf": [ { "$ref": "#/components/schemas/Address" }, { "type": "null" } ] }, "identifiers": { "type": "array", "items": { "$ref": "#/components/schemas/Identifier" } }, "relationships": { "type": "array", "items": { "$ref": "#/components/schemas/Relationship" } }, "workforce": { "type": "object", "required": [ "employees", "employees_as_of", "contractor_count", "contractor_note" ], "properties": { "employees": { "type": [ "integer", "null" ] }, "employees_as_of": { "type": [ "string", "null" ] }, "contractor_count": { "type": "null" }, "contractor_note": { "type": "string" } } }, "financials": { "type": "object", "additionalProperties": true }, "characteristics": { "type": "object", "additionalProperties": true }, "provenance": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/Source" } }, "source": { "$ref": "#/components/schemas/Source" }, "revision": { "type": "integer", "minimum": 1 }, "snapshot_key": { "type": "string" } } } ] }, "EntityIngest": { "type": "object", "additionalProperties": true, "required": [ "legal_name", "entity_type", "status", "identifiers", "cycle", "source" ], "properties": { "mci": { "$ref": "#/components/schemas/Mci" }, "legal_name": { "type": "string", "maxLength": 512 }, "entity_type": { "$ref": "#/components/schemas/EntityType" }, "status": { "$ref": "#/components/schemas/EntityStatus" }, "identifiers": { "type": "array", "minItems": 1, "maxItems": 256, "items": { "$ref": "#/components/schemas/Identifier" } }, "relationships": { "type": "array", "maxItems": 500, "items": { "$ref": "#/components/schemas/Relationship" } }, "cycle": { "type": "string" }, "source": { "$ref": "#/components/schemas/Source" } } }, "Envelope": { "type": "object", "required": [ "request_status", "message", "error_code", "data", "meta" ], "properties": { "request_status": { "enum": [ "success", "error", "degraded" ] }, "message": { "type": [ "string", "null" ] }, "error_code": { "type": [ "string", "null" ] }, "data": { "$ref": "#/components/schemas/EnvelopeData" }, "meta": { "$ref": "#/components/schemas/Meta" } } }, "ErrorEnvelope": { "allOf": [ { "$ref": "#/components/schemas/Envelope" }, { "type": "object", "properties": { "request_status": { "const": "error" }, "data": { "type": "null" } } } ] }, "EnvelopeData": { "oneOf": [ { "type": "object", "additionalProperties": true }, { "type": "array", "items": {} }, { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" } ] }, "Meta": { "type": "object", "required": [ "request_id", "cache", "upstream", "sources", "cycle", "release", "as_of", "response_time_ms", "limitations" ], "properties": { "request_id": { "type": "string" }, "cache": { "type": "object", "required": [ "status", "layer", "ttl_seconds" ], "properties": { "status": { "enum": [ "hit", "miss", "bypass", "stale" ] }, "layer": { "enum": [ "edge", "origin", "none" ] }, "ttl_seconds": { "type": "integer" } } }, "upstream": { "type": "object", "required": [ "status", "degraded_sources" ], "properties": { "status": { "enum": [ "ok", "skipped", "degraded", "unavailable" ] }, "degraded_sources": { "type": "array", "items": { "type": "string" } } } }, "sources": { "type": "array", "items": { "$ref": "#/components/schemas/Source" } }, "cycle": { "type": [ "string", "null" ] }, "release": { "type": [ "string", "null" ] }, "as_of": { "type": "string", "format": "date-time" }, "response_time_ms": { "type": "number" }, "limitations": { "type": "string", "format": "uri" } } } } } }