API docs by Redocly

UrbanMind JSON API (1.0.0)

Download OpenAPI specification:

This is the OpenAPI specification for the UrbanMind JSON API.

System API

Health check

Returns the health status of the service.

Authorizations:
None

Responses

Response samples

Content type
application/json
{
  • "message": "string"
}

NGSI-LD API

Query entities

5.7.2 Query Entities (excluding batch entity queries).

This operation allows querying an NGSI-LD system.

Authorizations:
None
query Parameters
id
Array of strings

List of entity IDs to filter

type
Array of strings

List of entity types to filter

idPattern
string

Regular expression pattern for entity IDs

attrs
Array of strings

List of attribute names to include

pick
Array of strings

List of attribute names to pick

omit
Array of strings

List of attribute names to omit

q
string

Query string

limit
integer

Limit

count
boolean

Count

options
string

Options for entities

format
required
string
Value: "simplified"

Format for entities. Must be "simplified".

header Parameters
NGSILD-EntityMap
string <uri>

If present, the EntityMap supplied is used for determining the set of Entities requested during the query operation. The location of the EntityMap used in the query/retrieval operation is returned in the response.

Link
string <uri>

6.3.5 JSON-LD @context resolution

In summary, from a developer's perspective, for POST, PATCH and PUT operations, if MIME type is "application/ld+json", then the associated @context shall be provided only as part of the request payload body. Likewise, if MIME type is "application/json", then the associated @context shall be provided only by using the JSON-LD Link header. No mixes are allowed, i.e. mixing options shall result in HTTP response errors. Implementations should provide descriptive error messages when these situations arise.

In contrast, GET and DELETE operations always take their input @context from the JSON-LD Link Header.

NGSILD-Tenant
string

6.3.14 Tenant specification. The tenant to which the NGSI-LD HTTP operation is targeted.

Via
string

6.3.18 Limiting Distributed Operations

If present, the listing of previously encountered Context Sources supplied is used when determining matching registrations. HTTP Via Header (IETF RFC 7230).

Any Context Broker implementation passing a distributed operation request onward to another Context Source shall send an additional field value on the Via header field using its own unique Context Source "hostAlias" (see clause 5.2.40) as the pseudonym.

Accept
required
string

The media type the client accepts. Should start with "application/json".

Responses

Response Headers
NGSILD-EntityMap
string <uri>

If present, the EntityMap supplied is used for determining the set of Entities requested during the query operation. The location of the EntityMap used in the query/retrieval operation is returned in the response.

NGSILD-Results-Count
integer

6.3.13 Counting number of results. The total number of matching results (e.g. number of Entities) is returned.

NGSILD-Tenant
string

6.3.14 Tenant specification. The tenant to which the NGSI-LD HTTP operation is targeted.

NGSILD-Warning
string
Enum: "110 - Response is Stale" "111 - Revalidation Failed" "199 - Miscellaneous Warning" "299 - Miscellaneous Persistent Warning"

6.3.17 Distributed Operations Caching and Timeout Behaviour

Response Schema: application/json
Array
id
required
string
type
required
string
property name*
additional property
any

Response samples

Content type
application/json
[
  • {
    }
]

Retrieve entity details

5.7.1 Retrieve Entity.

This operation allows retrieving an NGSI-LD Entity.

Authorizations:
None
path Parameters
entityId
required
string

Entity identifier

query Parameters
type
Array of strings

List of entity types to filter

attrs
Array of strings

List of attribute names to include

pick
Array of strings

List of attribute names to pick

omit
Array of strings

List of attribute names to omit

options
string

Options for entities

format
required
string
Value: "simplified"

Format for entities. Must be "simplified".

header Parameters
NGSILD-EntityMap
string <uri>

If present, the EntityMap supplied is used for determining the set of Entities requested during the query operation. The location of the EntityMap used in the query/retrieval operation is returned in the response.

Link
string <uri>

6.3.5 JSON-LD @context resolution

In summary, from a developer's perspective, for POST, PATCH and PUT operations, if MIME type is "application/ld+json", then the associated @context shall be provided only as part of the request payload body. Likewise, if MIME type is "application/json", then the associated @context shall be provided only by using the JSON-LD Link header. No mixes are allowed, i.e. mixing options shall result in HTTP response errors. Implementations should provide descriptive error messages when these situations arise.

In contrast, GET and DELETE operations always take their input @context from the JSON-LD Link Header.

NGSILD-Tenant
string

6.3.14 Tenant specification. The tenant to which the NGSI-LD HTTP operation is targeted.

Via
string

6.3.18 Limiting Distributed Operations

