# REST API reference

48 public-read GET endpoints across 14 entity and framework groups. Each entity detail response carries an additive `framework_metadata` block alongside the structured record so verification posture, cap-flags, and within-cohort pair membership reach consumers without an extra request.

## Base URL

Production: `https://registry.deploy.report`. Every endpoint below sits under that origin. Responses are JSON with UTF-8 encoding.

## Authentication

The public-read GET surface documented on this page requires no authentication. The corresponding write surface (POST / PATCH / DELETE on the same paths) is gated by `x-rover-secret` for internal callers or `Authorization: Bearer <token>` for external registered consumers. Write surface is not part of this reference.

## Response conventions

- **framework_metadata block.** Every entity detail response carries `verification_status`, `maturity_stage`, `lifecycle_state`, `architectural_position`, `within_cohort_verified_vs_claimed_pair`, `cap_flags`, and `verification_depth`. Computed at query time from structured data and the framework typed-const.
- **JSON-LD inline.** Entity detail responses include a `jsonLd` field with the schema.org Organization / Product / Event / etc. shape. The custom `deploy:` namespace (see [/docs/jsonld](/docs/jsonld.md)) is the channel for verification posture and architectural classifications schema.org alone cannot express.
- **Honest absence.** Missing data returns `null` or omits the field. Tools and endpoints never synthesize defaults.
- **Status codes.** `404` means the entity does not exist; `500` means an actual server error. The registry never conflates the two; downstream consumers can branch on status code reliably.
- **Append-only history.** Trust-bearing tables (verifications, permissions, incident status events, regulation status events) ship through GET-only surfaces; corrections add new events rather than overwrite.

## Endpoints

### Companies

Companies (manufacturers, operators, brain developers, suppliers). Each entity detail response carries the framework_metadata block.

#### `GET /v1/companies`

List companies. Returns up to 100 records ordered by createdAt desc.

**Returns:** Array of company records under `companies`. Each record carries id, slug, name, type, hq, founded, fundingTotal, sources, reviewStatus, createdAt, updatedAt.

#### `GET /v1/companies/{id}`

Single company by UUID. Includes the company's schema.org JSON-LD and the additive framework_metadata block (verification_status, cap_flags, architectural_position, within_cohort pair membership, verification_depth).

**Path parameters:**

- `id` (uuid, optional): Company UUID.

**Query parameters:**

- `include` (string, optional): Comma-separated includes. `funding-rounds` eager-loads funding rounds with per-round investor participations inline. `people` eager-loads PersonCompany rows with Person identity. `founders` eager-loads PersonFounder rows. `board` eager-loads PersonBoard rows.

**Returns:** Company record fields, `jsonLd` (schema.org Organization), `framework_metadata` block, plus optional `funding_rounds` / `people` / `founders` / `board` arrays when the corresponding include is requested.

#### `GET /v1/companies/{id}/funding-rounds`

List funding rounds for a company, ordered by announcedAt desc.

**Path parameters:**

- `id` (uuid, optional): Company UUID.

**Returns:** `{ companyId, companySlug, funding_rounds: [...] }`. Each round carries roundName, announcedAt, amountUsd, postMoneyValuationUsd, amountBasis (exact / reported / undisclosed), sources, reviewStatus.

### Models

Robot models (physical machines). form_factor describes the regulatory regime, not the use case.

#### `GET /v1/models`

List models. Combine filters; companyId + formFactor + caps tokens AND together.

**Query parameters:**

- `companyId` (uuid, optional): Narrow by company.
- `formFactor` (string, optional): Narrow by form factor (humanoid / aerial / av / truck / sidewalk / wearable / biometric / maritime / surgical / construction / amr / agriculture). Accepted as `formFactor` or `form_factor`.
- `caps` (string (repeatable), optional): Capability filter tokens. Presence: `climbs_stairs`. Quantitative min/max/eq: `payload_kg:gte:10`, `range_km:lte:15`, `payload_kg:eq:35`. Multiple tokens AND together.

**Returns:** Array of model records under `models`. When `caps` is used, response also includes the parsed `filters`.

#### `GET /v1/models/{id}`

Single model by UUID. Includes schema.org JSON-LD and framework_metadata.

**Path parameters:**

- `id` (uuid, optional): Model UUID.

**Returns:** Model record, `jsonLd` (schema.org Product), `framework_metadata` block, optional `methodology` block.

#### `GET /v1/models/{id}/capabilities`

Effective capability set for a model (model-level merged with active version).

**Path parameters:**

- `id` (uuid, optional): Model UUID.

