Data

Publish

POST /supply-chain/data-space/inbox

Publishes supply-chain data to TWIN. The body is a W3C Activity Streams 2.0 activity. The object field carries the actual consignment, event, or document payload — see the consignment data model for the full payload shape.

POST /supply-chain/data-space/inbox
Content-Type: application/json
Cookie: access_token=<jwt>
x-api-key: <your-api-key>

Request body

Field	Required	Description
`@context`	Yes	Must include `"https://www.w3.org/ns/activitystreams"`
`type`	Yes	`Create`, `Update`, or `Add`
`actor`	Yes	Publishing organisation — UNECE `TradeParty` with a `registeredId` (DID)
`object`	Yes	The consignment, event, or document payload
`target`	`Add` only	The consignment the event or document belongs to (identified by `globalId`)

Activity types

`type`	What TWIN does
`Create`	Creates a new consignment
`Update`	Updates an existing consignment — matched by `globalId` or `identifier`
`Add`	Adds an event or document to an existing consignment

Examples — the object field contains the consignment or event payload:

{
  "@context": ["https://www.w3.org/ns/activitystreams"],
  "type": "Create",
  "actor": {
    "@context": "https://vocabulary.uncefact.org/unece-context-D23B.jsonld",
    "type": "TradeParty",
    "registeredId": {
      "@type": "https://ref.gs1.org/voc/OrganizationID_Type-DID",
      "@value": "did:web:your-org.example.com"
    }
  },
  "object": {
    "@context": "https://vocabulary.uncefact.org/unece-context-D23B.jsonld",
    "type": "Consignment",
    "identifier": "MYREF-001",
    "globalId": "urn:uuid:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
  }
}

{
  "@context": ["https://www.w3.org/ns/activitystreams"],
  "type": "Update",
  "actor": {
    "@context": "https://vocabulary.uncefact.org/unece-context-D23B.jsonld",
    "type": "TradeParty",
    "registeredId": {
      "@type": "https://ref.gs1.org/voc/OrganizationID_Type-DID",
      "@value": "did:web:your-org.example.com"
    }
  },
  "object": {
    "@context": "https://vocabulary.uncefact.org/unece-context-D23B.jsonld",
    "type": "Consignment",
    "identifier": "MYREF-001",
    "globalId": "urn:uuid:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "summaryDescription": "Updated description"
  }
}

{
  "@context": ["https://www.w3.org/ns/activitystreams"],
  "type": "Add",
  "actor": {
    "@context": "https://vocabulary.uncefact.org/unece-context-D23B.jsonld",
    "type": "TradeParty",
    "registeredId": {
      "@type": "https://ref.gs1.org/voc/OrganizationID_Type-DID",
      "@value": "did:web:your-org.example.com"
    }
  },
  "object": {
    "@context": "https://vocabulary.uncefact.org/unece-context-D23B.jsonld",
    "type": "SupplyChainEvent",
    "typeCode": "twin:despatched",
    "occurrenceDateTime": "2026-06-02T09:00:00.000Z"
  },
  "target": {
    "@context": "https://vocabulary.uncefact.org/unece-context-D23B.jsonld",
    "type": "Consignment",
    "globalId": "urn:uuid:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
  }
}

{
  "@context": ["https://www.w3.org/ns/activitystreams"],
  "type": "Add",
  "actor": {
    "@context": "https://vocabulary.uncefact.org/unece-context-D23B.jsonld",
    "type": "TradeParty",
    "registeredId": {
      "@type": "https://ref.gs1.org/voc/OrganizationID_Type-DID",
      "@value": "did:web:your-org.example.com"
    }
  },
  "object": {
    "@context": "https://vocabulary.uncefact.org/unece-context-D23B.jsonld",
    "type": "Document",
    "documentTypeCode": "unece:DocumentCodeList#730",
    "uRIId": "https://example.com/document.pdf",
    "identifier": "DOC-001"
  },
  "target": {
    "@context": "https://vocabulary.uncefact.org/unece-context-D23B.jsonld",
    "type": "Consignment",
    "globalId": "urn:uuid:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
  }
}

Response `201`

{
  "id": "aig:019e...",
  "status": "completed",
  "generator": "supply-chain-node",
  "dateCreated": "2026-06-30T14:00:00.000Z",
  "tasks": [
    {
      "taskId": "...",
      "dataspaceAppId": "supply-chain",
      "result": 0,
      "startDate": "2026-06-30T14:00:00.000Z",
      "endDate": "2026-06-30T14:00:00.001Z",
      "status": "completed"
    }
  ]
}

Errors

Status	Cause
`400`	Malformed activity or missing required field
`401`	Missing or invalid credentials
`422`	Invalid consignment payload

Read

All read endpoints require:

Cookie: access_token=<jwt>
x-api-key: <your-api-key>

Consignments

Method	Endpoint	Returns
`GET`	`/supply-chain/data-space/consignments`	Paginated list of `ConsignmentView`
`GET`	`/supply-chain/data-space/consignments/:id`	Single `ConsignmentView` with nested events and documents
`GET`	`/supply-chain/data-space/consignments/:id/events`	Array of `EventView`
`GET`	`/supply-chain/data-space/consignments/:id/documents`	Array of `DocumentAttachment`

:id accepts the consignment's globalId, identifier, or AIG vertex ID (aig:...).

Query parameters

Parameter	Description
`cursor`	Cursor from a previous response to fetch the next page
`limit`	Number of results per page

Response `200` — list

{
  "entities": [...],
  "cursor": "<next-page-cursor>"
}

cursor is omitted when there are no more results.

Documents

Method	Endpoint	Returns
`GET`	`/supply-chain/data-space/documents`	Paginated list of `DocumentAttachment`
`GET`	`/supply-chain/data-space/documents/:documentId`	Single `DocumentAttachment` with a pre-signed download URL

Add ?consignmentId=:id to scope documents to a specific consignment.

Error codes

Status	Cause
`401`	Missing or invalid credentials
`404`	Consignment or document not found

Data

On this page