{
  "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, filings, 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 following the complete initial SEC release: 8,005 entities, 28,829 identifiers, and zero rejects. 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. 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 b7811bec94b84f245696041cd8f1279fa2d7cd38 and production Worker version becef229-6c77-4424-82ff-c7b6be26ae62.",
      "url": "https://github.com/coopalliance/cca-entities/tree/b7811bec94b84f245696041cd8f1279fa2d7cd38"
    },
    {
      "name": "Initial SEC EDGAR release",
      "description": "The completed sec-edgar cycle 2026-09-02 release contains 8,005 entities and 28,829 identifiers with zero rejects; live public status reports one complete release, no active release, no open conflicts, and healthy fresh capacity below 1% on the largest database.",
      "url": "https://corporations.datasourceapi.com/api/v1/sources"
    },
    {
      "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-02, completed 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-04"
  },
  "capabilities": [
    "corporate-entity-search",
    "corporate-relations",
    "domain-resolution",
    "entity-analytics",
    "entity-history",
    "financial-facts",
    "geospatial-search",
    "identifier-resolution",
    "provenance",
    "registry-and-filing-links",
    "school-and-incident-links",
    "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"
    }
  ],
  "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": "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, operation identifiers, provenance, limitations, and topology-safe status are live. Agent use must remain source- and release-aware because version 0.1.0 is beta, only SEC EDGAR is currently populated, and documented fields may be null."
  }
}