Accept a delegation
const url = 'https://example.com/api/v1/delegations/example/accept';const options = { method: 'POST', headers: { cookie: 'bl_%3Cslug%3E_session=%3Cbl_%3Cslug%3E_session%3E', 'Content-Type': 'application/json' }, body: '{"backend":{"base_url":"example","auth_header_name":"example","auth_header_value":"example","allowed_methods":["example"],"allowed_paths":["example"],"links":{"additionalProperty":{"local_id":"example","auth_header_value":"example","provides":"example"}}},"source_id":"example","links":[{"local_id":"example","auth_header_value":"example","provides":"example","object":"example"}],"basis":"example","dataset":{"id":"example","title":"example","description":"example","keywords":["example"],"building_id":"example","objects":["example"],"points":["example"],"profile":"example"},"actions":["example"],"valid_until":"2026-04-15T12:00:00Z"}'};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}curl --request POST \ --url https://example.com/api/v1/delegations/example/accept \ --header 'Content-Type: application/json' \ --cookie bl_%3Cslug%3E_session=%3Cbl_%3Cslug%3E_session%3E \ --data '{ "backend": { "base_url": "example", "auth_header_name": "example", "auth_header_value": "example", "allowed_methods": [ "example" ], "allowed_paths": [ "example" ], "links": { "additionalProperty": { "local_id": "example", "auth_header_value": "example", "provides": "example" } } }, "source_id": "example", "links": [ { "local_id": "example", "auth_header_value": "example", "provides": "example", "object": "example" } ], "basis": "example", "dataset": { "id": "example", "title": "example", "description": "example", "keywords": [ "example" ], "building_id": "example", "objects": [ "example" ], "points": [ "example" ], "profile": "example" }, "actions": [ "example" ], "valid_until": "2026-04-15T12:00:00Z" }'Accepts an open request or offer to us. A supplier names the system it delivers from (source_id, and links for an own id or key per building); a rights holder accepting an offer may change the dataset as it enters the catalog. Either may narrow the actions and shorten the period.
Authorizations
Section titled “Authorizations”Parameters
Section titled “Parameters”Path Parameters
Section titled “Path Parameters”The id of the delegation (urn:uuid:…).
Request Bodyrequired
Section titled “Request Bodyrequired”object
No longer accepted: a delivery comes from a system (decisions #72).
object
The address of the system, e.g. https://bms.example.nl/api.
The header that carries the key, e.g. X-Api-Key.
The key; shown as ••••••, and sent back as such it stays as it was.
Methods the data plane lets through, e.g. ["GET"] for reading or
["GET", "POST", "PATCH"] for reading and steering. At least one: an
empty list lets nothing through.
Path patterns the data plane lets through (* one segment, ** the
rest), e.g. api/sites/4711/**, or ["**"] for the whole API. At
least one, except on a Buildinglinks system, whose koppelingen fill
them (v1/buildings/{object}/**): an empty list lets nothing through.
Koppelingen that differ from the default, per object (decisions #72): the data plane routes the building to the system’s own id and key.
object
How one object is reached in a system (decisions #72).
object
The system’s own id of the building; the default is the object id.
A key for this building only; the default is the system’s.
What the system provides for this building: data (the default),
topology (the indeling, decisions #71) or both.
Supplier: the system (source) it delivers from.
Supplier: the koppelingen of the objects in that system, when they differ.
A koppeling as the API shows it: the object, and how it differs.
object
The system’s own id of the building; the default is the object id.
A key for this building only; the default is the system’s.
What the system provides for this building: data (the default),
topology (the indeling, decisions #71) or both.
The object id, e.g. nl.bag.pand.0014100040022681.
The basis on which the supplier delivers (V1).
Rights holder accepting an offer: the dataset as it enters the catalog; fields left out keep what the supplier proposed.
object
The product id; left out: made from the title.
The objects the delivery covers (decisions #69); building_id is the
older single object.
Only these points of the objects; left out = all.
The topology profile: a delegation for the indeling (decisions #71).
May narrow the requested actions.
May shorten the requested period.
Example generated
{ "backend": { "base_url": "example", "auth_header_name": "example", "auth_header_value": "example", "allowed_methods": [ "example" ], "allowed_paths": [ "example" ], "links": { "additionalProperty": { "local_id": "example", "auth_header_value": "example", "provides": "example" } } }, "source_id": "example", "links": [ { "local_id": "example", "auth_header_value": "example", "provides": "example", "object": "example" } ], "basis": "example", "dataset": { "id": "example", "title": "example", "description": "example", "keywords": [ "example" ], "building_id": "example", "objects": [ "example" ], "points": [ "example" ], "profile": "example" }, "actions": [ "example" ], "valid_until": "2026-04-15T12:00:00Z"}Responses
Section titled “Responses”OK.
A delegation as the management API shows it: the key of a binding masked.
object
Our side: delegator (rights holder) or delegate (supplier).
Who started it (decisions #66): the rights holder asked, or the supplier offered. The other party accepts or rejects.
requested, active, suspended, rejected, revoked or expired.
The objects this erkenning en aanwijzing covers (decisions #69).
Optionally only these points of the objects; None = all.
Supplier: the own source the backend binding was taken from.
None: the data; the topology profile: the indeling (decisions #71).
The basis on which the supplier delivers, e.g. a contract (V1).
read and/or write.
The rights holder’s control plane (DPS registration).
The supplier’s data plane (DPS registration).
Supplier only; never serialised with its secret (see masked).
object
The address of the system, e.g. https://bms.example.nl/api.
The header that carries the key, e.g. X-Api-Key.
The key; shown as ••••••, and sent back as such it stays as it was.
Methods the data plane lets through, e.g. ["GET"] for reading or
["GET", "POST", "PATCH"] for reading and steering. At least one: an
empty list lets nothing through.
Path patterns the data plane lets through (* one segment, ** the
rest), e.g. api/sites/4711/**, or ["**"] for the whole API. At
least one, except on a Buildinglinks system, whose koppelingen fill
them (v1/buildings/{object}/**): an empty list lets nothing through.
Koppelingen that differ from the default, per object (decisions #72): the data plane routes the building to the system’s own id and key.
object
How one object is reached in a system (decisions #72).
object
The system’s own id of the building; the default is the object id.
A key for this building only; the default is the system’s.
What the system provides for this building: data (the default),
topology (the indeling, decisions #71) or both.
The messages and states so far: at, state, message_type,
direction, by, note, evidence_id.
object
Our messages of this delegation that are not delivered yet.
A row of the outbox: a message of ours to a counterparty, until it is delivered or dropped (decisions #56).
object
The negotiation, transfer or delegation the message belongs to.
Active and within its period.
Transfers (rights holder) or data flows (supplier) that run now.
Rights holder: how many offers the product has.
Rights holder, open offer: a product of ours with the proposed id;
reusable when its own delegation has ended.
Rights holder, single delegation: the transfers under it (id,
state, counterparty_did, counterparty_name, updated_at).
object
Supplier, single delegation: the data flows of the delivery, with
requests_24h.
object
Supplier, open request: existing bindings it could reuse (asset_id,
title, building_id, backend).
object
Example
{ "role": "delegator", "initiated_by": "delegator"}The request is not valid.
The body of every failed call to a management API.
object
object
Stable, machine-readable: invalid_request, unauthenticated,
forbidden, not_found, conflict, upstream_unavailable,
unavailable, internal, or a more specific code of the operation.
For people; may change between versions.
Example
{ "error": { "code": "not_found", "message": "unknown negotiation" }}No valid session, DPoP-bound token or API key.
The body of every failed call to a management API.
object
object
Stable, machine-readable: invalid_request, unauthenticated,
forbidden, not_found, conflict, upstream_unavailable,
unavailable, internal, or a more specific code of the operation.
For people; may change between versions.
Example
{ "error": { "code": "not_found", "message": "unknown negotiation" }}The caller lacks the role this operation needs; or a change with the session cookie came from a page of another site (cross_site_request, decisions #83).
The body of every failed call to a management API.
object
object
Stable, machine-readable: invalid_request, unauthenticated,
forbidden, not_found, conflict, upstream_unavailable,
unavailable, internal, or a more specific code of the operation.
For people; may change between versions.
Example
{ "error": { "code": "not_found", "message": "unknown negotiation" }}Not found.
The body of every failed call to a management API.
object
object
Stable, machine-readable: invalid_request, unauthenticated,
forbidden, not_found, conflict, upstream_unavailable,
unavailable, internal, or a more specific code of the operation.
For people; may change between versions.
Example
{ "error": { "code": "not_found", "message": "unknown negotiation" }}Not an open request or offer to us, or its period has ended.
The body of every failed call to a management API.
object
object
Stable, machine-readable: invalid_request, unauthenticated,
forbidden, not_found, conflict, upstream_unavailable,
unavailable, internal, or a more specific code of the operation.
For people; may change between versions.
Example
{ "error": { "code": "not_found", "message": "unknown negotiation" }}