{
  "id": "entities",
  "name": "Corporate Entities",
  "description": "Operational beta, read-only corporate identity graph and intelligence API for canonical ecgc identifiers, resolution, provenance, relationships, financial and XBRL facts, history, analytics, the SEC EDGAR filing catalogue and archived filing documents, registries, schools, and nearby incidents.",
  "kind": "api",
  "audience": "public",
  "access": "open",
  "auth": "No authentication is required for documented public read operations; administration and deep operational status remain private.",
  "lifecycle": "beta",
  "health": "operational",
  "canonicalUrl": "https://corporations.datasourceapi.com",
  "aliases": [],
  "docsUrl": "https://corporations.datasourceapi.com/api/v1/docs",
  "docsMediaType": "text/html",
  "openapiUrl": "https://corporations.datasourceapi.com/openapi.json",
  "openapiMediaType": "application/json",
  "statusUrl": "https://corporations.datasourceapi.com/api/v1/status",
  "statusMediaType": "application/json",
  "repository": "https://github.com/coopalliance/cca-entities",
  "governanceNote": "Production version 0.1.0 remains beta but is operational: seven complete SEC releases publish 8,006 entities and 39,480 identifiers, with one open conflict and no active release. The cca-entities service owns the ecgc namespace. Public status is sanitized, topology-safe, and fresh; deep readiness, per-shard capacity, administration, and release mutation remain private. Public reads are mirror-only and release-based rather than real-time. Current populated coverage is SEC EDGAR; configured GLEIF, IRS Exempt Organizations, state registry, Wikidata, and CCA sources do not imply populated coverage. The filing catalogue indexes 18,738,157 filings, but only 14,665 filing documents are archived, so document retrieval is sparse relative to the index. Private-company financials, contractor headcount, EINs, domains, and registry fields remain incomplete, provenance-dependent, and may be null. No corpus completeness is claimed.",
  "serviceBinding": {
    "supported": false,
    "description": "No service binding is verified; the cataloged integration surface is the public read-only HTTPS API."
  },
  "provenance": [
    {
      "name": "CCA Entities production contract",
      "description": "Version 0.1.0 implementation, OpenAPI contract, aliases, documentation, llms.txt, RFC 9727 catalog, and ETag behavior verified at repository commit 5e88d1fe1c71bd08c1f5d117723292a7574a099d. The live OpenAPI document publishes 46 GET operations; deep readiness, capacity, and administration routes are deliberately excluded from this catalog.",
      "url": "https://github.com/coopalliance/cca-entities/tree/5e88d1fe1c71bd08c1f5d117723292a7574a099d"
    },
    {
      "name": "Published SEC EDGAR releases",
      "description": "Live public status verified 2026-09-08 reports seven complete releases, no active release, one open conflict, 8,006 entities, and 39,480 identifiers; the latest sec-edgar cycle is 2026-09-04 and capacity is healthy and fresh with the largest shard role at 13.79 percent of the D1 cap.",
      "url": "https://corporations.datasourceapi.com/api/v1/sources"
    },
    {
      "name": "SEC EDGAR filing catalogue coverage",
      "description": "Filing coverage reports 18,738,157 catalogued filings filed between 1993-02-11 and 2026-09-04 across eight filing shards, with 14,665 archived documents totaling about 254 GB of immutable object storage and no degraded shard.",
      "url": "https://corporations.datasourceapi.com/api/v1/filings/coverage"
    },
    {
      "name": "Published data limitations",
      "description": "Documents material and known limits for contractor headcount, private-company financials, EIN and domain coverage, registry variation, and release-based rather than real-time freshness.",
      "url": "https://corporations.datasourceapi.com/api/v1/limitations"
    },
    {
      "name": "Machine-readable API discovery",
      "description": "Live OpenAPI 3.1, HTML documentation, llms.txt, and RFC 9727 linkset describe the public read-only integration surface.",
      "url": "https://corporations.datasourceapi.com/.well-known/api-catalog"
    }
  ],
  "freshness": {
    "cadence": "The populated SEC EDGAR source is checked daily and published through immutable, release-based cycles; the current cycle is 2026-09-04. Other configured sources range from continuous and daily to weekly, monthly, as-needed, or jurisdiction-dependent and are not claimed as populated.",
    "lastVerified": "2026-09-08"
  },
  "capabilities": [
    "corporate-entity-search",
    "corporate-relations",
    "domain-resolution",
    "entity-analytics",
    "entity-history",
    "filing-documents",
    "financial-facts",
    "geospatial-search",
    "identifier-resolution",
    "provenance",
    "registry-and-filing-links",
    "school-and-incident-links",
    "sec-filings",
    "xbrl-facts"
  ],
  "examples": [
    {
      "label": "Service status",
      "description": "Inspect the topology-safe public corpus, release, source, and capacity summary.",
      "method": "GET",
      "url": "https://corporations.datasourceapi.com/api/v1/status"
    },
    {
      "label": "Search entities",
      "description": "Search the current published release for Apple and return one matching canonical entity.",
      "method": "GET",
      "url": "https://corporations.datasourceapi.com/api/v1/search?q=Apple&limit=1"
    },
    {
      "label": "Canonical entity",
      "description": "Read the current canonical entity bundle for the Apple Inc. entity in the initial SEC release.",
      "method": "GET",
      "url": "https://corporations.datasourceapi.com/api/v1/entities/ecgc-b2psffdc85la"
    },
    {
      "label": "Entity analytics",
      "description": "Aggregate the current published entity projection by entity type.",
      "method": "GET",
      "url": "https://corporations.datasourceapi.com/api/v1/analytics?group_by=entity_type&metric=count"
    },
    {
      "label": "Filing catalogue coverage",
      "description": "Report indexed filing counts, archived document coverage, and filed-date range for the SEC EDGAR catalogue.",
      "method": "GET",
      "url": "https://corporations.datasourceapi.com/api/v1/filings/coverage"
    }
  ],
  "operations": [
    {
      "operationId": "describeService",
      "summary": "Describe the service.",
      "method": "GET",
      "path": "/api/v1/"
    },
    {
      "operationId": "getHealth",
      "summary": "Get the process liveness and control-database probe.",
      "method": "GET",
      "path": "/api/v1/health"
    },
    {
      "operationId": "getStatus",
      "summary": "Get the topology-safe corpus, release, source, and capacity summary.",
      "method": "GET",
      "path": "/api/v1/status"
    },
    {
      "operationId": "getLimitations",
      "summary": "Get machine-readable data limitations.",
      "method": "GET",
      "path": "/api/v1/limitations"
    },
    {
      "operationId": "getSources",
      "summary": "Get the source catalog, licenses, cadence, and latest releases.",
      "method": "GET",
      "path": "/api/v1/sources"
    },
    {
      "operationId": "getStatistics",
      "summary": "Get precomputed corpus statistics.",
      "method": "GET",
      "path": "/api/v1/stats"
    },
    {
      "operationId": "analyzeEntities",
      "summary": "Aggregate the current published entity projection.",
      "method": "GET",
      "path": "/api/v1/analytics"
    },
    {
      "operationId": "getAnalyticsEvidence",
      "summary": "List immutable releases supporting aggregate results.",
      "method": "GET",
      "path": "/api/v1/analytics/evidence"
    },
    {
      "operationId": "searchEntities",
      "summary": "Search the current published corporate entity corpus.",
      "method": "GET",
      "path": "/api/v1/search"
    },
    {
      "operationId": "queryEntities",
      "summary": "Filter and sort structured entity fields.",
      "method": "GET",
      "path": "/api/v1/query"
    },
    {
      "operationId": "resolveIdentifier",
      "summary": "Resolve an external identifier to a canonical entity.",
      "method": "GET",
      "path": "/api/v1/resolve/{scheme}/{value}"
    },
    {
      "operationId": "resolveDomain",
      "summary": "Resolve a corporate domain.",
      "method": "GET",
      "path": "/api/v1/domain/{domain}"
    },
    {
      "operationId": "getEntity",
      "summary": "Get the current canonical entity bundle.",
      "method": "GET",
      "path": "/api/v1/entities/{mci}"
    },
    {
      "operationId": "getCompany",
      "summary": "Get the canonical entity bundle through the company compatibility alias.",
      "method": "GET",
      "path": "/api/v1/companies/{mci}"
    },
    {
      "operationId": "getEntityIdentifiers",
      "summary": "Get active identifier claims.",
      "method": "GET",
      "path": "/api/v1/entities/{mci}/identifiers"
    },
    {
      "operationId": "getEntityRelations",
      "summary": "Get effective corporate relationship claims.",
      "method": "GET",
      "path": "/api/v1/entities/{mci}/relations"
    },
    {
      "operationId": "getEntityTree",
      "summary": "Traverse the effective corporate relationship graph.",
      "method": "GET",
      "path": "/api/v1/entities/{mci}/tree"
    },
    {
      "operationId": "getEntityFinancials",
      "summary": "Get current financial and workforce facts.",
      "method": "GET",
      "path": "/api/v1/entities/{mci}/financials"
    },
    {
      "operationId": "getEntityXbrlFacts",
      "summary": "Get normalized XBRL facts in the current entity snapshot.",
      "method": "GET",
      "path": "/api/v1/entities/{mci}/xbrl"
    },
    {
      "operationId": "getEntityXbrlTags",
      "summary": "List XBRL tags in the current entity snapshot.",
      "method": "GET",
      "path": "/api/v1/entities/{mci}/xbrl/tags"
    },
    {
      "operationId": "getEntityProvenance",
      "summary": "Get field and identifier provenance.",
      "method": "GET",
      "path": "/api/v1/entities/{mci}/provenance"
    },
    {
      "operationId": "getEntityHistory",
      "summary": "List immutable versions for an entity.",
      "method": "GET",
      "path": "/api/v1/entities/{mci}/history"
    },
    {
      "operationId": "getEntitySnapshot",
      "summary": "Get one immutable entity snapshot.",
      "method": "GET",
      "path": "/api/v1/entities/{mci}/snapshots/{version_id}"
    },
    {
      "operationId": "getEntityChanges",
      "summary": "Get recent field changes for one entity.",
      "method": "GET",
      "path": "/api/v1/entities/{mci}/changes"
    },
    {
      "operationId": "compareEntityVersions",
      "summary": "Compare two immutable entity versions.",
      "method": "GET",
      "path": "/api/v1/entities/{mci}/compare"
    },
    {
      "operationId": "getEntityRawReferences",
      "summary": "List immutable raw archive and snapshot references.",
      "method": "GET",
      "path": "/api/v1/entities/{mci}/raw"
    },
    {
      "operationId": "getEntitySchools",
      "summary": "Resolve schools linked by authoritative EIN or domain evidence.",
      "method": "GET",
      "path": "/api/v1/entities/{mci}/schools"
    },
    {
      "operationId": "getEntityNearbyIncidents",
      "summary": "Get violence incidents geographically near the entity headquarters.",
      "method": "GET",
      "path": "/api/v1/entities/{mci}/incidents"
    },
    {
      "operationId": "getEntityFilingLinks",
      "summary": "Get direct authoritative filing links.",
      "method": "GET",
      "path": "/api/v1/entities/{mci}/filings"
    },
    {
      "operationId": "getEntityRegistryLinks",
      "summary": "Get authoritative registration identifier references.",
      "method": "GET",
      "path": "/api/v1/entities/{mci}/registry"
    },
    {
      "operationId": "getChanges",
      "summary": "Get the global recent change feed.",
      "method": "GET",
      "path": "/api/v1/changes"
    },
    {
      "operationId": "getChangeArchives",
      "summary": "List immutable R2 pages for the permanent historical change feed.",
      "method": "GET",
      "path": "/api/v1/changes/archives"
    },
    {
      "operationId": "queryFilings",
      "summary": "Search the complete SEC EDGAR filing catalogue.",
      "method": "GET",
      "path": "/api/v1/filings"
    },
    {
      "operationId": "searchFilings",
      "summary": "Full-text search across the filing catalogue.",
      "method": "GET",
      "path": "/api/v1/filings/search"
    },
    {
      "operationId": "filingFacets",
      "summary": "Count filings by form type or year.",
      "method": "GET",
      "path": "/api/v1/filings/facets"
    },
    {
      "operationId": "filingCoverage",
      "summary": "Report filing catalogue and document archive coverage.",
      "method": "GET",
      "path": "/api/v1/filings/coverage"
    },
    {
      "operationId": "getFiling",
      "summary": "Get one filing and its archived documents.",
      "method": "GET",
      "path": "/api/v1/filings/{accession}"
    },
    {
      "operationId": "listFilingDocuments",
      "summary": "List the archived documents for a filing.",
      "method": "GET",
      "path": "/api/v1/filings/{accession}/documents"
    },
    {
      "operationId": "getFilingDocument",
      "summary": "Download an archived filing document.",
      "method": "GET",
      "path": "/api/v1/filings/{accession}/documents/{sequence}"
    },
    {
      "operationId": "getNearestEntity",
      "summary": "Find the nearest known corporate location.",
      "method": "GET",
      "path": "/api/v1/nearest"
    },
    {
      "operationId": "getNearbyEntities",
      "summary": "Find known corporate locations within a radius.",
      "method": "GET",
      "path": "/api/v1/nearby"
    }
  ],
  "agentReadiness": {
    "level": "partial",
    "score": 88,
    "summary": "OpenAPI 3.1, HTML documentation, llms.txt, RFC 9727 discovery, examples, upstream operation identifiers, provenance, limitations, and topology-safe status are live, and 41 public read operations are cataloged. Agent use must remain source- and release-aware because version 0.1.0 is beta, only SEC EDGAR is populated, filing-document archival is sparse relative to the index, and documented fields may be null."
  }
}