hook-bindings
Operations of the Capability Registry API. Paths are relative to your deployment's API host.
GET /api/capability-registry-api/hook-bindings
List the caller org's hook bindings in Spaces the caller may read.
Authentication: bearer token (Authorization: Bearer <token>)
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
hookPointId | query | string | no | Only bindings of this hook point. |
space | query | string | no | Only bindings declared in this Space: its canonical xema:// URI (the path of a returned SpaceRef). |
| Status | Description | Body |
|---|---|---|
| 200 | application/json HookBindingListDtoDataEnvelope | |
| 422 | REQUEST_VALIDATION_FAILED. | application/problem+json ProblemDetailsDto |
POST /api/capability-registry-api/hook-bindings
Create a hook binding in the caller org.
Admitted against the owner's declaration, then the handler's descriptor (an invocable record visible to the org at the expected hash), then the execute-authority rule. Any refusal is a 422 carrying every reason.
Authentication: bearer token (Authorization: Bearer <token>)
Request body: application/json CreateHookBindingDto
| Status | Description | Body |
|---|---|---|
| 200 | application/json HookBindingDtoDataEnvelope | |
| 403 | HOOK_BINDING_SPACE_NOT_PERMITTED: the caller may not manage (or read) bindings in that Space. | application/problem+json HookBindingForbiddenProblemDto |
| 409 | HOOK_BINDING_CONTENTION: the write lost to a concurrent one and was rolled back whole; retry. | application/problem+json HookBindingConflictProblemDto |
| 422 | HOOK_BINDING_REFUSED with every reason, or REQUEST_VALIDATION_FAILED. | application/problem+json HookBindingRefusedProblemDto or ProblemDetailsDto |
GET /api/capability-registry-api/hook-bindings/effective
The bindings that reach a Space: own and inherited from its ancestors.
Every binding on the Space's ancestor chain, marked own or inherited, whether it applies there (the set the owner's composer evaluates) and which suppressions stop it, with what the caller may do about each. canCreate says whether the caller may create a binding in the Space.
Authentication: bearer token (Authorization: Bearer <token>)
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
hookPointId | query | string | no | Only this hook point. |
space | query | string | yes | The Space, as its canonical xema:// URI (the path of a returned SpaceRef). |
| Status | Description | Body |
|---|---|---|
| 200 | application/json HookBindingEffectiveSetDtoDataEnvelope | |
| 403 | HOOK_BINDING_SPACE_NOT_PERMITTED: the caller may not manage (or read) bindings in that Space. | application/problem+json HookBindingForbiddenProblemDto |
| 422 | HOOK_BINDING_REFUSED (space-kind-unsupported, space-outside-org) for a Space no one can judge here, or REQUEST_VALIDATION_FAILED. HOOK_SCOPE_REFUSED when the stored suppressions do not resolve (the composer fails closed on the same set). | application/problem+json HookBindingRefusedProblemDto or HookScopeRefusedProblemDto or ProblemDetailsDto |
GET /api/capability-registry-api/hook-bindings/suppressions
List the suppressions stored at a Space.
Authentication: bearer token (Authorization: Bearer <token>)
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
hookPointId | query | string | no | Only this hook point. |
space | query | string | yes | The Space, as its canonical xema:// URI (the path of a returned SpaceRef). |
| Status | Description | Body |
|---|---|---|
| 200 | application/json HookBindingSuppressionListDtoDataEnvelope | |
| 403 | HOOK_BINDING_SPACE_NOT_PERMITTED: the caller may not manage (or read) bindings in that Space. | application/problem+json HookBindingForbiddenProblemDto |
| 422 | HOOK_BINDING_REFUSED (space-kind-unsupported, space-outside-org) for a Space no one can judge here, or REQUEST_VALIDATION_FAILED. | application/problem+json HookBindingRefusedProblemDto or ProblemDetailsDto |
PUT /api/capability-registry-api/hook-bindings/suppressions
Suppress an optional ancestor binding at a Space.
The kernel resolution runs over the stored set with the suppression; a required or unknown target is a 422 and nothing is stored. Idempotent.
Authentication: bearer token (Authorization: Bearer <token>)
Request body: application/json HookBindingSuppressionRequestDto
| Status | Description | Body |
|---|---|---|
| 200 | application/json HookBindingSuppressionDtoDataEnvelope | |
| 403 | HOOK_BINDING_SPACE_NOT_PERMITTED: the caller may not manage (or read) bindings in that Space. | application/problem+json HookBindingForbiddenProblemDto |
| 404 | HOOK_BINDING_NOT_FOUND | application/problem+json HookBindingNotFoundProblemDto |
| 409 | HOOK_BINDING_CONTENTION: the write lost to a concurrent one and was rolled back whole; retry. | application/problem+json HookBindingConflictProblemDto |
| 422 | HOOK_SCOPE_REFUSED for a required or unknown target. HOOK_BINDING_REFUSED (space-kind-unsupported, space-outside-org) for a Space no one can judge here, or REQUEST_VALIDATION_FAILED. | application/problem+json HookScopeRefusedProblemDto or HookBindingRefusedProblemDto or ProblemDetailsDto |
DELETE /api/capability-registry-api/hook-bindings/suppressions
Remove a suppression.
Authentication: bearer token (Authorization: Bearer <token>)
Request body: application/json HookBindingSuppressionRequestDto
| Status | Description | Body |
|---|---|---|
| 204 | ||
| 403 | HOOK_BINDING_SPACE_NOT_PERMITTED: the caller may not manage (or read) bindings in that Space. | application/problem+json HookBindingForbiddenProblemDto |
| 404 | HOOK_BINDING_SUPPRESSION_NOT_FOUND | application/problem+json HookBindingNotFoundProblemDto |
| 409 | HOOK_BINDING_CONTENTION: the write lost to a concurrent one and was rolled back whole; retry. | application/problem+json HookBindingConflictProblemDto |
| 422 | HOOK_BINDING_REFUSED (space-kind-unsupported, space-outside-org) for a Space no one can judge here, or REQUEST_VALIDATION_FAILED. | application/problem+json HookBindingRefusedProblemDto or ProblemDetailsDto |
GET /api/capability-registry-api/hook-bindings/{id}
Read one hook binding of the caller org.
Authentication: bearer token (Authorization: Bearer <token>)
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | yes |
| Status | Description | Body |
|---|---|---|
| 200 | application/json HookBindingDtoDataEnvelope | |
| 404 | HOOK_BINDING_NOT_FOUND | application/problem+json HookBindingNotFoundProblemDto |
DELETE /api/capability-registry-api/hook-bindings/{id}
Delete an OPTIONAL hook binding.
A required binding is a 409; removing one is the separate policy action DELETE hook-bindings/:id/required.
Authentication: bearer token (Authorization: Bearer <token>)
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | yes |
| Status | Description | Body |
|---|---|---|
| 204 | ||
| 403 | HOOK_BINDING_SPACE_NOT_PERMITTED: the caller may not manage (or read) bindings in that Space. | application/problem+json HookBindingForbiddenProblemDto |
| 404 | HOOK_BINDING_NOT_FOUND | application/problem+json HookBindingNotFoundProblemDto |
| 409 | HOOK_BINDING_REQUIRED_NEEDS_POLICY_REMOVAL, or HOOK_BINDING_CONTENTION: the write lost to a concurrent one and was rolled back whole; retry. | application/problem+json HookBindingConflictProblemDto |
POST /api/capability-registry-api/hook-bindings/{id}/authorize
Ask the owning service to originate the binding's execute delegation again.
For a binding that is awaiting (no member was present, or the owner was unreachable), or whose delegation ended or was refused. An unreachable owner or an absent member keeps the same generation; a refusal or an ended delegation asks for a new one. An owner refusal is a 422.
Authentication: bearer token (Authorization: Bearer <token>)
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | yes |
| Status | Description | Body |
|---|---|---|
| 200 | application/json HookBindingDtoDataEnvelope | |
| 403 | HOOK_BINDING_SPACE_NOT_PERMITTED: the caller may not manage (or read) bindings in that Space. | application/problem+json HookBindingForbiddenProblemDto |
| 404 | HOOK_BINDING_NOT_FOUND | application/problem+json HookBindingNotFoundProblemDto |
| 409 | HOOK_BINDING_CONTENTION: the write lost to a concurrent one and was rolled back whole; retry. | application/problem+json HookBindingConflictProblemDto |
| 422 | HOOK_BINDING_REFUSED (execute-authority-refused): the owner refused to originate the delegation. | application/problem+json HookBindingRefusedProblemDto |
DELETE /api/capability-registry-api/hook-bindings/{id}/required
Remove a REQUIRED hook binding (audited policy action).
Requires a reason. The removal and its audit record commit together; the audit journal receives the record after commit.
Authentication: bearer token (Authorization: Bearer <token>)
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | yes |
Request body: application/json RemoveRequiredHookBindingDto
| Status | Description | Body |
|---|---|---|
| 204 | ||
| 403 | ORG_ROLE_NOT_PERMITTED: the caller is not an org admin (refused by OrgRoleGuard). | application/problem+json OrgRoleForbiddenProblemDto |
| 404 | HOOK_BINDING_NOT_FOUND | application/problem+json HookBindingNotFoundProblemDto |
| 409 | HOOK_BINDING_NOT_REQUIRED, or HOOK_BINDING_CONTENTION: the write lost to a concurrent one; retry. | application/problem+json HookBindingConflictProblemDto |