Create a source
const url = 'https://example.com/api/v1/sources';const options = { method: 'POST', headers: { cookie: 'bl_%3Cslug%3E_session=%3Cbl_%3Cslug%3E_session%3E', 'Content-Type': 'application/json' }, body: '{"id":"example","name":"example","protocol":"example","health_path":"example","objects":["example"],"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"}}},"links":[{"local_id":"example","auth_header_value":"example","provides":"example","object":"example"}],"created_at":"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/sources \ --header 'Content-Type: application/json' \ --cookie bl_%3Cslug%3E_session=%3Cbl_%3Cslug%3E_session%3E \ --data '{ "id": "example", "name": "example", "protocol": "example", "health_path": "example", "objects": [ "example" ], "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" } } }, "links": [ { "local_id": "example", "auth_header_value": "example", "provides": "example", "object": "example" } ], "created_at": "2026-04-15T12:00:00Z" }'Sets down a system once: its address, key and protocol, and the objects it serves (its koppelingen). Koppelingen that differ from the default (an own id or key per building, or the indeling) go in links.
Authorizations
Section titled “Authorizations”Request Bodyrequired
Section titled “Request Bodyrequired”A source (in the screens: a system): a backend API of the data holder, set down once (decisions #67, #72). It may have no koppelingen yet.
object
Left empty on create: made from the name.
buildinglinks (the Buildinglinks protocol) or generic.
A path that says whether the system is up, e.g. health; the system
test asks it with the system’s key.
Its koppelingen: the object ids (e.g. nl.bag.pand.0014100040022681)
this system serves.
The binding of a dataset onto an internal API: where the data plane sends a request, with which key, and what it lets through.
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.
Its koppelingen that differ from the default: every object is one; this lists only the ones with an own id or key, or that provide more or other than data (decisions #72).
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.
Example generated
{ "id": "example", "name": "example", "protocol": "example", "health_path": "example", "objects": [ "example" ], "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" } } }, "links": [ { "local_id": "example", "auth_header_value": "example", "provides": "example", "object": "example" } ], "created_at": "2026-04-15T12:00:00Z"}Responses
Section titled “Responses”OK.
A source (in the screens: a system): a backend API of the data holder, set down once (decisions #67, #72). It may have no koppelingen yet.
object
Left empty on create: made from the name.
buildinglinks (the Buildinglinks protocol) or generic.
A path that says whether the system is up, e.g. health; the system
test asks it with the system’s key.
Its koppelingen: the object ids (e.g. nl.bag.pand.0014100040022681)
this system serves.
The binding of a dataset onto an internal API: where the data plane sends a request, with which key, and what it lets through.
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.
Its koppelingen that differ from the default: every object is one; this lists only the ones with an own id or key, or that provide more or other than data (decisions #72).
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.
Example generated
{ "id": "example", "name": "example", "protocol": "example", "health_path": "example", "objects": [ "example" ], "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" } } }, "links": [ { "local_id": "example", "auth_header_value": "example", "provides": "example", "object": "example" } ], "created_at": "2026-04-15T12:00:00Z"}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" }}A source with this id already exists.
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" }}