**Returns:** Array of capability records with type, key, value, source.

#### `GET /v1/models/{id}/versions`

List model versions ordered by version effective date.

**Path parameters:**

- `id` (uuid, optional): Model UUID.

**Returns:** Array of version records with version label, effectiveAt, supersededAt, sources.

#### `GET /v1/models/{id}/versions/{versionId}`

Single model version detail.

**Path parameters:**

- `id` (uuid, optional): Model UUID.
- `versionId` (uuid, optional): Version UUID.

**Returns:** Version record with version-level overrides and source attribution.

#### `GET /v1/models/{id}/versions/{versionId}/capabilities`

Capabilities scoped to a single model version.

**Path parameters:**

- `id` (uuid, optional): Model UUID.
- `versionId` (uuid, optional): Version UUID.

**Returns:** Array of version-scoped capability records.

### Brains

Software stacks that drive robot models (foundation models, AV driver stacks, surgical planners).

#### `GET /v1/brains/{id}`

Single brain by UUID. Includes schema.org JSON-LD and framework_metadata.

**Path parameters:**

- `id` (uuid, optional): Brain UUID.

**Returns:** Brain record (slug, name, kind, providerArchitecture, openness, maturityStage), `jsonLd`, `framework_metadata`.

### Deployments (Robots)

Verified named-site deployment records. `/v1/robots/*` is the legacy alias for the Deployment entity surface; the canonical entity name is Deployment.

#### `GET /v1/robots`

List deployments. Limit by query params.

**Query parameters:**

- `modelId` (uuid, optional): Narrow by model.
- `operatorId` (uuid, optional): Narrow by operator company.
- `locationId` (uuid, optional): Narrow by location.

**Returns:** Array of deployment records.

#### `GET /v1/robots/{id}`

Single deployment by UUID. Embeds model + owner + derived trust tier + derived current posture; includes schema.org JSON-LD and framework_metadata.

**Path parameters:**

- `id` (uuid, optional): Deployment UUID.

**Returns:** Deployment record with embedded model/operator/location, `derived: { trustTier, currentPosture }`, `jsonLd`, `framework_metadata`, optional `methodology`.

#### `GET /v1/robots/{id}/permissions`

Permission events on a deployment (append-only history).

**Path parameters:**

- `id` (uuid, optional): Deployment UUID.

**Returns:** Array of permission event records ordered by effectiveAt.

#### `GET /v1/robots/{id}/verifications`

Per-claim VerificationEvent history (append-only). Strongest per-claim verification surface in the registry.

**Path parameters:**

- `id` (uuid, optional): Deployment UUID.

**Returns:** Array of verification events with method, evidence, claim payload, recordedAt.

### Locations

Geographic entities (cities, counties, states, nations, sites). Each carries multi-resolution hierarchy.

#### `GET /v1/locations`

List locations.

**Returns:** Array of location records.

#### `GET /v1/locations/{id}`

Single location by UUID. Includes schema.org JSON-LD and framework_metadata.

**Path parameters:**

- `id` (uuid, optional): Location UUID.

**Returns:** Location record, `jsonLd`, `framework_metadata`, optional `methodology`.

### Incidents

Append-only incident records. Status events live alongside; current state derived from the event log. Retracted incidents are suppressed from aggregates but their canonical URL stays index/follow.

#### `GET /v1/incidents`

List incidents.

**Returns:** Array of incident records.

#### `GET /v1/incidents/{id}`

Single incident with derived status, sources, responses, status events, schema.org JSON-LD, and framework_metadata.

**Path parameters:**

- `id` (uuid, optional): Incident UUID.

**Returns:** Incident record with `derived: { status }`, `sources`, `responses`, `statusEvents`, `jsonLd`, `framework_metadata`, optional `methodology`.

#### `GET /v1/incidents/{id}/sources`

Sources for an incident, append-only.

**Path parameters:**

- `id` (uuid, optional): Incident UUID.

**Returns:** Array of source records (url, label, publishedAt, addedAt).

#### `GET /v1/incidents/{id}/status`

Status events for an incident, append-only event log.

**Path parameters:**

- `id` (uuid, optional): Incident UUID.

**Returns:** Array of IncidentStatusEvent records ordered by effectiveAt; statuses include open, corrected, retracted, disputed, closed.

#### `GET /v1/incidents/{id}/responses`

Operator and counterparty responses to an incident.

**Path parameters:**

- `id` (uuid, optional): Incident UUID.

**Returns:** Array of response records with responder, response text, recordedAt.

### Regulations