If present, the listing of previously encountered Context Sources supplied is used when determining matching registrations. HTTP Via Header (IETF RFC 7230).

Any Context Broker implementation passing a distributed operation request onward to another Context Source shall send an additional field value on the Via header field using its own unique Context Source "hostAlias" (see clause 5.2.40) as the pseudonym.

Accept
required
string

The media type the client accepts. Should start with "application/json".

Responses

Response Headers
NGSILD-EntityMap
string <uri>

If present, the EntityMap supplied is used for determining the set of Entities requested during the query operation. The location of the EntityMap used in the query/retrieval operation is returned in the response.

NGSILD-Tenant
string

6.3.14 Tenant specification. The tenant to which the NGSI-LD HTTP operation is targeted.

NGSILD-Warning
string
Enum: "110 - Response is Stale" "111 - Revalidation Failed" "199 - Miscellaneous Warning" "299 - Miscellaneous Persistent Warning"

6.3.17 Distributed Operations Caching and Timeout Behaviour

Response Schema: application/json
id
string
type
string
property name*
additional property
any

Response samples

Content type
application/json
{
  • "id": "string",
  • "type": "string"
}

Retrieve available entity types

5.7.5 Retrieve Available Entity Types.

This operation allows retrieving a list of NGSI-LD entity types for which entity instances exist within the NGSI-LD system.

5.7.6 Retrieve Details of Available Entity Types.

This operation allows retrieving a list with a detailed representation of NGSI-LD entity types for which entity instances exist within the NGSI-LD system.

Authorizations:
None
query Parameters
details
boolean

If true, then detailed entity type information represented as an array with elements of the Entity Type data structure (clause 5.2.25) is to be returned.

header Parameters
Link
string <uri>

6.3.5 JSON-LD @context resolution

In summary, from a developer's perspective, for POST, PATCH and PUT operations, if MIME type is "application/ld+json", then the associated @context shall be provided only as part of the request payload body. Likewise, if MIME type is "application/json", then the associated @context shall be provided only by using the JSON-LD Link header. No mixes are allowed, i.e. mixing options shall result in HTTP response errors. Implementations should provide descriptive error messages when these situations arise.

In contrast, GET and DELETE operations always take their input @context from the JSON-LD Link Header.

NGSILD-Tenant
string

6.3.14 Tenant specification. The tenant to which the NGSI-LD HTTP operation is targeted.

Via
string

6.3.18 Limiting Distributed Operations

If present, the listing of previously encountered Context Sources supplied is used when determining matching registrations. HTTP Via Header (IETF RFC 7230).

Any Context Broker implementation passing a distributed operation request onward to another Context Source shall send an additional field value on the Via header field using its own unique Context Source "hostAlias" (see clause 5.2.40) as the pseudonym.

Accept
required
string

The media type the client accepts. Should start with "application/json".

Responses

Response Headers
NGSILD-Tenant
string

6.3.14 Tenant specification. The tenant to which the NGSI-LD HTTP operation is targeted.

NGSILD-Warning
string
Enum: "110 - Response is Stale" "111 - Revalidation Failed" "199 - Miscellaneous Warning" "299 - Miscellaneous Persistent Warning"

6.3.17 Distributed Operations Caching and Timeout Behaviour

Response Schema: application/json
One of
id
required
string <uri>
type
required
string
Value: "EntityTypeList"
typeList
required
Array of strings

Response samples

Content type
application/json
Example
{}

Details about available entity type

5.7.7 Retrieve Available Entity Type information.

This operation allows retrieving detailed entity type information about a specified NGSI-LD entity type for which entity instances exist within the NGSI-LD system. The detailed representation includes the type name (as short name if available in the provided @context), the count of available entity instances and details about attributes that existing instances of this entity type have, including their name (as short name if available in the provided @context) and a list of types the attribute can have (e.g. Property or Relationship).

Authorizations:
None
path Parameters
type
required
string <uri> (Path)

Name of the entity type for which detailed information is to be retrieved. The Fully Qualified Name (FQN) as well as the short name can be used, given that the latter is part of the JSON-LD @context provided.

header Parameters
Link
string <uri>

6.3.5 JSON-LD @context resolution

In summary, from a developer's perspective, for POST, PATCH and PUT operations, if MIME type is "application/ld+json", then the associated @context shall be provided only as part of the request payload body. Likewise, if MIME type is "application/json", then the associated @context shall be provided only by using the JSON-LD Link header. No mixes are allowed, i.e. mixing options shall result in HTTP response errors. Implementations should provide descriptive error messages when these situations arise.

In contrast, GET and DELETE operations always take their input @context from the JSON-LD Link Header.

NGSILD-Tenant
string

