# Corporate Entities

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.

## Access

- Kind: api
- Audience: public
- Access: open
- Authentication: No authentication is required for documented public read operations; administration and deep operational status remain private.
- Lifecycle: beta
- Observed health: operational

## Integration links

- Base URL: https://corporations.datasourceapi.com
- Documentation: https://corporations.datasourceapi.com/api/v1/docs
- OpenAPI: https://corporations.datasourceapi.com/openapi.json
- Status: https://corporations.datasourceapi.com/api/v1/status
- Repository: https://github.com/coopalliance/cca-entities
- Catalog metadata: https://services.datasourceapi.com/api/v1/services/entities

## 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

## Provenance and freshness

- CCA Entities production contract: 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. (https://github.com/coopalliance/cca-entities/tree/b7811bec94b84f245696041cd8f1279fa2d7cd38)
- Initial SEC EDGAR release: 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. (https://corporations.datasourceapi.com/api/v1/sources)
- Published data limitations: 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. (https://corporations.datasourceapi.com/api/v1/limitations)
- Machine-readable API discovery: Live OpenAPI 3.1, HTML documentation, llms.txt, and RFC 9727 linkset describe the public read-only integration surface. (https://corporations.datasourceapi.com/.well-known/api-catalog)

Update 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.. Metadata last verified: 2026-09-04.

Governance: 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.


## Agent readiness

partial (88/100): 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.

## Examples

### Service status

Inspect the topology-safe public corpus, release, source, and capacity summary.

```http
GET https://corporations.datasourceapi.com/api/v1/status
```

### Search entities

Search the current published release for Apple and return one matching canonical entity.

```http
GET https://corporations.datasourceapi.com/api/v1/search?q=Apple&limit=1
```

### Canonical entity

Read the current canonical entity bundle for the Apple Inc. entity in the initial SEC release.

```http
GET https://corporations.datasourceapi.com/api/v1/entities/ecgc-b2psffdc85la
```

### Entity analytics

Aggregate the current published entity projection by entity type.

```http
GET https://corporations.datasourceapi.com/api/v1/analytics?group_by=entity_type&metric=count
```