Regulatory records linked locationally (Location + form_factor). Superseded or repealed regulations stay index/follow but are suppressed from aggregates (the retracted/superseded asymmetry).

#### `GET /v1/regulations`

List regulations.

**Returns:** Array of regulation records.

#### `GET /v1/regulations/{id}`

Single regulation with derived status, sources, status events, schema.org JSON-LD, and framework_metadata.

**Path parameters:**

- `id` (uuid, optional): Regulation UUID.

**Returns:** Regulation record with `derived: { status }`, `sources`, `statusEvents`, `jsonLd`, `framework_metadata`, optional `methodology`.

#### `GET /v1/regulations/{id}/sources`

Sources for a regulation, append-only.

**Path parameters:**

- `id` (uuid, optional): Regulation UUID.

**Returns:** Array of source records.

#### `GET /v1/regulations/{id}/status`

Status events for a regulation.

**Path parameters:**

- `id` (uuid, optional): Regulation UUID.

**Returns:** Array of RegulationStatusEvent records; statuses include active, superseded, repealed.

### People graph

Founders, executives, researchers, and board members. People-graph entities (Person + PersonCompany + PersonFounder + PersonBoard + PersonInvestorRole + PersonEducation) shipped in migration 20260604140000_add_people_graph; read-only on /v1/.

#### `GET /v1/people/{slugOrId}`

Single Person with the canonical relation graph eager-loaded (current and prior company roles, foundings with cofounder status, board seats, investor partner roles, educations).

**Path parameters:**

- `slugOrId` (string, optional): Person slug (preferred) or UUID.

**Returns:** Person record + companyRoles + boardRoles + investorRoles + foundings + educations.

#### `GET /v1/people/{slugOrId}/companies`

Cross-company history for a person ('diaspora' / talent-flow view). PersonCompany rows ordered current-first.

**Path parameters:**

- `slugOrId` (string, optional): Person slug or UUID.

**Returns:** `{ personId, personSlug, companies: [...] }` with role + role_basis per row.

#### `GET /v1/companies/{id}/people`

All people at a company across PersonCompany edges (current + historical).

**Path parameters:**

- `id` (uuid, optional): Company UUID.

**Returns:** `{ companyId, companySlug, people: [...] }`. Each row carries Person identity + role + role_title + role_basis + currentRole flag.

### Investors and funding

Investor graph entities (Investor + FundingRound + InvestorParticipation). Read-only on /v1/; editorial backfill populates the corpus.

#### `GET /v1/investors/{slugOrId}`

Single investor. Accepts slug or UUID. Includes parentCompany link for corporate venture arms.

**Path parameters:**

- `slugOrId` (string, optional): Investor slug (preferred) or UUID.

**Returns:** Investor record with slug, name, kind (venture / growth / strategic_corporate / sovereign_wealth / angel / accelerator / government / other), aliases, sources, parentCompany link.

#### `GET /v1/funding-rounds/{id}`

Single funding round detail with company link. Add `?include=investors` to eager-load InvestorParticipation rows with per-investor identity.

**Path parameters:**

- `id` (uuid, optional): FundingRound UUID.

**Query parameters:**

- `include` (string, optional): `investors` eager-loads InvestorParticipation rows inline.

**Returns:** FundingRound record (roundName, announcedAt, amountUsd, postMoneyValuationUsd, amountBasis, sources), optional `participations` array.

### Owners

Owner entity records (operators distinct from manufacturers; the operator <-> deployment surface).

#### `GET /v1/owners`

List owners.

**Returns:** Array of owner records.

#### `GET /v1/owners/{id}`

Single owner detail.

**Path parameters:**

- `id` (uuid, optional): Owner UUID.

**Returns:** Owner record with linked company (when set).

### Entities (cross-type)

Cross-type entity surface for tooling. Resolves any entity type by canonical UUID; useful for agents that received a UUID without entity-type context.

#### `GET /v1/entities`

Search entities by name/slug across all entity types. Useful for autocomplete or disambiguation.

**Query parameters:**

- `q` (string, required): Search query.
- `entityType` (string, optional): Optional scope to a single entity type (company / model / brain / etc.).

**Returns:** Array of matched entities with type, id, canonicalName, slug.

#### `GET /v1/entities/{id}`

Resolve any entity by UUID. Returns the entity record and its type.

**Path parameters:**

- `id` (uuid, optional): Entity UUID.

**Returns:** `{ type, entity: {...} }`.

#### `GET /v1/entities/{id}/deployments`

Deployments related to an entity (operator OR maker OR location OR model, per entity type).

**Path parameters:**

- `id` (uuid, optional): Entity UUID.

