Get an agreement

GET

/api/v1/agreements/{id}

const url = 'https://example.com/api/v1/agreements/example';
const options = {
  method: 'GET',
  headers: {cookie: 'bl_%3Cslug%3E_session=%3Cbl_%3Cslug%3E_session%3E'}
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

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

With its transfers, what it covers and, as provider, how it is used.

Authorizations

session
viewer
dpop
viewer
bearer
viewer

Parameters

Path Parameters

required

string

The id of the agreement.

Responses

200

OK.

application/json

An agreement as the management API shows it.

object

required

string

negotiation_id

The negotiation that closed it; none for an agreement for own use.

string | null

delegation_id

The aanwijzing an agreement for own use comes from (decisions #74).

string | null

dataset_id

required

string

provider_did

required

string

consumer_did

required

string

odrl

required

The agreement as ODRL.

object

signed_at

required

string format: date-time

role

required

provider or consumer: our side.

string

Allowed values: provider consumer

provider_name

List only.

string | null

consumer_name

List only.

string | null

negotiation_state

One of:

null
string

null

transfers

Single agreement only: its transfers (id, state, role, updated_at).

Array<object> | null

object

offer_id

string | null

revocation

Set when the provider revoked the agreement.

object | null

termination

Set when the agreement was terminated.

object | null

objects

The objects the agreement covers.

Array<string> | null

points

The points it covers; null: all points of the objects.

Array<string> | null

read_only

boolean | null

observed_from

Data from before this moment is not covered.

string | null

usage

One of:

null
object

null

Provider only: how the consumer uses the agreement (decisions #76, #77).

object

running

required

The consumer has a running transfer.

boolean

idle_since

Not running: since when; never used: since the agreement.

string | null format: date-time

counted

required

A data plane told how it was used; otherwise only running is known.

boolean

requests_24h

required

integer format: int64

failed_24h

required

integer format: int64

refused_24h

required

integer format: int64

last_request_at

string | null format: date-time

Example

{
  "role": "provider",
  "negotiation_state": "INITIAL"
}

401

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

application/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

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

application/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

Not found.

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