6.3.14 Tenant specification. The tenant to which the NGSI-LD HTTP operation is targeted.

Via
string

6.3.18 Limiting Distributed Operations

If present, the listing of previously encountered Context Sources supplied is used when determining matching registrations. HTTP Via Header (IETF RFC 7230).

Any Context Broker implementation passing a distributed operation request onward to another Context Source shall send an additional field value on the Via header field using its own unique Context Source "hostAlias" (see clause 5.2.40) as the pseudonym.

Accept
required
string

The media type the client accepts. Should start with "application/json".

Responses

Response Headers
NGSILD-Tenant
string

6.3.14 Tenant specification. The tenant to which the NGSI-LD HTTP operation is targeted.

NGSILD-Warning
string
Enum: "110 - Response is Stale" "111 - Revalidation Failed" "199 - Miscellaneous Warning" "299 - Miscellaneous Persistent Warning"

6.3.17 Distributed Operations Caching and Timeout Behaviour

Response Schema: application/json
id
required
string <uri>

Fully Qualified Name (FQN) of the entity type being described.

type
required
string
Value: "EntityTypeInfo"

JSON-LD @type.

typeName
required
string

Name of the entity type, short name if contained in @context.

entityCount
required
number

Number of entity instances of this entity type.

required
Array of objects (Attribute)

List of attributes that entity instances with the specified entity type can have.

Array
id
required
string <uri>

Full URI of attribute name.

type
required
string
Value: "Attribute"

JSON-LD @type.

attributeName
required
string

Name of the attribute, short name if contained in @context.

attributeTypes
Array of strings

List of attribute types (e.g. Property or Relationship) for which entity instances exist, which contain an attribute with this name.

typeNames
Array of strings

List of entity type names for which entity instances exist containing attributes that have the respective name.

Response samples

Content type
application/json
{
  • "id": "http://example.com",
  • "type": "EntityTypeInfo",
  • "typeName": "string",
  • "entityCount": 0,
  • "attributeDetails": [
    ]
}

Available attributes

5.7.8 Retrieve Available Attributes.

This operation allows retrieving a list of NGSI-LD attributes that belong to entity instances existing within the NGSI-LD system.

5.7.9 Retrieve Details of Available Attributes.

This operation allows retrieving a list with a detailed representation of NGSI-LD attributes that belong to entity instances existing within the NGSI-LD system.

Authorizations:
None
query Parameters
details
boolean

If true, then detailed attribute information represented as an array with elements of the Attribute data structure (clause 5.2.28) is to be returned.

header Parameters
Link
string <uri>

6.3.5 JSON-LD @context resolution

In summary, from a developer's perspective, for POST, PATCH and PUT operations, if MIME type is "application/ld+json", then the associated @context shall be provided only as part of the request payload body. Likewise, if MIME type is "application/json", then the associated @context shall be provided only by using the JSON-LD Link header. No mixes are allowed, i.e. mixing options shall result in HTTP response errors. Implementations should provide descriptive error messages when these situations arise.

In contrast, GET and DELETE operations always take their input @context from the JSON-LD Link Header.

NGSILD-Tenant
string

6.3.14 Tenant specification. The tenant to which the NGSI-LD HTTP operation is targeted.

Via
string

6.3.18 Limiting Distributed Operations

If present, the listing of previously encountered Context Sources supplied is used when determining matching registrations. HTTP Via Header (IETF RFC 7230).

Any Context Broker implementation passing a distributed operation request onward to another Context Source shall send an additional field value on the Via header field using its own unique Context Source "hostAlias" (see clause 5.2.40) as the pseudonym.

Accept
required
string

The media type the client accepts. Should start with "application/json".

Responses

Response Headers
NGSILD-Tenant
string

6.3.14 Tenant specification. The tenant to which the NGSI-LD HTTP operation is targeted.

NGSILD-Warning
string
Enum: "110 - Response is Stale" "111 - Revalidation Failed" "199 - Miscellaneous Warning" "299 - Miscellaneous Persistent Warning"

6.3.17 Distributed Operations Caching and Timeout Behaviour

Response Schema: application/json
One of
id
required
string <uri>

Unique identifier for the attribute list.

type
required
string
Value: "AttributeList"

JSON-LD @type.

attributeList
required
Array of strings

List containing the attribute names.

Response samples

Content type
application/json
Example
{}

Attribute details

5.7.10 Retrieve Available Attribute Information.

This operation allows retrieving detailed attribute information about a specified NGSI-LD attribute that belongs to entity instances existing within the NGSI-LD system. The detailed representation includes the attribute name (as short name if available in the provided @context) and the type names for which entity instances exist that have the respective attribute, a count of available attribute instances and a list of types the attribute can have (e.g. Property or Relationship).

