Ga naar inhoud
buildinglinksbuildinglinks

Get a source

GET
/api/v1/sources/{id}
curl --request GET \
  --url https://example.com/api/v1/sources/example \
  --cookie bl_%3Cslug%3E_session=%3Cbl_%3Cslug%3E_session%3E

With the products that come from it. Keys are masked.

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Path Parameters

Section titled “Path Parameters”
id
required
string

The id of the source.

Responses

Section titled “Responses”

200

Section titled “200”

OK.

Media typeapplication/json

A source as the management API shows it: keys masked.

object
id
required

Left empty on create: made from the name.

string
name
required
string
protocol

buildinglinks (the Buildinglinks protocol) or generic.

string
health_path

A path that says whether the system is up, e.g. health; the system test asks it with the system’s key.

string | null
objects

Its koppelingen: the object ids (e.g. nl.bag.pand.0014100040022681) this system serves.

Array<string>
backend

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
base_url
required

The address of the system, e.g. https://bms.example.nl/api.

string
auth_header_name

The header that carries the key, e.g. X-Api-Key.

string | null
auth_header_value

The key; shown as ••••••, and sent back as such it stays as it was.

string | null
allowed_methods

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.

Array<string>
allowed_paths

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.

Array<string>
links

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
key
additional properties

How one object is reached in a system (decisions #72).

object
local_id

The system’s own id of the building; the default is the object id.

string | null
auth_header_value

A key for this building only; the default is the system’s.

string | null
provides

What the system provides for this building: data (the default), topology (the indeling, decisions #71) or both.

string | null
links

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).

Array

A koppeling as the API shows it: the object, and how it differs.

object
local_id

The system’s own id of the building; the default is the object id.

string | null
auth_header_value

A key for this building only; the default is the system’s.

string | null
provides

What the system provides for this building: data (the default), topology (the indeling, decisions #71) or both.

string | null
object
required

The object id, e.g. nl.bag.pand.0014100040022681.

string
created_at
string format: date-time
products

Single source only: the products that come from it.

Array<object> | null
object
id
required
string
title
required
string

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",
  "products": [
    {
      "id": "example",
      "title": "example"
    }
  ]
}

401

Section titled “401”

No valid session, DPoP-bound token or API key.

Media typeapplication/json

The body of every failed call to a management API.

object
error
required
object
code
required

Stable, machine-readable: invalid_request, unauthenticated, forbidden, not_found, conflict, upstream_unavailable, unavailable, internal, or a more specific code of the operation.

string
message
required

For people; may change between versions.

string

Example 

{
  "error": {
    "code": "not_found",
    "message": "unknown negotiation"
  }
}

403

Section titled “403”

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).

Media typeapplication/json

The body of every failed call to a management API.

object
error
required
object
code
required

Stable, machine-readable: invalid_request, unauthenticated, forbidden, not_found, conflict, upstream_unavailable, unavailable, internal, or a more specific code of the operation.

string
message
required

For people; may change between versions.

string

Example 

{
  "error": {
    "code": "not_found",
    "message": "unknown negotiation"
  }
}

404

Section titled “404”

Not found.

Media typeapplication/json

The body of every failed call to a management API.

object
error
required
object
code
required

Stable, machine-readable: invalid_request, unauthenticated, forbidden, not_found, conflict, upstream_unavailable, unavailable, internal, or a more specific code of the operation.

string
message
required

For people; may change between versions.

string

Example 

{
  "error": {
    "code": "not_found",
    "message": "unknown negotiation"
  }
}