Change an app
const url = 'https://example.com/api/v1/apps/example';const options = { method: 'PUT', headers: { cookie: 'bl_%3Cslug%3E_session=%3Cbl_%3Cslug%3E_session%3E', 'Content-Type': 'application/json' }, body: '{"name":"example","description":"example","subscriptions":["example"],"write":true}'};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}curl --request PUT \ --url https://example.com/api/v1/apps/example \ --header 'Content-Type: application/json' \ --cookie bl_%3Cslug%3E_session=%3Cbl_%3Cslug%3E_session%3E \ --data '{ "name": "example", "description": "example", "subscriptions": [ "example" ], "write": true }'Its name, description, connections and permission; its keys stay.
Authorizations
Section titled “Authorizations”Parameters
Section titled “Parameters”Path Parameters
Section titled “Path Parameters”The id of the app.
Request Bodyrequired
Section titled “Request Bodyrequired”object
Aliases of connections; null: all, also later ones; left out: none.
Example generated
{ "name": "example", "description": "example", "subscriptions": [ "example" ], "write": true}Responses
Section titled “Responses”OK.
An app as the management API shows it.
object
The connections (aliases) it may use; null: all of them, also later ones.
It may write (steer); otherwise only read.
A key of an app, without the key itself.
object
The last four characters, to recognise it.
Single app only: what it reaches, per connection.
A connection an app reaches.
object
The gateway address of the connection.
The app may write here: it may write, and the agreement allows it.
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" }}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" }}