Start a negotiation

POST

/api/v1/negotiations

curl --request POST \
  --url https://example.com/api/v1/negotiations \
  --header 'Content-Type: application/json' \
  --cookie bl_%3Cslug%3E_session=%3Cbl_%3Cslug%3E_session%3E \
  --data '{ "counterparty_did": "example", "counterparty_address": "example", "dataset_id": "example", "offer_id": "example", "purpose": "example" }'

As consumer: requests an offer from a provider’s catalog. The provider may need an operator to approve, so the negotiation can stay REQUESTED for a while; it ends FINALIZED with an agreement or TERMINATED.

Authorizations

• session
  operator
• dpop
  operator
• bearer
  operator

Request Body^required

Media typeapplication/json

object

counterparty_did

required

The provider.

string

counterparty_address

The provider’s DSP endpoint; default: as the registry of the authority has it.

string | null

dataset_id

required

The dataset (product) in the provider’s catalog.

string

offer_id

required

The offer of that dataset to accept.

string

purpose

The purpose of the use, e.g. bl:climate_control: one the offer allows. Left out: the offer’s, when it names one.

string | null

Example ^generated

{
  "counterparty_did": "example",
  "counterparty_address": "example",
  "dataset_id": "example",
  "offer_id": "example",
  "purpose": "example"
}

Responses

200

OK.

Media typeapplication/json

A negotiation as the management API shows it.

object

id

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

null

string

Human consent: set when the offer requires a provider operator to approve the request (both roles keep track of it).

string

Allowed values: pending approved rejected expired

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

id

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

null

object

Provider, single negotiation only: what the approval narrowed (decisions #68).

object

read_only

boolean

points

Array<string> | null

conflicts

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

Array<object> | null

object

Example

{
  "role": "provider",
  "state": "INITIAL",
  "approval": "pending"
}

400

Unknown participant, the offer is not available to us, or it does not allow the purpose.

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

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

502

The provider or the authority could not be reached.

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