Authorizations:
None
path Parameters
attrId
required
string <uri> (Path)

Name of the attribute for which detailed information is to be retrieved. The Fully Qualified Name (FQN) as well as the short name can be used, given that the latter is part of the JSON-LD @context provided.

header Parameters
Link
string <uri>

6.3.5 JSON-LD @context resolution

In summary, from a developer's perspective, for POST, PATCH and PUT operations, if MIME type is "application/ld+json", then the associated @context shall be provided only as part of the request payload body. Likewise, if MIME type is "application/json", then the associated @context shall be provided only by using the JSON-LD Link header. No mixes are allowed, i.e. mixing options shall result in HTTP response errors. Implementations should provide descriptive error messages when these situations arise.

In contrast, GET and DELETE operations always take their input @context from the JSON-LD Link Header.

NGSILD-Tenant
string

6.3.14 Tenant specification. The tenant to which the NGSI-LD HTTP operation is targeted.

Via
string

6.3.18 Limiting Distributed Operations

If present, the listing of previously encountered Context Sources supplied is used when determining matching registrations. HTTP Via Header (IETF RFC 7230).

Any Context Broker implementation passing a distributed operation request onward to another Context Source shall send an additional field value on the Via header field using its own unique Context Source "hostAlias" (see clause 5.2.40) as the pseudonym.

Accept
required
string

The media type the client accepts. Should start with "application/json".

Responses

Response Headers
NGSILD-Tenant
string

6.3.14 Tenant specification. The tenant to which the NGSI-LD HTTP operation is targeted.

NGSILD-Warning
string
Enum: "110 - Response is Stale" "111 - Revalidation Failed" "199 - Miscellaneous Warning" "299 - Miscellaneous Persistent Warning"

6.3.17 Distributed Operations Caching and Timeout Behaviour

Response Schema: application/json
id
required
string <uri>

Full URI of attribute name.

type
required
string
Value: "Attribute"

JSON-LD @type.

attributeName
required
string

Name of the attribute, short name if contained in @context.

attributeTypes
Array of strings

List of attribute types (e.g. Property or Relationship) for which entity instances exist, which contain an attribute with this name.

typeNames
Array of strings

List of entity type names for which entity instances exist containing attributes that have the respective name.

Response samples

Content type
application/json
{
  • "id": "http://example.com",
  • "type": "Attribute",
  • "attributeName": "string",
  • "attributeTypes": [
    ],
  • "typeNames": [
    ]
}

UrbanMind API

Retrieve distribution data

Downloads the data associated with the given distribution ID. This endpoint is similar to the one used by the HTML UI but is intended for programmatic use.

Authorizations:
(ParticipantIDBearerAuth)
path Parameters
id
required
string <uuid>

UUID in path

Responses

Response Schema: application/octet-stream
string <binary>

Response samples

Content type
application/json
{
  • "message": "string"
}

Retrieve data from integration

Performs a data pull using an integration client configured with the provided dynamic distribution configuration payload.

Authorizations:
(ParticipantIDBearerAuth)
path Parameters
id
required
string <uuid>

UUID in path

Request Body schema: application/json
required
property name*
additional property
any

Responses

Response Schema: application/octet-stream
string <binary>

Request samples

Content type
application/json
{ }

Response samples

Content type
application/json
{
  • "message": "string"
}

Use case DuckDB query

Query the DuckDB database behind a use case using SQL.

Authorizations:
(ParticipantIDBearerAuth) None
path Parameters
id
required
string <uuid>

UUID in path

Request Body schema: application/json
required
query
required
string

The SQL query that should be executed

Array of strings or numbers or booleans

Optional parameters for the SQL query.

Array
One of
string

Responses

Response Schema: application/json
Array of objects
Array
property name*
additional property
any

Request samples

Content type
application/json
{
  • "query": "select id, pm25 from Environment.AirQualityObserved where id != ? and pm25 > ?;",
  • "params": [
    ]
}

Response samples

Content type
application/json
{
  • "rows": [
    ]
}

Fetch widget data

Returns the data associated with the given widget ID. This endpoint is similar to the one used by the HTML UI but is intended for programmatic use.

Authorizations:
(ParticipantIDBearerAuth) None
path Parameters
id
required
string <uuid>

UUID in path

Responses

Response Schema:
Array of objects
Array
property name*
additional property
any

Response samples

Content type
{
  • "rows": [
    ]
}

DSP API

Fetch the participant's catalog

Returns the provider's catalog, containing the datasets, data services, and distributions it offers.

Authorizations:
(ParticipantIDBearerAuth) None
path Parameters
participant_id
required
string <uuid>

