Skip to content
Registry StackDocsLatest
Search

Execute a governed consultation

POST
/v1/consultations/{profile_id}/execute
curl --request POST \
  --url https://data.example.test/v1/consultations/example/execute \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Data-Purpose: example' \
  --header 'Registry-Notary-Evaluation-Id: example' \
  --data '{ "contract_hash": "sha256:0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef", "inputs": { "date_of_birth": "1990-04-12", "family_name": "Diallo", "given_name": "Amina" } }'

Executes one exact, purpose-bound, single-subject consultation for the configured authorized OIDC workload with the profile’s exact required scope. The request pins the active contract hash and supplies up to eight typed selector components. Relay returns only the profile-approved outcome, outputs on match, and closed provenance. This route does not accept a subject batch.

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Path Parameters

Section titled “Path Parameters”
profile_id
required
string
>= 1 characters <= 96 characters /^[a-z][a-z0-9._-]{0,95}$/

Exact consultation profile identifier from the protected contract catalog.

Header Parameters

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

Purpose of use. The value must match the selected profile’s purpose contract and is handled only inside the consultation authorization boundary.

Registry-Notary-Evaluation-Id
required
string
/^[0-9A-HJKMNP-TV-Z]{26}$/

Canonical uppercase ULID supplied by the authenticated Registry Notary workload to correlate this consultation with its evaluation.

Request Bodyrequired

Section titled “Request Bodyrequired”
Media typeapplication/json

The exact consultation-v1 request envelope. Contract mismatch fails before source access. The complete encoded request body is limited to 8 KiB.

object
contract_hash
required
string
/^sha256:[0-9a-f]{64}$/
inputs
required

Up to sixteen profile-defined scalar inputs, including one to eight selector-role inputs plus parameter-role inputs. Values are strings, booleans, safe JSON integers, or null where the selected profile permits null. Selector inputs have a 4096-byte aggregate canonical ceiling after profile validation. Every declared input property is required; a nullable parameter is represented by explicit JSON null. Unknown, missing, duplicate, type-mismatched, or non-nullable null inputs fail before source access.

object
>= 1 properties <= 16 properties
key
additional properties
One of:
string
<= 4096 characters
Example
{
  "contract_hash": "sha256:0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef",
  "inputs": {
    "date_of_birth": "1990-04-12",
    "family_name": "Diallo",
    "given_name": "Amina"
  }
}

Responses

Section titled “Responses”

200

Section titled “200”

Durably completed consultation result.

Media typeapplication/json
One of:
object
consultation_id
required
string
/^[0-9A-HJKMNP-TV-Z]{26}$/
notary_evaluation_id
required
string
/^[0-9A-HJKMNP-TV-Z]{26}$/
outcome
required
Allowed value: match
outputs
required
object
>= 1 properties
key
additional properties
string | integer | boolean | null
profile
required
object
contract_hash
required
string
/^sha256:[0-9a-f]{64}$/
id
required
string
/^[a-z][a-z0-9._-]{0,95}$/
provenance
required
One of:
object
acquired_at
required
string format: date-time
acquisition_class
required
Allowed values: source_projected_exact bounded_full_record
consent
required
object
checked_at
required
string | null format: date-time
expires_at
required
string | null format: date-time
outcome
required
Allowed value: not_required
revocation_status
required
Allowed value: not_applicable
verifier_id
required
string | null
<= 128 characters
verifier_revision
required
string | null
<= 128 characters
integration
required
object
id
required
string
/^[a-z][a-z0-9._-]{0,95}$/
revision
required
integer
>= 1
source_observed_at
required
string | null format: date-time
source_revision
required
string | null
<= 128 characters
schema
required
Allowed value: registry.relay.consultation-result.v1
Example
{
  "outcome": "match",
  "provenance": {
    "acquisition_class": "source_projected_exact",
    "consent": {
      "outcome": "not_required",
      "revocation_status": "not_applicable"
    }
  },
  "schema": "registry.relay.consultation-result.v1"
}

400

Section titled “400”

The consultation request is invalid. Stable code: consultation.invalid_request.

