Skip to content
Registry StackDocsDocumentation preview
Search

Get record by id

GET
/v1/datasets/{dataset_id}/entities/{entity}/records/{id}
curl -sS \
  -H 'Authorization: Bearer $REGISTRY_RELAY_TOKEN' \
  'http://localhost:4242/v1/datasets/social_registry/entities/household/records/$ID'

Return a single household record from social_registry by primary key. Registered household.

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Path Parameters

Section titled “Path Parameters”
id
required
string

Entity primary key

dataset_id
required
string

Dataset identifier

entity
required
string

Entity name

Query Parameters

Section titled “Query Parameters”
fields
string

Comma-separated list of entity fields to project. Unknown fields are rejected.

expand
string
Allowed values: members

Comma-separated relationships to expand inline. Limited to the entity’s configured allowed_expansions.

Header Parameters

Section titled “Header Parameters”
Data-Purpose
required
string
>= 1 characters

Purpose-of-use IRI or controlled string. When require_purpose_header is set on this entity, the header must be present; a missing value returns 400 auth.purpose_required. On ordinary entity and feature routes, the value is recorded verbatim in the audit trail but is not compared to a value allowlist; Registry Notary remains the purpose-certification layer for an offering handoff. Native /v1/consultations/.../execute is separate and validates Data-Purpose against the selected consultation profile contract. Header names are case-insensitive (Data-Purpose and data-purpose are equivalent).

Example
https://demo.example.gov/purpose/demo-review
x-registry-trust-legal-basis
string
>= 1 characters

Optional PDP trust context. Relay passes this value to policy evaluation only when the authenticated principal has the exact value-bound registry:trust:legal_basis:<value> scope. Without that scope, Relay treats the header as absent. Header names are case-insensitive.

x-registry-trust-consent
string
>= 1 characters

Optional PDP trust context. Relay passes this value to policy evaluation only when the authenticated principal has the exact value-bound registry:trust:consent:<value> scope. Without that scope, Relay treats the header as absent. Header names are case-insensitive.

x-registry-trust-assurance
string
>= 1 characters

Optional PDP trust context. Relay passes this value to policy evaluation only when the authenticated principal has the exact value-bound registry:trust:assurance:<value> scope. Without that scope, Relay treats the header as absent. Header names are case-insensitive.

x-registry-trust-jurisdiction
string
>= 1 characters

Optional PDP trust context. Relay passes this value to policy evaluation only when the authenticated principal has the exact value-bound registry:trust:jurisdiction:<value> scope. Without that scope, Relay treats the header as absent. Header names are case-insensitive.

x-registry-subject-ref
string
>= 1 characters

Optional PDP trust context. Relay passes this value to policy evaluation only when the authenticated principal has the exact value-bound registry:trust:subject_ref:<value> scope. Without that scope, Relay treats the header as absent. Header names are case-insensitive.

x-registry-relationship
string
>= 1 characters

Optional PDP trust context. Relay passes this value to policy evaluation only when the authenticated principal has the exact value-bound registry:trust:relationship:<value> scope. Without that scope, Relay treats the header as absent. Header names are case-insensitive.

x-registry-on-behalf-of
string
>= 1 characters

Optional PDP trust context. Relay passes this value to policy evaluation only when the authenticated principal has the exact value-bound registry:trust:on_behalf_of:<value> scope. Without that scope, Relay treats the header as absent. Header names are case-insensitive.

x-registry-credential-format
string
>= 1 characters

Optional PDP trust context. Relay passes this value to policy evaluation only when the authenticated principal has the exact value-bound registry:trust:requested_credential_format:<value> scope. Without that scope, Relay treats the header as absent. Header names are case-insensitive.

x-registry-source-observed-at-unix-seconds
string
>= 1 characters

Optional PDP trust context. Relay passes this value to policy evaluation only when the authenticated principal has the exact value-bound registry:trust:source_observed_at_unix_seconds:<value> scope. Without that scope, Relay treats the header as absent. Header names are case-insensitive.

x-registry-source-observed-age-seconds
string
>= 1 characters

Optional PDP trust context. Relay passes this value to policy evaluation only when the authenticated principal has the exact value-bound registry:trust:source_observed_age_seconds:<value> scope. Without that scope, Relay treats the header as absent. Header names are case-insensitive.

Responses

Section titled “Responses”

200

Section titled “200”

Successful response

Media typeapplication/json

Registered household.

object
area_geometry

Optional string field.

string | null
id
required

Required string field.

string
members
Array<object>
object
age

Optional integer field.

integer | null format: int64
household

Registered household.

object
area_geometry

Optional string field.

string | null
id
required

Required string field.

string
members
Array<object> recursive
region

Optional string field. Codelist: https://example.test/vocab/codelists/Region.

string | null
household_id
required

Required string field.

string
id
required

Required string field.

string
region

Optional string field. Codelist: https://example.test/vocab/codelists/Region.

string | null
Example
{
  "area_geometry": "<area_geometry>",
  "id": "01HZX9...",
  "region": "north"
}

401

Section titled “401”

Missing or invalid bearer credential.

Media typeapplication/problem+json

RFC 9457 Problem Details, returned for every non-2xx response.

object
code
required
string
detail
required
string
request_id
required
string
status
required
integer format: int32
title
required
string
type
required
string format: uri
key
additional properties
any
Example
{
  "code": "auth.missing_credential",
  "detail": "no credential provided in Authorization or x-api-key header",
  "request_id": "01ARZ3NDEKTSV4RRFFQ69G5FAV",
  "status": 401,
  "title": "Missing credential",
  "type": "https://id.registrystack.org/problems/registry-relay/auth/missing_credential"
}

403

Section titled “403”

Authenticated principal lacks the scope required for this operation.

Media typeapplication/problem+json

RFC 9457 Problem Details, returned for every non-2xx response.

object
code
required
string
detail
required
string
request_id
required
string
status
required
integer format: int32
title
required
string
type
required
string format: uri
key
additional properties
any
Example
{
  "code": "auth.missing_credential",
  "detail": "no credential provided in Authorization or x-api-key header",
  "request_id": "01ARZ3NDEKTSV4RRFFQ69G5FAV",
  "status": 401,
  "title": "Missing credential",
  "type": "https://id.registrystack.org/problems/registry-relay/auth/missing_credential"
}

404

Section titled “404”

household record with the given primary key not found.

Media typeapplication/problem+json

RFC 9457 Problem Details, returned for every non-2xx response.

object
code
required
string
detail
required
string
request_id
required
string
status
required
integer format: int32
title
required
string
type
required
string format: uri
key
additional properties
any
Example
{
  "code": "auth.missing_credential",
  "detail": "no credential provided in Authorization or x-api-key header",
  "request_id": "01ARZ3NDEKTSV4RRFFQ69G5FAV",
  "status": 401,
  "title": "Missing credential",
  "type": "https://id.registrystack.org/problems/registry-relay/auth/missing_credential"
}

default

Section titled “default”

Problem Details error response.

Media typeapplication/problem+json

RFC 9457 Problem Details, returned for every non-2xx response.

object
code
required
string
detail
required
string
request_id
required
string
status
required
integer format: int32
title
required
string
type
required
string format: uri
key
additional properties
any
Example
{
  "code": "auth.missing_credential",
  "detail": "no credential provided in Authorization or x-api-key header",
  "request_id": "01ARZ3NDEKTSV4RRFFQ69G5FAV",
  "status": 401,
  "title": "Missing credential",
  "type": "https://id.registrystack.org/problems/registry-relay/auth/missing_credential"
}