List negotiations

GET

/api/v1/negotiations

const url = 'https://example.com/api/v1/negotiations';
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/negotiations \
  --cookie bl_%3Cslug%3E_session=%3Cbl_%3Cslug%3E_session%3E

Contract negotiations as consumer and as provider, newest first.

Authorizations

session
viewer
dpop
viewer
bearer
viewer

Parameters

Query Parameters

state

string

Only processes in this state, e.g. REQUESTED.

role

string

consumer or provider.

approval

string

Negotiations only: pending, approved, rejected or expired.

limit

integer format: int64

At most this many, 1 to 1000; default 200.

Responses

200

OK.

application/json

A page of a list. next_cursor is null on the last page.

object

items

required

Array

A negotiation as the management API shows it.

object

required

string

role

required

string

Allowed values: provider consumer

state

required

string

Allowed values: INITIAL REQUESTED OFFERED ACCEPTED AGREED VERIFIED FINALIZED TERMINATED

consumer_pid

required

string

provider_pid

required

string

counterparty_did

required

string

counterparty_address

The DSP endpoint of the counterparty.

string | null

dataset_id

string | null

offer_id

string | null

offer

required

The ODRL offer as sent or received.

object

agreement_id

string | null

purpose

string | null

connection_alias

The connection (subscription) this negotiation is part of, if any.

string | null

error

string | null

history

required

The messages and states so far: at, state, message_type, direction, evidence_id, note.

Array<object>

object

created_at

required

string format: date-time

updated_at

required

string format: date-time

approval

One of:

null
string

null

expires_at

Deadline of a pending approval.

string | null format: date-time

decided_by

string | null

decided_at

string | null format: date-time

counterparty_name

The counterparty’s name in the registry of the authority.

string | null

odrl

required

The ODRL offer, as offer.

object

outbox

required

Our messages of this negotiation that are not delivered yet.

Array<object>

A row of the outbox: a message of ours to a counterparty, until it is delivered or dropped (decisions #56).

object

required

integer format: int64

process_id

required

The negotiation, transfer or delegation the message belongs to.

string

kind

required

string

message_type

required

string

counterparty_did

required

string

url

required

string

evidence_id

required

string

status

required

string

attempts

required

integer format: int32

next_attempt_at

required

string format: date-time

last_error

string | null

response_status

integer | null format: int32

created_at

required

string format: date-time

resent_at

string | null format: date-time

delivered_at

string | null format: date-time

objects

Provider, single negotiation only: the objects of the product asked for.

Array<string> | null

points

Provider, single negotiation only: the points of the product, if it names them.

Array<string> | null

narrowing

One of:

null
object

null

conflicts

Provider, single negotiation only: other consumers that already steer these objects (object, consumer_did, agreement_id).

Array<object> | null

object

next_cursor

Pass as cursor for the next page.

string | null

Example

{
  "items": [
    {
      "role": "provider",
      "state": "INITIAL",
      "approval": "pending"
    }
  ]
}

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