Participant id in path

Request Body schema: application/json
required
@context
required
Array of strings
@type
required
string

Responses

Response Schema: application/json
@context
required
Array of strings
@id
required
string
@type
required
string
participantId
required
string
dct:title
string
object
@id
string
foaf:name
string
dct:description
string
dct:issued
string <date-time>
dct:modified
string <date-time>
Array of objects (Dataset)
Array
@context
Array of strings
@id
required
string
@type
string
Value: "Dataset"
dct:title
string
dct:description
string
object
@id
string
foaf:name
string
dct:issued
string <date-time>
dct:modified
string <date-time>
required
Array of objects (Distribution)
Array
@type
required
string
Value: "Distribution"
required
string or DataService (object)
One of
string
format
required
string
dcat:mediaType
required
string
dcterms:title
required
string
dcterms:description
required
string
dcat:downloadURL
required
string
dcterms:modified
required
string
dcterms:issued
required
string
required
Array of objects (Offer)
Array
@id
required
string
@type
required
string
uid
required
string
required
Array of objects (Permission)
Array
action
required
string
required
Array of objects (Prohibition)
Array
action
required
string
Array of objects (DataService)
Array
@id
required
string
@type
required
string
Value: "DataService"
endpointUrl
string

Request samples

Content type
application/json
{
  • "@context": [
    ],
  • "@type": "string"
}

Response samples

Content type
application/json
{
  • "@context": [
    ],
  • "@id": "string",
  • "@type": "string",
  • "participantId": "string",
  • "dct:title": "string",
  • "dct:publisher": {
    },
  • "dct:description": "string",
  • "dct:issued": "2019-08-24T14:15:22Z",
  • "dct:modified": "2019-08-24T14:15:22Z",
  • "dataset": [
    ],
  • "service": [
    ]
}

Fetch dataset details

Returns the details of a single dataset offered by the participant.

Authorizations:
(ParticipantIDBearerAuth) None
path Parameters
participant_id
required
string <uuid>

Participant id in path

id
required
string <uuid>

UUID in path

Responses

Response Schema: application/json
@context
Array of strings
@id
required
string
@type
string
Value: "Dataset"
dct:title
string
dct:description
string
object
@id
string
foaf:name
string
dct:issued
string <date-time>
dct:modified
string <date-time>
required
Array of objects (Distribution)
Array
@type
required
string
Value: "Distribution"
required
string or DataService (object)
One of
string
format
required
string
dcat:mediaType
required
string
dcterms:title
required
string
dcterms:description
required
string
dcat:downloadURL
required
string
dcterms:modified
required
string
dcterms:issued
required
string
required
Array of objects (Offer)
Array
@id
required
string
@type
required
string
uid
required
string
required
Array of objects (Permission)
Array
action
required
string
required
Array of objects (Prohibition)
Array
action
required
string

Response samples

Content type
application/json
{
  • "@context": [
    ],
  • "@id": "string",
  • "@type": "Dataset",
  • "dct:title": "string",
  • "dct:description": "string",
  • "dct:publisher": {
    },
  • "dct:issued": "2019-08-24T14:15:22Z",
  • "dct:modified": "2019-08-24T14:15:22Z",
  • "distribution": [
    ],
  • "hasPolicy": [
    ]
}

Fetch transfer process state

Returns the current state of the transfer process. Can be accessed by either the consumer or provider of the contract.

Authorizations:
(ParticipantIDBearerAuth)
path Parameters
participant_id
required
string <uuid>

Participant id in path

transfer_id
required
string <uuid>

Responses

Response Schema: application/json
@context
required
Array of strings
@type
required
string
Value: "TransferProcess"
providerPid
required
string
consumerPid
required
string
state
required
string (TransferProcessState)
Enum: "REQUESTED" "STARTED" "TERMINATED" "COMPLETED" "SUSPENDED"

DSP transfer-process states.

Response samples

Content type
application/json
{
  • "@context": [
    ],
  • "@type": "TransferProcess",
  • "providerPid": "string",
  • "consumerPid": "string",
  • "state": "REQUESTED"
}

Request transfer process

Requests the creation of a transfer process for a given agreement. Initiated by the consumer and sent to the provider.

Authorizations:
(ParticipantIDBearerAuth)
path Parameters
participant_id
required
string <uuid>

Participant id in path

Request Body schema: application/json
required
@context
required
Array of strings
@type
required
string
Value: "TransferRequestMessage"
consumerPid
required
string
agreementId
required
string
format
required
string
callbackAddress
string

Responses

