Locus
API reference

Locus API v0.1.0

Generated at build time from the published API contract. The wire is protobuf JSON: camelCase keys, symbolic enum names, absent fields for proto defaults. Try-it calls ride the same-origin proxy to your configured data planes; with no plane running, the network error you see is the honest state.

Resolver plane

GET/healthLiveness probe; 200 whenever the process is up (no readiness check).
Responses
200Process is alive.
GET/readyReadiness probe; 200 once reference data is warm and request control is healthy, 503 while draining or the fail-closed control plane is unavailable.
Responses
200Ready to serve.
503Draining or not yet warm.
GET/metricsEngine metrics; Prometheus text by default, JSON when format=json.
Responses
200Prometheus text metrics (v0.0.4) by default, or the JSON snapshot when format=json.
GET/metrics.jsonEngine metrics as a JSON snapshot.
Responses
200Metrics snapshot.
POST/v1/resolveResolve one raw address.
Responses
200Canonical resolve envelope (protobuf JSON, camelCase).
400Invalid request (malformed or wrong-shape JSON).
401
409
413Request body is too large.
422Address parsed to no usable key (parse_failed).
428
429
500Internal error (for example the response failed to serialize).
503Overloaded, draining, or fail-closed control plane unavailable.
POST/v1/resolve/retryRe-resolve a prior CandidateSet's addressKey with disambiguating evidence.

Single-shot retry for an address that first resolved to a CandidateSet. The client echoes the canonical addressKey and supplies at least one of the required evidence fields; a matching (key, evidence) pair resolves with status retry_resolved. An unambiguous key (no required evidence) resolves idempotently; an unmatched pair stays a CandidateSet with retryStatus evidenceNotMatched.

Responses
200Canonical resolve envelope (protobuf JSON, camelCase).
400Invalid request (blank addressKey, wrong-shape JSON, or no required evidence).
401
409
413Request body is too large.
428
429
500Internal error (for example the response failed to serialize).
503Overloaded, draining, or fail-closed control plane unavailable.
GET/v1/locations/{locationId}Dereference a minted location id to its canonical entity.

A minted id resolves to its canonical location entity: grain, status, parent link, and the entity's current address-key binding. Tombstoned ids still dereference - ids are never reused - with status telling the truth. 404 distinguishes an unknown id from a deployment without entity data provisioned.

Responses
200The canonical location entity (protobuf JSON, camelCase).
400Malformed location id (problem+json).
404Unknown location id, or entity data is not provisioned (distinct detail strings; problem+json).
503Service is warming up or draining (problem+json).

try-it needs a concrete path parameter; use the workbenches for parameterized routes

POST/v1/bulk/resolveResolve a bounded batch of raw addresses.
Responses
200Canonical batch envelope (protobuf JSON, camelCase). items[] is in request order; each item carries either the resolved ResolveResponse envelope or an RFC 9457 problem, plus its index (and id when supplied on input). count is how many items produced a resolve envelope. The top-level response stays 200 even when individual items fail.
400Invalid request (malformed body, wrong shape, or bulk limit exceeded).
401
409
413Request body is too large.
428
429
500Internal error (for example the batch response failed to serialize).
503Overloaded, draining, or fail-closed control plane unavailable.

Detail plane

GET/v1/locations/{parcelId}/detailsFull parcel_record cargo behind a resolved parcel id (every populated source column; nulls dropped server-side).

Typed error arms: not_found (routable id, no record), unroutable_parcel_id (maps to no county), integrity_refused (the key-verify gate refused a wrong row rather than serving it). x-locus-cache reports hit|miss.

Responses
200The flat parcel_record JSON, attribution riding every rendered figure.
404{"error": {"code": "not_found" | "unroutable_parcel_id" | "integrity_refused"}}

try-it needs a concrete path parameter; use the workbenches for parameterized routes

GET/v1/addresses/{addressKey}/detailsInterim address-key shim: decisive parcel behind a canonical address key (x-locus-interim disclosed).

Interim shim, disclosed via the x-locus-interim response header until the claim-graph route replaces it. no_decisive_parcel is the honest ambiguous/absent arm: the shim refuses to guess between parcels.

Responses
200parcel_record JSON; x-locus-parcel-id names the decisive parcel.
404{"error": {"code": "no_decisive_parcel"}}
501{"error": {"code": "address_lookup_unavailable"}} when the shim is not enabled.

try-it needs a concrete path parameter; use the workbenches for parameterized routes

Gateway (platform)

GET/v1/usageMetering readback: per-day, per-route, per-outcome-class rollups for the calling org (NEW gateway route).

Opaque cursor + limit pagination like every list endpoint. The gateway adds its own typed arms on every route: invalid_key, scope_missing, entitlement_missing, license_unacknowledged, rate_limited, quota_exhausted.

Responses
200Rollup rows plus a next cursor.
401{"error": {"code": "invalid_key"}}
429{"error": {"code": "rate_limited"}} with Retry-After.