Ga naar inhoud
buildinglinksbuildinglinks

Get an app

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

With what it reaches: per connection the product, the buildings, the gateway address and whether it may write there.

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Path Parameters

Section titled “Path Parameters”
id
required
string

The id of the app.

Responses

Section titled “Responses”

200

Section titled “200”

OK.

Media typeapplication/json

An app as the management API shows it.

object
id
required
string
name
required
string
description
required
string
subscriptions

The connections (aliases) it may use; null: all of them, also later ones.

Array<string> | null
write
required

It may write (steer); otherwise only read.

boolean
created_by
string | null
created_at
required
string format: date-time
keys
required
Array<object>

A key of an app, without the key itself.

object
id
required
string
name
required
string
last4

The last four characters, to recognise it.

string | null
created_at
required
string format: date-time
last_used_at
string | null format: date-time
last_used_at
string | null
reach

Single app only: what it reaches, per connection.

Array<object> | null

A connection an app reaches.

object
alias
required
string
dataset_id
required
string
dataset_title
string | null
provider_did
required
string
provider_name
string | null
state
required
string
objects
required
Array<string>
url
required

The gateway address of the connection.

string
write
required

The app may write here: it may write, and the agreement allows it.

boolean
key
One of:
null

Example generated

{
  "id": "example",
  "name": "example",
  "description": "example",
  "subscriptions": [
    "example"
  ],
  "write": true,
  "created_by": "example",
  "created_at": "2026-04-15T12:00:00Z",
  "keys": [
    {
      "id": "example",
      "name": "example",
      "last4": "example",
      "created_at": "2026-04-15T12:00:00Z",
      "last_used_at": "2026-04-15T12:00:00Z"
    }
  ],
  "last_used_at": "example",
  "reach": [
    {
      "alias": "example",
      "dataset_id": "example",
      "dataset_title": "example",
      "provider_did": "example",
      "provider_name": "example",
      "state": "example",
      "objects": [
        "example"
      ],
      "url": "example",
      "write": true
    }
  ],
  "key": {
    "id": "example",
    "name": "example",
    "key": "example",
    "last4": "example",
    "created_at": "2026-04-15T12:00:00Z"
  }
}

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"
  }
}