Response Schema: application/json
@context
required
Array of strings
@type
required
string
Value: "TransferProcess"
providerPid
required
string
consumerPid
required
string
state
required
string (TransferProcessState)
Enum: "REQUESTED" "STARTED" "TERMINATED" "COMPLETED" "SUSPENDED"

DSP transfer-process states.

Request samples

Content type
application/json
{
  • "@context": [
    ],
  • "@type": "TransferRequestMessage",
  • "consumerPid": "string",
  • "agreementId": "string",
  • "format": "string",
  • "callbackAddress": "string"
}

Response samples

Content type
application/json
{
  • "@context": [
    ],
  • "@type": "TransferProcess",
  • "providerPid": "string",
  • "consumerPid": "string",
  • "state": "REQUESTED"
}

Start transfer process

Starts a transfer process for the given contract. Can be sent by either the consumer or provider, typically to confirm start after suspension or to signal the provider is ready to transmit.

Authorizations:
(ParticipantIDBearerAuth)
path Parameters
participant_id
required
string <uuid>

Participant id in path

transfer_id
required
string <uuid>
Request Body schema: application/json
required
@context
required
Array of strings
@type
required
string
Value: "TransferStartMessage"
providerPid
required
string
consumerPid
required
string

Responses

Response Schema: application/json
@context
required
Array of strings
@type
required
string
Value: "TransferProcess"
providerPid
required
string
consumerPid
required
string
state
required
string (TransferProcessState)
Enum: "REQUESTED" "STARTED" "TERMINATED" "COMPLETED" "SUSPENDED"

DSP transfer-process states.

Request samples

Content type
application/json
{
  • "@context": [
    ],
  • "@type": "TransferStartMessage",
  • "providerPid": "string",
  • "consumerPid": "string"
}

Response samples

Content type
application/json
{
  • "@context": [
    ],
  • "@type": "TransferProcess",
  • "providerPid": "string",
  • "consumerPid": "string",
  • "state": "REQUESTED"
}

Complete transfer process

Signals that a transfer process has completed, indicating that all data has been transmitted. Can be sent by either the consumer or provider.

Authorizations:
(ParticipantIDBearerAuth)
path Parameters
participant_id
required
string <uuid>

Participant id in path

transfer_id
required
string <uuid>
Request Body schema: application/json
required
@context
required
Array of strings
@type
required
string
Value: "TransferCompletionMessage"
providerPid
required
string
consumerPid
required
string

Responses

Response Schema: application/json
@context
required
Array of strings
@type
required
string
Value: "TransferProcess"
providerPid
required
string
consumerPid
required
string
state
required
string (TransferProcessState)
Enum: "REQUESTED" "STARTED" "TERMINATED" "COMPLETED" "SUSPENDED"

DSP transfer-process states.

Request samples

Content type
application/json
{
  • "@context": [
    ],
  • "@type": "TransferCompletionMessage",
  • "providerPid": "string",
  • "consumerPid": "string"
}

Response samples

Content type
application/json
{
  • "@context": [
    ],
  • "@type": "TransferProcess",
  • "providerPid": "string",
  • "consumerPid": "string",
  • "state": "REQUESTED"
}

Terminate transfer process

Terminates a transfer process, ending it before completion. Can be sent by either the consumer or provider and may optionally include a reason for the termination.

Authorizations:
(ParticipantIDBearerAuth)
path Parameters
participant_id
required
string <uuid>

Participant id in path

transfer_id
required
string <uuid>
Request Body schema: application/json
required
@context
required
Array of strings
@type
required
string
Value: "TransferTerminationMessage"
providerPid
required
string
consumerPid
required
string
code
string
reason
Array of strings

Responses

Response Schema: application/json
@context
required
Array of strings
@type
required
string
Value: "TransferProcess"
providerPid
required
string
consumerPid
required
string
state
required
string (TransferProcessState)
Enum: "REQUESTED" "STARTED" "TERMINATED" "COMPLETED" "SUSPENDED"

DSP transfer-process states.

Request samples

Content type
application/json
{
  • "@context": [
    ],
  • "@type": "TransferTerminationMessage",
  • "providerPid": "string",
  • "consumerPid": "string",
  • "code": "string",
  • "reason": [
    ]
}

Response samples

Content type
application/json
{
  • "@context": [
    ],
  • "@type": "TransferProcess",
  • "providerPid": "string",
  • "consumerPid": "string",
  • "state": "REQUESTED"
}

Suspend transfer process

Suspends an active transfer process. Can be sent by either the consumer or provider and may optionally include a reason for the suspension.

Authorizations:
(ParticipantIDBearerAuth)
path Parameters
participant_id
required
string <uuid>

Participant id in path