Media typeapplication/problem+json
object
code
required
string
detail
required
string
request_id
required
string
status
required
integer format: int32
title
required
string
type
required
string format: uri
code
required
Allowed value: consultation.invalid_request
status
required
Allowed value: 400
Example
{
  "code": "consultation.invalid_request",
  "detail": "no credential provided in Authorization or x-api-key header",
  "request_id": "01ARZ3NDEKTSV4RRFFQ69G5FAV",
  "status": 400,
  "title": "Missing credential",
  "type": "https://id.registrystack.org/problems/registry-relay/auth/missing_credential"
}

401

Section titled “401”

The Registry Notary OIDC credential is missing or invalid. Stable code: auth.invalid_credentials.

Media typeapplication/problem+json
object
code
required
string
detail
required
string
request_id
required
string
status
required
integer format: int32
title
required
string
type
required
string format: uri
code
required
Allowed value: auth.invalid_credentials
status
required
Allowed value: 401
Example
{
  "code": "auth.invalid_credentials",
  "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”

The authenticated workload is not permitted to perform this consultation. Stable code: consultation.denied.

Media typeapplication/problem+json
object
code
required
string
detail
required
string
request_id
required
string
status
required
integer format: int32
title
required
string
type
required
string format: uri
code
required
Allowed value: consultation.denied
status
required
Allowed value: 403
Example
{
  "code": "consultation.denied",
  "detail": "no credential provided in Authorization or x-api-key header",
  "request_id": "01ARZ3NDEKTSV4RRFFQ69G5FAV",
  "status": 403,
  "title": "Missing credential",
  "type": "https://id.registrystack.org/problems/registry-relay/auth/missing_credential"
}

404

Section titled “404”

The profile id is not visible to this workload. Stable code: consultation.profile_not_found.

Media typeapplication/problem+json
object
code
required
string
detail
required
string
request_id
required
string
status
required
integer format: int32
title
required
string
type
required
string format: uri
code
required
Allowed value: consultation.profile_not_found
status
required
Allowed value: 404
Example
{
  "code": "consultation.profile_not_found",
  "detail": "no credential provided in Authorization or x-api-key header",
  "request_id": "01ARZ3NDEKTSV4RRFFQ69G5FAV",
  "status": 404,
  "title": "Missing credential",
  "type": "https://id.registrystack.org/problems/registry-relay/auth/missing_credential"
}

409

Section titled “409”

The pinned contract hash is not active for this profile, or the authenticated Notary batch child identity conflicts with prior durable state.

Media typeapplication/problem+json
One of:
object
code
required
string
detail
required
string
request_id
required
string
status
required
integer format: int32
title
required
string
type
required
string format: uri
code
required
Allowed value: consultation.contract_mismatch
status
required
Allowed value: 409
Example
{
  "code": "consultation.contract_mismatch",
  "detail": "no credential provided in Authorization or x-api-key header",
  "request_id": "01ARZ3NDEKTSV4RRFFQ69G5FAV",
  "status": 409,
  "title": "Missing credential",
  "type": "https://id.registrystack.org/problems/registry-relay/auth/missing_credential"
}

429

Section titled “429”

The consultation quota is exhausted. Stable code: consultation.rate_limited.

Media typeapplication/problem+json
object
code
required
string
detail
required
string
request_id
required
string
status
required
integer format: int32
title
required
string
type
required
string format: uri
code
required
Allowed value: consultation.rate_limited
status
required
Allowed value: 429
Example
{
  "code": "consultation.rate_limited",
  "detail": "no credential provided in Authorization or x-api-key header",
  "request_id": "01ARZ3NDEKTSV4RRFFQ69G5FAV",
  "status": 429,
  "title": "Missing credential",
  "type": "https://id.registrystack.org/problems/registry-relay/auth/missing_credential"
}

Headers

Section titled “Headers”
Retry-After
required
integer
>= 1 <= 60

Whole seconds before retrying, bounded by the consultation-v1 public contract.

503

Section titled “503”

The consultation cannot be completed safely. Stable code: consultation.unavailable.

Media typeapplication/problem+json
object
code
required
string
detail
required
string
request_id
required
string
status
required
integer format: int32
title
required
string
type
required
string format: uri
code
required
Allowed value: consultation.unavailable
status
required
Allowed value: 503
Example
{
  "code": "consultation.unavailable",
  "detail": "no credential provided in Authorization or x-api-key header",
  "request_id": "01ARZ3NDEKTSV4RRFFQ69G5FAV",
  "status": 503,
  "title": "Missing credential",
  "type": "https://id.registrystack.org/problems/registry-relay/auth/missing_credential"
}