Ga naar inhoud
buildinglinksbuildinglinks

Start a transfer

POST
/api/v1/transfers
curl --request POST \
  --url https://example.com/api/v1/transfers \
  --header 'Content-Type: application/json' \
  --cookie bl_%3Cslug%3E_session=%3Cbl_%3Cslug%3E_session%3E \
  --data '{ "agreement_id": "example", "format": "example" }'

As consumer: starts a transfer under an agreement. Once STARTED, the data is reachable through the gateway of our data plane.

Authorizations

Section titled “Authorizations”

Request Bodyrequired

Section titled “Request Bodyrequired”
Media typeapplication/json
object
agreement_id
required

An agreement of ours as consumer.

string
format

Default HttpData-PULL.

string | null

Example generated

{
  "agreement_id": "example",
  "format": "example"
}

Responses

Section titled “Responses”

200

Section titled “200”

OK.

Media typeapplication/json

A transfer as the management API shows it.

object
id
required
string
role
required
string
Allowed values: provider consumer
state
required
string
Allowed values: INITIAL REQUESTED STARTED SUSPENDED COMPLETED TERMINATED
consumer_pid
required
string
provider_pid
required
string
agreement_id
required
string
dataset_id
string | null
counterparty_did
required
string
counterparty_address
string | null
format
required

E.g. HttpData-PULL.

string
data_address

Where the data is: the endpoint, with the token masked.

object | null
connection_alias
string | null
error
string | null
history
required

The messages and states so far, as for a negotiation.

Array<object>
object
created_at
required
string format: date-time
updated_at
required
string format: date-time
dataplane_id

DPS: the data plane serving this transfer (own, or a supplier’s for a delegated dataset) and the state it last reported.

string | null
dataplane_endpoint
string | null
delegation_id
string | null
flow_state
string | null
counterparty_name
string | null
outbox
required

Our messages of this transfer 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

Example 

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

401

Section titled “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

Section titled “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

Section titled “502”

The provider could not be reached or refused.

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