Create an app

POST

/api/v1/apps

curl --request POST \
  --url https://example.com/api/v1/apps \
  --header 'Content-Type: application/json' \
  --cookie bl_%3Cslug%3E_session=%3Cbl_%3Cslug%3E_session%3E \
  --data '{ "name": "example", "description": "example", "subscriptions": [ "example" ], "write": true, "key": "example" }'

Creates an app with its first key, which the answer shows this once. Subscriptions left out: none; null: all of them, also later ones.

Authorizations

• session
  operator
• dpop
  operator
• bearer
  operator

Request Body^required

Media typeapplication/json

object

name

required

At most 100 characters.

string

description

At most 500 characters.

string

subscriptions

Aliases of subscriptions; null: all, also later ones; left out: none.

Array<string> | null

write

It may write (steer); otherwise only read.

boolean

key

The first key, only for automated provisioning by an admin; normally generated. At least 16 characters.

string | null

Example ^generated

{
  "name": "example",
  "description": "example",
  "subscriptions": [
    "example"
  ],
  "write": true,
  "key": "example"
}

Responses

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

null

object

Create only: the first key, shown this once.

object

id

required

string

name

required

string

key

required

Send it as Authorization: Bearer <key> to the gateway.

string

last4

string | null

created_at

Not on the key that comes with a new app.

string | null format: date-time

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

400

The request is not valid.

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

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

Only an admin may supply a 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"
  }
}

409

The supplied key already belongs to an app.

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