transfer_id
required
string <uuid>
Request Body schema: application/json
required
@context
required
Array of strings
@type
required
string
Value: "TransferSuspensionMessage"
providerPid
required
string
consumerPid
required
string
code
string
reason
Array of strings

Responses

Response Schema: application/json
@context
required
Array of strings
@type
required
string
Value: "TransferProcess"
providerPid
required
string
consumerPid
required
string
state
required
string (TransferProcessState)
Enum: "REQUESTED" "STARTED" "TERMINATED" "COMPLETED" "SUSPENDED"

DSP transfer-process states.

Request samples

Content type
application/json
{
  • "@context": [
    ],
  • "@type": "TransferSuspensionMessage",
  • "providerPid": "string",
  • "consumerPid": "string",
  • "code": "string",
  • "reason": [
    ]
}

Response samples

Content type
application/json
{
  • "@context": [
    ],
  • "@type": "TransferProcess",
  • "providerPid": "string",
  • "consumerPid": "string",
  • "state": "REQUESTED"
}

Fetch negotiation process state

Returns the current state of the contract negotiation process (contract). Can be accessed by either the consumer or provider of the contract.

Authorizations:
(ParticipantIDBearerAuth)
path Parameters
participant_id
required
string <uuid>

Participant id in path

contract_id
required
string <uuid>

Responses

Response Schema: application/json
@context
required
Array of strings
@type
required
string
Value: "ContractNegotiation"
providerPid
required
string
consumerPid
required
string
state
required
string (ContractNegotiationState)
Enum: "REQUESTED" "FINALIZED" "TERMINATED" "AGREED" "VERIFIED"

Response samples

Content type
application/json
{
  • "@context": [
    ],
  • "@type": "ContractNegotiation",
  • "providerPid": "string",
  • "consumerPid": "string",
  • "state": "REQUESTED"
}

Initiate contract negotiation

Initiates a new contract negotiation by sending an offer from the consumer to the provider. Used to start the negotiation process.

Authorizations:
(ParticipantIDBearerAuth)
path Parameters
participant_id
required
string <uuid>

Participant id in path

Request Body schema: application/json
required
@context
required
Array of strings
@type
required
string
Value: "ContractRequestMessage"
consumerPid
required
string
required
object (MessageOffer)
@id
required
string
@type
required
string
target
string
Array of objects (Permission)
Array
action
required
string
Array of objects (Prohibition)
Array
action
required
string

Responses

Response Schema: application/json
@context
required
Array of strings
@type
required
string
Value: "ContractNegotiation"
providerPid
required
string
consumerPid
required
string
state
required
string (ContractNegotiationState)
Enum: "REQUESTED" "FINALIZED" "TERMINATED" "AGREED" "VERIFIED"

Request samples

Content type
application/json
{
  • "@context": [
    ],
  • "@type": "ContractRequestMessage",
  • "consumerPid": "string",
  • "offer": {
    }
}

Response samples

Content type
application/json
{
  • "@context": [
    ],
  • "@type": "ContractNegotiation",
  • "providerPid": "string",
  • "consumerPid": "string",
  • "state": "REQUESTED"
}

Send counter-offer for contract negotiation

Sends a counter-offer within an existing contract negotiation, identified by the provider's process id (contract_id). Used by the consumer to continue a negotiation that has already been initiated by the provider.

Authorizations:
(ParticipantIDBearerAuth)
path Parameters
participant_id
required
string <uuid>

Participant id in path

contract_id
required
string <uuid>
Request Body schema: application/json
required
@context
required
Array of strings
@type
required
string
Value: "ContractRequestMessage"
consumerPid
required
string
required
object (MessageOffer)
@id
required
string
@type
required
string
target
string
Array of objects (Permission)
Array
action
required
string
Array of objects (Prohibition)
Array
action
required
string

Responses

Response Schema: application/json
@context
required
Array of strings
@type
required
string
Value: "ContractNegotiation"
providerPid
required
string
consumerPid
required
string
state
required
string (ContractNegotiationState)
Enum: "REQUESTED" "FINALIZED" "TERMINATED" "AGREED" "VERIFIED"

Request samples

Content type
application/json
{
  • "@context": [
    ],
  • "@type": "ContractRequestMessage",
  • "consumerPid": "string",
  • "offer": {
    }
}

Response samples

Content type
application/json
{
  • "@context": [
    ],
  • "@type": "ContractNegotiation",
  • "providerPid": "string",
  • "consumerPid": "string",
  • "state": "REQUESTED"
}

Send contract negotiation event

Sends an event signaling a state change in the contract negotiation, such as finalization by the provider after the consumer has verified the agreement. Can be sent by either the consumer or provider depending on the event type.

