Relationship: members

GET

/v1/datasets/{dataset_id}/entities/{entity}/records/{id}/relationships/{relationship}

const url = 'https://data.example.test/v1/datasets/example/entities/example/records/example/relationships/example?limit=10';
const options = {
  method: 'GET',
  headers: {
    'Data-Purpose': 'https://demo.example.gov/purpose/demo-review',
    Authorization: 'Bearer <token>'
  }
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request GET \
  --url 'https://data.example.test/v1/datasets/example/entities/example/records/example/relationships/example?limit=10' \
  --header 'Authorization: Bearer <token>' \
  --header 'Data-Purpose: https://demo.example.gov/purpose/demo-review'

Returns the members (has_many) target(s) for one household record. Foreign key: household_id.

Authorizations

bearerAuth
apiKeyAuth

Parameters

Path Parameters

required

string

Entity primary key

dataset_id

required

string

Dataset identifier

entity

required

string

Entity name

relationship

required

string

Relationship name

Query Parameters

limit

integer format: int32

>= 1

Maximum records to return. Capped by the entity’s api.max_limit.

Examples

default

cursor

string

Opaque pagination cursor returned in a prior response’s pagination.next_cursor.

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

object

data

required

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

pagination

required

object

has_more

required

True when more pages remain after this one.

boolean

next_cursor

Opaque cursor for the next page; null when has_more is false.

string | null

Example

{
  "data": [
    {
      "age": 42,
      "household_id": "01HZX9...",
      "id": "01HZX9..."
    }
  ],
  "pagination": {
    "has_more": true,
    "next_cursor": "eyJvIjoyMH0="
  }
}

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

Parent record not found, or relationship target unavailable.

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