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'

import os, httpx

token = os.environ['REGISTRY_RELAY_TOKEN']
record_id = '...'
resp = httpx.get(
    f'http://localhost:4242/v1/datasets/social_registry/entities/household/records/{record_id}',
    headers={'Authorization': f'Bearer {token}'}
)
resp.raise_for_status()
print(resp.json())

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

Authorizations

bearerAuth
apiKeyAuth

Parameters

Path Parameters

required

string

Entity primary key

dataset_id

required

string

Dataset identifier

entity

required

string

Entity name

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

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

200

Successful response

application/json

Registered household.

object

area_geometry

Optional string field.

string | null

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

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

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

Missing or invalid bearer credential.

application/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

Authenticated principal lacks the scope required for this operation.

application/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

household record with the given primary key not found.

application/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

Problem Details error response.

application/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"
}