Authorizations:
(ParticipantIDBearerAuth)
path Parameters
id
required
string <uuid>

UUID in path

contract_id
required
string <uuid>
Request Body schema: application/json
required
@context
required
Array of strings
@type
required
string
Value: "ContractNegotiationEventMessage"
providerPid
required
string
consumerPid
required
string
eventType
required
string
Value: "FINALIZED"

Responses

Response Schema: application/json
@context
required
Array of strings
@type
required
string
Value: "ContractNegotiation"
providerPid
required
string
consumerPid
required
string
state
required
string (ContractNegotiationState)
Enum: "REQUESTED" "FINALIZED" "TERMINATED" "AGREED" "VERIFIED"

Request samples

Content type
application/json
{
  • "@context": [
    ],
  • "@type": "ContractNegotiationEventMessage",
  • "providerPid": "string",
  • "consumerPid": "string",
  • "eventType": "FINALIZED"
}

Response samples

Content type
application/json
{
  • "@context": [
    ],
  • "@type": "ContractNegotiation",
  • "providerPid": "string",
  • "consumerPid": "string",
  • "state": "REQUESTED"
}

Terminate contract negotiation

Terminates a contract negotiation, ending it before an agreement is reached. Can be sent by either the consumer or provider and may optionally include a reason for the termination.

Authorizations:
(ParticipantIDBearerAuth)
path Parameters
participant_id
required
string <uuid>

Participant id in path

contract_id
required
string <uuid>
Request Body schema: application/json
required
@context
required
Array of strings
@type
required
string
Value: "ContractNegotiationTerminationMessage"
providerPid
required
string
consumerPid
required
string
reason
Array of strings

Responses

Response Schema: application/json
@context
required
Array of strings
@type
required
string
Value: "ContractNegotiation"
providerPid
required
string
consumerPid
required
string
state
required
string (ContractNegotiationState)
Enum: "REQUESTED" "FINALIZED" "TERMINATED" "AGREED" "VERIFIED"

Request samples

Content type
application/json
{
  • "@context": [
    ],
  • "@type": "ContractNegotiationTerminationMessage",
  • "providerPid": "string",
  • "consumerPid": "string",
  • "reason": [
    ]
}

Response samples

Content type
application/json
{
  • "@context": [
    ],
  • "@type": "ContractNegotiation",
  • "providerPid": "string",
  • "consumerPid": "string",
  • "state": "REQUESTED"
}

Create contract agreement

Allows a provider to send a Contract Agreement Message, transitioning the negotiation to the AGREED state.

Authorizations:
(ParticipantIDBearerAuth)
path Parameters
participant_id
required
string <uuid>

Participant id in path

contract_id
required
string <uuid>
Request Body schema: application/json
required
@context
required
Array of strings
@type
required
string
Value: "ContractAgreementMessage"
providerPid
required
string
consumerPid
required
string
agreement
required
object

Ignored for now; validated/persisted in a follow-up.

Responses

Response Schema: application/json
@context
required
Array of strings
@type
required
string
Value: "ContractNegotiation"
providerPid
required
string
consumerPid
required
string
state
required
string (ContractNegotiationState)
Enum: "REQUESTED" "FINALIZED" "TERMINATED" "AGREED" "VERIFIED"

Request samples

Content type
application/json
{
  • "@context": [
    ],
  • "@type": "ContractAgreementMessage",
  • "providerPid": "string",
  • "consumerPid": "string",
  • "agreement": { }
}

Response samples

Content type
application/json
{
  • "@context": [
    ],
  • "@type": "ContractNegotiation",
  • "providerPid": "string",
  • "consumerPid": "string",
  • "state": "REQUESTED"
}

Verify contract agreement

Verifies the contract agreement, sent by the consumer to confirm the agreement issued by the provider.

Authorizations:
(ParticipantIDBearerAuth)
path Parameters
participant_id
required
string <uuid>

Participant id in path

contract_id
required
string <uuid>
Request Body schema: application/json
required
@context
required
Array of strings
@type
required
string
Value: "ContractAgreementVerificationMessage"
providerPid
required
string
consumerPid
required
string

Responses

Response Schema: application/json
@context
required
Array of strings
@type
required
string
Value: "ContractAgreement"
providerPid
required
string
consumerPid
required
string

Request samples

Content type
application/json
{
  • "@context": [
    ],
  • "@type": "ContractAgreementVerificationMessage",
  • "providerPid": "string",
  • "consumerPid": "string"
}

Response samples

Content type
application/json
{
  • "@context": [
    ],
  • "@type": "ContractAgreement",
  • "providerPid": "string",
  • "consumerPid": "string"
}