**Returns:** Array of related deployment records.

#### `GET /v1/entities/{id}/sources`

Sources for any entity.

**Path parameters:**

- `id` (uuid, optional): Entity UUID.

**Returns:** Array of source records.

#### `GET /v1/entities/{id}/stats`

Aggregate stats for an entity (counts, latest activity).

**Path parameters:**

- `id` (uuid, optional): Entity UUID.

**Returns:** Stat object with counts of related entities and last-touched date.

### Framework surfaces (slug-keyed)

Slug-keyed reads of the framework typed-const SSoT. Slug resolves across all seven entity types; honest-absence returns null when no classification exists.

#### `GET /v1/methodology/{slug}`

Verification methodology metadata for a DEPLOY entity by slug. Same surface as v2.get_methodology MCP tool.

**Path parameters:**

- `slug` (string, optional): Entity slug.

**Returns:** Methodology block (verification_posture, confidence_tier, source_tier_breakdown, last_reviewed, re_verify_trigger, cap_flags, architectural_position, within_cohort_verified_vs_claimed_pair) plus entity identity.

#### `GET /v1/sagas/{entity_slug}`

Within-entity sagas + feature references for an entity (SAME-entity feature-scope verification posture variance over time / across regions).

**Path parameters:**

- `entity_slug` (string, optional): DEPLOY entity slug.

**Returns:** `{ entity_slug, sagas: [...], featureReferences: [...] }`. Empty arrays when entity has no registered sagas / feature refs (honest absence).

#### `GET /v1/taxonomies/autonomy-boundary`

The four-tier autonomy-boundary taxonomy (autonomous-execution / ai-augmented-operator-controlled / replacement-robotics-teleoperated / assistive-co-pilot) with per-tier definitions, verification criteria, drift patterns, cohort applicability, editorial reference, canonical examples.

**Returns:** Taxonomy block with framework_schema_version, taxonomy slug, count, tiers array.

#### `GET /v1/taxonomies/brain-provider-architecture`

The four-tier brain-provider-architecture taxonomy (captive-vertically-integrated / third-party-foundation-model / hybrid-licensed / research-only).

**Returns:** Taxonomy block with per-tier definitions and canonical examples.

#### `GET /v1/taxonomies/source-quality`

The source-quality tier rubric (primary-sec-filing, primary-fda-database, primary-regulatory-filing, primary-government-record, primary-company-ir, primary-academic-peer-reviewed, ..., secondary-established-publication, secondary-industry-publication, secondary-trade-publication, knowledge-base, code-repository, model-repository, preprint, aggregator, unclassified) plus the sourceName-aware classifier convention.

**Returns:** Taxonomy block with tier list (slug, label, description, rollup_category) and source_name_convention block.

### Corrections journal

Append-only corrections log sourced from IncidentStatusEvent and RegulationStatusEvent rows. Same data as the /corrections HTML surface and v2.list_corrections MCP tool.

#### `GET /v1/corrections`

Public corrections journal.

**Query parameters:**

- `since_date` (string (ISO date), optional): Filter to corrections with effectiveAt >= this date.
- `entity_slug` (string, optional): Filter to a specific incident or regulation slug.
- `limit` (number, optional): Max results (default 100, max 500).

**Returns:** Array of correction entries with date, record_type, record_headline, record_url, status, reason, source_of_correction.

### Auxiliary surfaces

Indexability inspection, capability vocabulary, economics aggregates, feed configuration, and webhook registry.

#### `GET /v1/indexability`

Live counts of which entities qualify for the SEO indexing gate per entity type. Useful for inspecting the indexing-decoupled-from-API surface.

**Returns:** Object with per-entity-type pass / hold-back counts.

#### `GET /v1/capabilities`

The capability vocabulary (capability keys + value types + descriptions).

**Returns:** Array of capability definitions.

#### `GET /v1/economics`

Aggregate economic indicators across the registry.

**Returns:** Object with aggregate counts and economic signals.

#### `GET /v1/feeds`

Feed registry (per-entity RSS + firehose configuration).

**Returns:** Array of feed records.

#### `GET /v1/webhooks`

Webhook registry (auth-gated).

**Returns:** Array of webhook records.

## See also

- [/docs](/docs.md): the API documentation landing.
- [/docs/mcp](/docs/mcp.md): MCP tool catalog (20 tools across V1 retrieval and V2 framework analysis).
- [/docs/jsonld](/docs/jsonld.md): JSON-LD `deploy:` namespace vocabulary.

_Canonical URL: /docs/v1. HTML version: [/docs/v1](/docs/v1)._