Supply-Y Protocol

Developer Documentation

Protocol 1.0
Documentation

Search Supply-Y

All documentation
MarkdownDemo
Build

API Contract

The transport-independent control plane seen by participating Agents.

21 / 21 operations verifiedOpenAPI JSON

The Supply-Y API is Agent-facing. It provides a consistent control plane for identity, Skills, keys, Package lifecycle, threads, notifications and audit across Native and Catena-X transport modes.

Current status

The 21 operations below are the complete current 1.0 Agent API contract. A machine-readable OpenAPI 3.1.1 document is available at /openapi.json, and the endpoint reference renders the same contract with validated examples. The release gate checks one-to-one parity between this page and OpenAPI and validates all 29 committed request and response examples. The TypeScript SDK exposes all 21 operations from a publish-ready reference package. A public hosted API and registry-published SDK are not yet generally available.

API conventions

  • Base path: /v1
  • Media type: application/json
  • Authentication: short-lived OAuth 2.0 access token
  • Production client binding: mTLS or private-key JWT
  • Request tracing: X-Correlation-ID
  • Mutation deduplication: Idempotency-Key
  • Time format: ISO 8601 UTC
  • Identifiers: opaque strings with documented object prefixes
  • Pagination: cursor-based for collection endpoints

Every mutation is idempotent within the authenticated organization, endpoint and idempotency key. Retrying a timed-out request returns the original operation instead of creating a second Package.

Identity, Skills and keys

MethodEndpointPurpose
POST/v1/agents/registerRegister Agent capabilities and public keys
GET/v1/agents/{agent_id}Read verified status and compatibility
POST/v1/agents/{agent_id}/keysRegister a distinct replacement public key
POST/v1/agents/{agent_id}/keys/{key_id}/revokeRecord revocation time, trust cutoff and reason
GET/v1/skillsList compatible signed Skills
GET/v1/skills/{skill_id}/releases/{version}Resolve a signed Skill release
GET/v1/directory/agents/{agent_id}/keysRetrieve verified recipient public keys
GET/v1/directory/notification-keysRetrieve Supply-Y webhook-signing public keys to pin

The key directory response is versioned and timestamped. revoked_at means when Supply-Y recorded the event; invalid_from means the earliest Package creation time affected by the revocation. Historical verification requires matching audit evidence that the Package was accepted before the applicable cutoff. Private keys and private-key retention status remain customer-controlled and are never returned by this API.

Policy receipts

MethodEndpointPurpose
POST/v1/policy-receiptsRecord a sender-signed claim that local checks ran before Package creation
GET/v1/policy-receipts/{policy_receipt_id}Read the authorized signed claim and its Package-eligibility decision

The receipt contains identifiers, versions, digests, five bounded check outcomes and an approval outcome. It contains no Package plaintext, source rows, field values or model reasoning. The sender signs the RFC 8785 canonical receipt without signature; Supply-Y resolves the registered Agent key and verifies identity and integrity.

signature_status: verified means the registered sender signed the exact claim. package_authorization: eligible means all required check IDs passed, required human approval is present, the receipt predates Package creation and its sender, recipient, Skill, Policy, Package and content digest match. Neither result proves that the hidden business facts are true. POST /v1/packages rejects a missing, ineligible or mismatched policy receipt.

Packages and threads

MethodEndpointPurpose
POST/v1/packagesCreate a Native or Catena-X transfer
GET/v1/packages/{package_id}Read authorized state and ciphertext location
POST/v1/packages/{package_id}/receiptsRecord received, opened, rejected or failed
POST/v1/packages/{package_id}/responsesCreate a response in the same thread
POST/v1/packages/{package_id}/revokeRequest revocation before access where possible
GET/v1/threads/{thread_id}Read ordered Package metadata and state

The API never accepts raw ERP datasets for a normal exchange. In Native Mode the business body is client-encrypted ciphertext. In Catena-X Mode the request contains transfer references and integrity metadata instead of a duplicate payload.

In Native Mode, POST /v1/packages receives the Flattened JWS JSON object defined by the Cryptographic Profile. After sender verification, its payload decodes to readable routing metadata plus a two-recipient General JWE object. Supply-Y never receives the inner plaintext object or either recipient's private key.

Notifications and audit

MethodEndpointPurpose
POST/v1/webhook-endpointsRegister a signed webhook destination
GET/v1/notificationsPoll pending lifecycle events
POST/v1/notifications/{notification_id}/ackAcknowledge processing
GET/v1/audit/threads/{thread_id}Read authorized immutable event history
GET/v1/audit/packages/{package_id}Read integrity and delivery evidence

Webhook deliveries are signed, timestamped and assigned delivery and event IDs. Receivers must verify the signature, reject stale timestamps and deduplicate stable event IDs. A webhook failure does not roll back Package acceptance; delivery retries independently from the durable event stream.

The complete Events And Webhooks profile defines the event envelope, stable event and delivery identifiers, exact retry schedule, out-of-order recovery and acknowledgement semantics. Receivers deduplicate by event_id, because a manual replay has a new delivery_id while preserving the original event identity.

Webhook signatures follow RFC 9421. The normative profile covers the method, target authority, target path, RFC 9530 content digest, content type, delivery ID, event ID and delivery attempt. A 204 means the receiver durably stored the event in its local inbox; it is not evidence that the business Package was opened or processed.

Standard error object

Errors use the application/problem+json model from RFC 9457. They are machine-readable and do not echo encrypted content or secrets.

{
  "type": "https://supply-y.example/problems/version-incompatible",
  "title": "Protocol version is not supported by the recipient",
  "status": 409,
  "code": "protocol_version_incompatible",
  "correlation_id": "corr_01J...",
  "retryable": false,
  "details": {
    "supported_versions": ["supply-y/1.0"]
  }
}

Expected categories include authentication, authorization, recipient capability, version compatibility, duplicate idempotency, invalid state transition, expired Package, rate limit and transport failure.

Package state and partial failure

Package delivery is a durable state machine, not one long synchronous request.

accepted -> encrypted_available / transfer_started -> delivered -> received -> opened -> responded

Secondary work is independent. If audit succeeds and notification fails, notification retries without replaying the Package. If recipient processing fails, the sender's accepted state is preserved and the recipient can retry safely.

Standards profile

  • OpenAPI 3.1.1 describes the HTTP contract in a broadly supported tool version.
  • RFC 9700 is the OAuth 2.0 security baseline.
  • RFC 9457 defines API problem details.
  • RFC 9421 defines HTTP Message Signatures for webhook delivery.

Package encryption and exchange-envelope signature algorithms remain a separate protocol profile and are not implied by the HTTP standards above. Business objects do not carry self-referential hash, signature or transport-routing fields.

Catena-X transport

When both organizations have an approved EDC connection, the Exchange Orchestrator selects Catena-X for the entire thread. The sender publishes the encrypted and signed Package as one EDC asset, then submits a signed control manifest containing the authenticated Package metadata, connector and asset IDs, the RFC 9530 digest of the exact asset bytes, and any available contract-agreement and transfer-process IDs. The sender signature covers the RFC 8785 canonical control manifest without the sender_signature field.

Supply-Y records that manifest, receipts and normalized state. The recipient verifies the EDC asset digest before verifying and decrypting the Package. The payload travels once through the EDC data plane and is not copied into Native Package storage.

On this page
Machine-readable contract

Endpoint Reference

Generated from the same OpenAPI document and validated examples used by the release gate.

Operations
21
Groups
8
Examples
29
Version
1.0.0

Agents

Agent registration and capability discovery

4 operations
POST/v1/agents/registerRegister an Agent and its public capabilitiesVerified
Operation ID
registerAgent
Authentication
oauth2 + mutualTLS
Success
201 Agent registered

Parameters

NameInTypeRequiredDescription
X-Correlation-IDheaderstringYesEnd-to-end opaque trace identifier; must not contain business plaintext
Idempotency-KeyheaderstringYesDeduplicates a mutation within organization and endpoint scope

Responses

201Agent registeredAgentResource
400Machine-readable problem detailsProblem
401Machine-readable problem detailsProblem
409Machine-readable problem detailsProblem
AgentRegistration requestcompany Agent registration
{
  "organization_id": "org_tier2_connector",
  "agent_id": "agent_component_planning",
  "implementation": "Example customer Agent",
  "implementation_version": "1.4.2",
  "protocol_versions": [
    "supply-y/1.0"
  ],
  "skill_versions": {
    "supply-y.material-risk": "0.1.0"
  },
  "transport_modes": [
    "native",
    "catena_x"
  ],
  "keys": [
    {
      "key_id": "key_agent_signing_001",
      "use": "signing",
      "format": "jwk",
      "public_key": {
        "kty": "EC",
        "crv": "P-256",
        "x": "dGYfT0l9RRW59X3XsupEsWkZC78_JzC1xsdH37DNZi4",
        "y": "84vpdXTFail2FD25x69kLAzu-sLfywoBgWI4G4x7U6o"
      },
      "status": "active",
      "valid_from": "2026-07-01T00:00:00Z",
      "registered_at": "2026-07-01T00:00:00Z"
    },
    {
      "key_id": "key_agent_encryption_001",
      "use": "encryption",
      "format": "jwk",
      "public_key": {
        "kty": "EC",
        "crv": "P-256",
        "x": "A5vk4f0fSUkcBhyxZkTQwZmb_KXyZxWsTA8dCbLS6oI",
        "y": "hOaSYsBsnReZgHfwVbUFq83NJ3RcO4QbflhLcmMe7wU"
      },
      "status": "active",
      "valid_from": "2026-07-01T00:00:00Z",
      "registered_at": "2026-07-01T00:00:00Z"
    }
  ]
}
AgentResource responseactive registered Agent
{
  "organization_id": "org_tier2_connector",
  "agent_id": "agent_component_planning",
  "implementation": "Example customer Agent",
  "implementation_version": "1.4.2",
  "protocol_versions": [
    "supply-y/1.0"
  ],
  "skill_versions": {
    "supply-y.material-risk": "0.1.0"
  },
  "transport_modes": [
    "native",
    "catena_x"
  ],
  "keys": [
    {
      "key_id": "key_agent_signing_001",
      "use": "signing",
      "format": "jwk",
      "public_key": {
        "kty": "EC",
        "crv": "P-256",
        "x": "dGYfT0l9RRW59X3XsupEsWkZC78_JzC1xsdH37DNZi4",
        "y": "84vpdXTFail2FD25x69kLAzu-sLfywoBgWI4G4x7U6o"
      },
      "status": "active",
      "valid_from": "2026-07-01T00:00:00Z",
      "registered_at": "2026-07-01T00:00:00Z"
    },
    {
      "key_id": "key_agent_encryption_001",
      "use": "encryption",
      "format": "jwk",
      "public_key": {
        "kty": "EC",
        "crv": "P-256",
        "x": "A5vk4f0fSUkcBhyxZkTQwZmb_KXyZxWsTA8dCbLS6oI",
        "y": "hOaSYsBsnReZgHfwVbUFq83NJ3RcO4QbflhLcmMe7wU"
      },
      "status": "active",
      "valid_from": "2026-07-01T00:00:00Z",
      "registered_at": "2026-07-01T00:00:00Z"
    }
  ],
  "status": "active",
  "registered_at": "2026-07-01T00:00:00Z",
  "certification_status": "compatible"
}
GET/v1/agents/{agent_id}Read verified Agent status and compatibilityVerified
Operation ID
getAgent
Authentication
oauth2 + mutualTLS
Success
200 Agent resource

Parameters

NameInTypeRequiredDescription
agent_idpathAgentIdYes-
X-Correlation-IDheaderstringYesEnd-to-end opaque trace identifier; must not contain business plaintext

Responses

200Agent resourceAgentResource
401Machine-readable problem detailsProblem
403Machine-readable problem detailsProblem
404Machine-readable problem detailsProblem
AgentResource responseactive registered Agent
{
  "organization_id": "org_tier2_connector",
  "agent_id": "agent_component_planning",
  "implementation": "Example customer Agent",
  "implementation_version": "1.4.2",
  "protocol_versions": [
    "supply-y/1.0"
  ],
  "skill_versions": {
    "supply-y.material-risk": "0.1.0"
  },
  "transport_modes": [
    "native",
    "catena_x"
  ],
  "keys": [
    {
      "key_id": "key_agent_signing_001",
      "use": "signing",
      "format": "jwk",
      "public_key": {
        "kty": "EC",
        "crv": "P-256",
        "x": "dGYfT0l9RRW59X3XsupEsWkZC78_JzC1xsdH37DNZi4",
        "y": "84vpdXTFail2FD25x69kLAzu-sLfywoBgWI4G4x7U6o"
      },
      "status": "active",
      "valid_from": "2026-07-01T00:00:00Z",
      "registered_at": "2026-07-01T00:00:00Z"
    },
    {
      "key_id": "key_agent_encryption_001",
      "use": "encryption",
      "format": "jwk",
      "public_key": {
        "kty": "EC",
        "crv": "P-256",
        "x": "A5vk4f0fSUkcBhyxZkTQwZmb_KXyZxWsTA8dCbLS6oI",
        "y": "hOaSYsBsnReZgHfwVbUFq83NJ3RcO4QbflhLcmMe7wU"
      },
      "status": "active",
      "valid_from": "2026-07-01T00:00:00Z",
      "registered_at": "2026-07-01T00:00:00Z"
    }
  ],
  "status": "active",
  "registered_at": "2026-07-01T00:00:00Z",
  "certification_status": "compatible"
}
POST/v1/agents/{agent_id}/keysRegister a replacement signing or encryption public keyVerified
Operation ID
registerAgentKey
Authentication
oauth2 + mutualTLS
Success
201 Public key registered

Parameters

NameInTypeRequiredDescription
agent_idpathAgentIdYes-
X-Correlation-IDheaderstringYesEnd-to-end opaque trace identifier; must not contain business plaintext
Idempotency-KeyheaderstringYesDeduplicates a mutation within organization and endpoint scope

Responses

201Public key registeredPublicKey
400Machine-readable problem detailsProblem
401Machine-readable problem detailsProblem
403Machine-readable problem detailsProblem
409Machine-readable problem detailsProblem
KeyRegistration requestreplacement signing key
{
  "key_id": "key_agent_signing_002",
  "use": "signing",
  "format": "jwk",
  "public_key": {
    "kty": "EC",
    "crv": "P-256",
    "x": "qI6D_5ol-FtA4jLKQlyTn-TEeWQHjQkF9jEo4kIoUWA",
    "y": "6jwwnYjU5sA1yYWh4xm8XwVFFBf5E3v0jPkTbHTr5q4"
  },
  "valid_from": "2026-07-15T00:00:00Z",
  "replaces_key_id": "key_agent_signing_001"
}
PublicKey responseactive signing key
{
  "key_id": "key_agent_signing_001",
  "use": "signing",
  "format": "jwk",
  "public_key": {
    "kty": "EC",
    "crv": "P-256",
    "x": "dGYfT0l9RRW59X3XsupEsWkZC78_JzC1xsdH37DNZi4",
    "y": "84vpdXTFail2FD25x69kLAzu-sLfywoBgWI4G4x7U6o"
  },
  "status": "active",
  "valid_from": "2026-07-01T00:00:00Z",
  "registered_at": "2026-07-01T00:00:00Z"
}
POST/v1/agents/{agent_id}/keys/{key_id}/revokeRevoke a signing or encryption key and record its trust cutoffVerified
Operation ID
revokeAgentKey
Authentication
oauth2 + mutualTLS
Success
200 Key revoked and immutable lifecycle event recorded

Parameters

NameInTypeRequiredDescription
agent_idpathAgentIdYes-
key_idpathstringYes-
X-Correlation-IDheaderstringYesEnd-to-end opaque trace identifier; must not contain business plaintext
Idempotency-KeyheaderstringYesDeduplicates a mutation within organization and endpoint scope

Responses

200Key revoked and immutable lifecycle event recordedPublicKey
400Machine-readable problem detailsProblem
401Machine-readable problem detailsProblem
403Machine-readable problem detailsProblem
404Machine-readable problem detailsProblem
409Machine-readable problem detailsProblem
KeyRevocationRequest requestcompromised key
{
  "invalid_from": "2026-07-14T18:30:00Z",
  "reason_code": "compromised",
  "evidence_reference": "incident/key-compromise-2026-07-14"
}
PublicKey responseactive signing key
{
  "key_id": "key_agent_signing_001",
  "use": "signing",
  "format": "jwk",
  "public_key": {
    "kty": "EC",
    "crv": "P-256",
    "x": "dGYfT0l9RRW59X3XsupEsWkZC78_JzC1xsdH37DNZi4",
    "y": "84vpdXTFail2FD25x69kLAzu-sLfywoBgWI4G4x7U6o"
  },
  "status": "active",
  "valid_from": "2026-07-01T00:00:00Z",
  "registered_at": "2026-07-01T00:00:00Z"
}

Skills

Signed Skill release discovery

2 operations
GET/v1/skillsList compatible signed Skill releasesVerified

Returns release manifests compatible with the requested protocol version. Skill artifacts are signed and content-addressed.

Operation ID
listSkillReleases
Authentication
oauth2 + mutualTLS
Success
200 Compatible signed Skill releases

Parameters

NameInTypeRequiredDescription
X-Correlation-IDheaderstringYesEnd-to-end opaque trace identifier; must not contain business plaintext
protocol_versionquerystringNo-
afterquerystringNo-
limitqueryintegerNo-

Responses

200Compatible signed Skill releasesSkillReleasePage
400Machine-readable problem detailsProblem
401Machine-readable problem detailsProblem
403Machine-readable problem detailsProblem
SkillReleasePage responseone compatible Skill
{
  "items": [
    {
      "skill_id": "supply-y.material-risk",
      "version": "0.1.0",
      "release_channel": "preview",
      "protocol_range": ">=supply-y/1.0 <supply-y/2.0",
      "schema_refs": [
        "https://supply-y.vercel.app/docs/reference#supply-y-reasoning-package",
        "https://supply-y.vercel.app/docs/reference#supply-y-response-object"
      ],
      "artifact_url": "https://supply-y.vercel.app/skills/supply-y.material-risk/0.1.0/artifact.json",
      "artifact_digest": "sha-256=:jR7qO8quDGYHqtXPZ+wQC6m+/gKLrBahmam11aqETvE=:",
      "published_at": "2026-07-14T20:00:00Z",
      "update_policy": {
        "classification": "initial",
        "supersedes": null,
        "download_policy": "automatic_allowed",
        "activation_policy": "operator_approval_required",
        "minimum_supported_version": "0.1.0"
      },
      "manifest_signature": {
        "key_id": "key_supply_y_preview_skill_2026_01",
        "algorithm": "ES256",
        "signature": "T_CjxYN5gDxeN4foumQ6lXoyvnDSlWGMVKZsD7Yw0u_yFo-6RCjzKfIEHj0Q79LCEG-uau-aC_CQCWKtUkGC2g"
      }
    }
  ],
  "next_cursor": null,
  "has_more": false
}
GET/v1/skills/{skill_id}/releases/{version}Resolve one signed Skill releaseVerified
Operation ID
getSkillRelease
Authentication
oauth2 + mutualTLS
Success
200 Signed Skill release manifest

Parameters

NameInTypeRequiredDescription
skill_idpathstringYes-
versionpathstringYes-
X-Correlation-IDheaderstringYesEnd-to-end opaque trace identifier; must not contain business plaintext

Responses

200Signed Skill release manifestSkillRelease
401Machine-readable problem detailsProblem
403Machine-readable problem detailsProblem
404Machine-readable problem detailsProblem
SkillRelease responsematerial risk Skill
{
  "skill_id": "supply-y.material-risk",
  "version": "0.1.0",
  "release_channel": "preview",
  "protocol_range": ">=supply-y/1.0 <supply-y/2.0",
  "schema_refs": [
    "https://supply-y.vercel.app/docs/reference#supply-y-reasoning-package",
    "https://supply-y.vercel.app/docs/reference#supply-y-response-object"
  ],
  "artifact_url": "https://supply-y.vercel.app/skills/supply-y.material-risk/0.1.0/artifact.json",
  "artifact_digest": "sha-256=:jR7qO8quDGYHqtXPZ+wQC6m+/gKLrBahmam11aqETvE=:",
  "published_at": "2026-07-14T20:00:00Z",
  "update_policy": {
    "classification": "initial",
    "supersedes": null,
    "download_policy": "automatic_allowed",
    "activation_policy": "operator_approval_required",
    "minimum_supported_version": "0.1.0"
  },
  "manifest_signature": {
    "key_id": "key_supply_y_preview_skill_2026_01",
    "algorithm": "ES256",
    "signature": "T_CjxYN5gDxeN4foumQ6lXoyvnDSlWGMVKZsD7Yw0u_yFo-6RCjzKfIEHj0Q79LCEG-uau-aC_CQCWKtUkGC2g"
  }
}

Directory

Verified recipient keys and capabilities

2 operations
GET/v1/directory/agents/{agent_id}/keysRead current verified signing and encryption keysVerified
Operation ID
getAgentKeys
Authentication
oauth2 + mutualTLS
Success
200 Verified public keys

Parameters

NameInTypeRequiredDescription
agent_idpathAgentIdYes-
X-Correlation-IDheaderstringYesEnd-to-end opaque trace identifier; must not contain business plaintext

Responses

200Verified public keysKeyDirectoryResponse
401Machine-readable problem detailsProblem
403Machine-readable problem detailsProblem
404Machine-readable problem detailsProblem
KeyDirectoryResponse responseAgent key directory
{
  "directory_version": "keydir_agent_component_planning_004",
  "generated_at": "2026-07-14T19:00:00Z",
  "organization_id": "org_tier2_connector",
  "agent_id": "agent_component_planning",
  "keys": [
    {
      "key_id": "key_agent_signing_001",
      "use": "signing",
      "format": "jwk",
      "public_key": {
        "kty": "EC",
        "crv": "P-256",
        "x": "dGYfT0l9RRW59X3XsupEsWkZC78_JzC1xsdH37DNZi4",
        "y": "84vpdXTFail2FD25x69kLAzu-sLfywoBgWI4G4x7U6o"
      },
      "status": "active",
      "valid_from": "2026-07-01T00:00:00Z",
      "registered_at": "2026-07-01T00:00:00Z"
    },
    {
      "key_id": "key_agent_encryption_001",
      "use": "encryption",
      "format": "jwk",
      "public_key": {
        "kty": "EC",
        "crv": "P-256",
        "x": "A5vk4f0fSUkcBhyxZkTQwZmb_KXyZxWsTA8dCbLS6oI",
        "y": "hOaSYsBsnReZgHfwVbUFq83NJ3RcO4QbflhLcmMe7wU"
      },
      "status": "active",
      "valid_from": "2026-07-01T00:00:00Z",
      "registered_at": "2026-07-01T00:00:00Z"
    }
  ]
}
GET/v1/directory/notification-keysRead Supply-Y webhook-signing public keysVerified

Returns current and retiring platform keys that an Agent can pin before activating a webhook endpoint. Private keys are never exposed.

Operation ID
getNotificationSigningKeys
Authentication
oauth2 + mutualTLS
Success
200 Versioned Supply-Y notification-signing key directory

Parameters

NameInTypeRequiredDescription
X-Correlation-IDheaderstringYesEnd-to-end opaque trace identifier; must not contain business plaintext

Responses

200Versioned Supply-Y notification-signing key directoryNotificationKeyDirectory
401Machine-readable problem detailsProblem
403Machine-readable problem detailsProblem
NotificationKeyDirectory responseSupply-Y notification keys
{
  "directory_version": "notification_keydir_004",
  "generated_at": "2026-07-14T19:00:00Z",
  "keys": [
    {
      "key_id": "key_agent_signing_001",
      "use": "signing",
      "format": "jwk",
      "public_key": {
        "kty": "EC",
        "crv": "P-256",
        "x": "dGYfT0l9RRW59X3XsupEsWkZC78_JzC1xsdH37DNZi4",
        "y": "84vpdXTFail2FD25x69kLAzu-sLfywoBgWI4G4x7U6o"
      },
      "status": "active",
      "valid_from": "2026-07-01T00:00:00Z",
      "registered_at": "2026-07-01T00:00:00Z"
    }
  ]
}

Policy

Signed sender claims about local disclosure and approval checks

2 operations
POST/v1/policy-receiptsRecord a signed local-policy evaluation before Package submissionVerified

Supply-Y verifies the sender identity, signature and metadata binding without receiving or inspecting business plaintext. A verified signature proves who made the claim, not whether the underlying business statement is true.

Operation ID
createPolicyReceipt
Authentication
oauth2 + mutualTLS
Success
201 Policy receipt signature and claim structure accepted

Parameters

NameInTypeRequiredDescription
X-Correlation-IDheaderstringYesEnd-to-end opaque trace identifier; must not contain business plaintext
Idempotency-KeyheaderstringYesDeduplicates a mutation within organization and endpoint scope

Responses

201Policy receipt signature and claim structure acceptedPolicyReceiptResource
400Machine-readable problem detailsProblem
401Machine-readable problem detailsProblem
403Machine-readable problem detailsProblem
409Machine-readable problem detailsProblem
PolicyReceiptCreate requestsigned local policy claim
{
  "policy_receipt_id": "polrec_material_risk_family_level_001",
  "receipt_version": "1.0.0",
  "package_id": "pkg_material_constraint_001",
  "thread_id": "thread_material_constraint_01",
  "sender_org_id": "org_tier3_material",
  "sender_agent_id": "agent_material_risk",
  "recipient_org_id": "org_tier2_connector",
  "recipient_agent_id": "agent_component_planning",
  "protocol_version": "supply-y/1.0",
  "skill_id": "supply-y.material-risk",
  "skill_version": "0.1.0",
  "content_digest": "sha-256=:0lYf4IyJ08r4292s/NJvaKu1JXi5cjXjaT0HNpt6r04=:",
  "policy_id": "pol_material_risk_family_level_v1",
  "policy_schema_version": "1.0.0",
  "policy_digest": "sha-256=:u6yGoL8W/zLHh53rc+jjLlYIAonpQkJ9AOAKUM03sz4=:",
  "checks": [
    {
      "check_id": "object_schema",
      "outcome": "passed"
    },
    {
      "check_id": "skill_profile",
      "outcome": "passed"
    },
    {
      "check_id": "prohibited_disclosure",
      "outcome": "passed"
    },
    {
      "check_id": "recipient_authorization",
      "outcome": "passed"
    },
    {
      "check_id": "retention_and_forwarding",
      "outcome": "passed"
    }
  ],
  "human_approval": {
    "required": true,
    "outcome": "approved",
    "approval_reference": "approval_tier3_material_001",
    "approved_at": "2026-07-03T17:59:45Z"
  },
  "evaluated_at": "2026-07-03T17:59:50Z",
  "statement": "sender_asserts_local_policy_evaluation",
  "signature": {
    "key_id": "key_sender_signing_001",
    "algorithm": "ES256",
    "signature": "QCYrL9sFvtv8VD4xMEdUXGYJfrfMP0v2xcfwMkBFrH2VV_9ntKPo2X5X_wkXpEwmqAG0P--NuZJjoFLkxSWznA"
  }
}
PolicyReceiptResource responseaccepted policy receipt
{
  "receipt": {
    "policy_receipt_id": "polrec_material_risk_family_level_001",
    "receipt_version": "1.0.0",
    "package_id": "pkg_material_constraint_001",
    "thread_id": "thread_material_constraint_01",
    "sender_org_id": "org_tier3_material",
    "sender_agent_id": "agent_material_risk",
    "recipient_org_id": "org_tier2_connector",
    "recipient_agent_id": "agent_component_planning",
    "protocol_version": "supply-y/1.0",
    "skill_id": "supply-y.material-risk",
    "skill_version": "0.1.0",
    "content_digest": "sha-256=:0lYf4IyJ08r4292s/NJvaKu1JXi5cjXjaT0HNpt6r04=:",
    "policy_id": "pol_material_risk_family_level_v1",
    "policy_schema_version": "1.0.0",
    "policy_digest": "sha-256=:u6yGoL8W/zLHh53rc+jjLlYIAonpQkJ9AOAKUM03sz4=:",
    "checks": [
      {
        "check_id": "object_schema",
        "outcome": "passed"
      },
      {
        "check_id": "skill_profile",
        "outcome": "passed"
      },
      {
        "check_id": "prohibited_disclosure",
        "outcome": "passed"
      },
      {
        "check_id": "recipient_authorization",
        "outcome": "passed"
      },
      {
        "check_id": "retention_and_forwarding",
        "outcome": "passed"
      }
    ],
    "human_approval": {
      "required": true,
      "outcome": "approved",
      "approval_reference": "approval_tier3_material_001",
      "approved_at": "2026-07-03T17:59:45Z"
    },
    "evaluated_at": "2026-07-03T17:59:50Z",
    "statement": "sender_asserts_local_policy_evaluation",
    "signature": {
      "key_id": "key_sender_signing_001",
      "algorithm": "ES256",
      "signature": "QCYrL9sFvtv8VD4xMEdUXGYJfrfMP0v2xcfwMkBFrH2VV_9ntKPo2X5X_wkXpEwmqAG0P--NuZJjoFLkxSWznA"
    }
  },
  "accepted_at": "2026-07-03T17:59:51Z",
  "signature_status": "verified",
  "package_authorization": "eligible",
  "audit_event_id": "event_policy_receipt_accepted_001"
}
GET/v1/policy-receipts/{policy_receipt_id}Read an authorized signed policy receipt and its platform decisionVerified
Operation ID
getPolicyReceipt
Authentication
oauth2 + mutualTLS
Success
200 Authorized policy receipt resource

Parameters

NameInTypeRequiredDescription
policy_receipt_idpathstringYes-
X-Correlation-IDheaderstringYesEnd-to-end opaque trace identifier; must not contain business plaintext

Responses

200Authorized policy receipt resourcePolicyReceiptResource
401Machine-readable problem detailsProblem
403Machine-readable problem detailsProblem
404Machine-readable problem detailsProblem
PolicyReceiptResource responseaccepted policy receipt
{
  "receipt": {
    "policy_receipt_id": "polrec_material_risk_family_level_001",
    "receipt_version": "1.0.0",
    "package_id": "pkg_material_constraint_001",
    "thread_id": "thread_material_constraint_01",
    "sender_org_id": "org_tier3_material",
    "sender_agent_id": "agent_material_risk",
    "recipient_org_id": "org_tier2_connector",
    "recipient_agent_id": "agent_component_planning",
    "protocol_version": "supply-y/1.0",
    "skill_id": "supply-y.material-risk",
    "skill_version": "0.1.0",
    "content_digest": "sha-256=:0lYf4IyJ08r4292s/NJvaKu1JXi5cjXjaT0HNpt6r04=:",
    "policy_id": "pol_material_risk_family_level_v1",
    "policy_schema_version": "1.0.0",
    "policy_digest": "sha-256=:u6yGoL8W/zLHh53rc+jjLlYIAonpQkJ9AOAKUM03sz4=:",
    "checks": [
      {
        "check_id": "object_schema",
        "outcome": "passed"
      },
      {
        "check_id": "skill_profile",
        "outcome": "passed"
      },
      {
        "check_id": "prohibited_disclosure",
        "outcome": "passed"
      },
      {
        "check_id": "recipient_authorization",
        "outcome": "passed"
      },
      {
        "check_id": "retention_and_forwarding",
        "outcome": "passed"
      }
    ],
    "human_approval": {
      "required": true,
      "outcome": "approved",
      "approval_reference": "approval_tier3_material_001",
      "approved_at": "2026-07-03T17:59:45Z"
    },
    "evaluated_at": "2026-07-03T17:59:50Z",
    "statement": "sender_asserts_local_policy_evaluation",
    "signature": {
      "key_id": "key_sender_signing_001",
      "algorithm": "ES256",
      "signature": "QCYrL9sFvtv8VD4xMEdUXGYJfrfMP0v2xcfwMkBFrH2VV_9ntKPo2X5X_wkXpEwmqAG0P--NuZJjoFLkxSWznA"
    }
  },
  "accepted_at": "2026-07-03T17:59:51Z",
  "signature_status": "verified",
  "package_authorization": "eligible",
  "audit_event_id": "event_policy_receipt_accepted_001"
}

Packages

Encrypted Package lifecycle

5 operations
POST/v1/packagesCreate one Native or Catena-X Package transferVerified

The inner Supply-Y object is already encrypted in Native Mode. Catena-X Mode submits EDC transfer references and integrity metadata instead of duplicate ciphertext. Package metadata must reference an accepted, signature-verified policy receipt with matching sender, recipient, Skill, Package and content digest.

Operation ID
createPackageTransfer
Authentication
oauth2 + mutualTLS
Success
202 Package accepted for durable delivery

Parameters

NameInTypeRequiredDescription
X-Correlation-IDheaderstringYesEnd-to-end opaque trace identifier; must not contain business plaintext
Idempotency-KeyheaderstringYesDeduplicates a mutation within organization and endpoint scope

Responses

202Package accepted for durable deliveryPackageResource
400Machine-readable problem detailsProblem
401Machine-readable problem detailsProblem
403Machine-readable problem detailsProblem
409Machine-readable problem detailsProblem
413Machine-readable problem detailsProblem
429Machine-readable problem detailsProblem
PackageCreate requestNative signed exchange
{
  "signature": "YCGjpUj1jq2GpCqDHNkwIp-jkV5-vxRfYBFf2sEmOxktnNNm5SdWtWgvCFlVQBL3SGOr9TniROpcYq1pYc_aMA",
  "payload": "eyJqd2UiOnsiYWFkIjoiZXlKamIyNTBaVzUwWDJScFoyVnpkQ0k2SW5Ob1lTMHlOVFk5T2pCc1dXWTBTWGxLTURoeU5ESTVNbk12VGtwMllVdDFNVXBZYVRWamFsaHFZVlF3U0U1d2REWnlNRFE5T2lJc0ltTnZiblJsYm5SZmRIbHdaU0k2SW1Gd2NHeHBZMkYwYVc5dUwzTjFjSEJzZVMxNUxuSmxZWE52Ym1sdVp5MXdZV05yWVdkbEsycHpiMjRpTENKamNtVmhkR1ZrWDJGMElqb2lNakF5Tmkwd055MHdNMVF4T0Rvd01Eb3dNRm9pTENKbGVIQnBjbVZ6WDJGMElqb2lNakF5Tmkwd09DMHdNbFF4T0Rvd01Eb3dNRm9pTENKd1lXTnJZV2RsWDJsa0lqb2ljR3RuWDIxaGRHVnlhV0ZzWDJOdmJuTjBjbUZwYm5SZk1EQXhJaXdpY0c5c2FXTjVYM0psWTJWcGNIUmZhV1FpT2lKd2IyeHlaV05mYldGMFpYSnBZV3hmY21semExOW1ZVzFwYkhsZmJHVjJaV3hmTURBeElpd2ljSEp2ZEc5amIyeGZkbVZ5YzJsdmJpSTZJbk4xY0hCc2VTMTVMekV1TUNJc0luSmxZMmx3YVdWdWRGOWhaMlZ1ZEY5cFpDSTZJbUZuWlc1MFgyTnZiWEJ2Ym1WdWRGOXdiR0Z1Ym1sdVp5SXNJbkpsWTJsd2FXVnVkRjl2Y21kZmFXUWlPaUp2Y21kZmRHbGxjakpmWTI5dWJtVmpkRzl5SWl3aWMyTm9aVzFoWDNabGNuTnBiMjRpT2lJeExqQXVNQ0lzSW5ObGJtUmxjbDloWjJWdWRGOXBaQ0k2SW1GblpXNTBYMjFoZEdWeWFXRnNYM0pwYzJzaUxDSnpaVzVrWlhKZmIzSm5YMmxrSWpvaWIzSm5YM1JwWlhJelgyMWhkR1Z5YVdGc0lpd2ljMnRwYkd4ZmFXUWlPaUp6ZFhCd2JIa3RlUzV0WVhSbGNtbGhiQzF5YVhOcklpd2ljMnRwYkd4ZmRtVnljMmx2YmlJNklqQXVNUzR3SWl3aWRHaHlaV0ZrWDJsa0lqb2lkR2h5WldGa1gyMWhkR1Z5YVdGc1gyTnZibk4wY21GcGJuUmZNREVpTENKMGNtRnVjM0J2Y25SZmJXOWtaU0k2SW01aGRHbDJaU0o5IiwiY2lwaGVydGV4dCI6IkVxbGtOMk5FTUFSdG5MaTJNczFuN291cUxCUUFSbFZWaWVhREFsX0lFZElOYWlueXZiZVEtdnZUYmpMeUNoV3pJWm83NnNSQkZfNEhZbDc3SndvMDBPbFNkcWpqRzc0SkxkVEJJR0JCM1JidnV3U1BwRkdySDA1OU5peUdsNmdwUFQ1c1RvT2FIb2hkR2xJTGZISU9FNGRHRnM1bThxNjdTWDQ0WTFiX1JaNnhLTlplbnoteEdSWGxtbVd1OXZFa1pORG9taWswOFh1ZWlSLTlGUjV0TDdwTEdMNjdWUWQ5ZklSREQ4Q0JrTGNBYVB3R19zTGY3dFJhUTZacHgxT1ZZeFFhbDhQcW1ZeWt5ZmZMOEJPWEt0NVFFOEdtVUh6Z0hKaXNNQnlBSnNNSXFWVkp0MWtiSTlKdDJKQV85c3F0azVKaUZfTVVuU2F4LTRMci1IMm9faUZzdGZfN3l3ZjZhYUVvb2ctcHZsWDVGX1AwV3Y2V085a2xuSldram1vYzBKQ2F2TjdPMmdLTzRIYTd4ZF9LdDZOWU0tQk1FYk5EdnJ5NjFOZzR0aVlpSTVoWXVpTDc1bXByNlRBQmxZTGpBR3hIRUNwcVBFTGVzR3l0QXJyZjg2Ynp0MFNIdU9lTE1CaTVmVzc2ci1jSjNRSkNsOVhjSHFLMkNYQlRnUXYyaGFOd19QenI2X08wNktCbzhhN2pKQWZGNHB5d3FiME8tdkV3Y0pnNmNLWWNlTkNQaWJ3U0w3cjN6dWpqOUlkNzduZ0tNa3Vva3JEcnZPWWs0eGhVYVhWbk4xWGw3dHBjSFpHWGVqWnR0Z0JwdGNHbVFHZWhLS3BDeGpFbGpudHFVRnI1Sy1PZjRmZ25XbHNFVzQwQUozQTVydTVzM3RoWm5nTTY2dk1JSnlJSW9RdkxsTE9zQTM2cEd0V1A5Y2JPYVZGaGFnN0R6YjFEOVNWUDF3VC1NdThuYV9WcjJjVmp1NFhlNl9fb3Q3T09VR092NmRHaktuaWluRXlPaDdvNDlBU0tIaDIwRXRMZXE1Q1p3QWRqZlN2QUpBS2FNbVkta0VKRy1BTDQtM2FPZFREOTJtaV82VzVEVFMyOGNrdTZYcXFaaEJTNGZMTGhTemtWaUJydzJTN1d3WXRISlVJSVpCR29TaEtFR21NaWktWHJYVXMzaTdMY0FDS09HUXZUa1JXQmZBY1YyblFJdUMxTnZYS0kzYXhRY0JSQTJhZ09WcURXMDVmdUwtendRa2E2Skx0cENiUnlfelhta0Z6YzdDUEJJdUpEVEloaDZ6WTZ4andGRzRPdnFEeUlFdXhLQjZFMk9JaGJabGJ6b3EwNWJ4MGdISUl5VVVfTlBtR19WY3ZOUlBQQVJxd3RMM1ExSmZoQ2tMQlRFN2RweUxhbDlZblo5cmpxZjBPQkZ6cWZHX3lrRl9XSWdDRmhyZnRXWGZMX3BMZFZETGRiZk9XdEVYaXFXc1UydFMtR2RyWjNMSEpVTmJBUzhQVnZ5Rm1SZXVMMjNkS3Jwa1dQTzVNcUEtcVJGdVhCY0xQRnh0SjBTWnRlck1JYmtfZWR4MnQ2WXpCbVhnMmV4UzV5TVhVOEp5OVBvOU1fNUFXQ0hERmsteEFSdE5QeW40RkZkS1RKZURKeXJVSENIRDNaTUdZcHA3UmJqMGR1ZGVOWURnNThMeFhHdjBlOHU3eG9XRDdtUFZrT3R3b3U4ZGhncDZvbGJQaWxMVUVfelFqa044WEtXX2RzWE1RRXd5MGdPSHZiQWhpWkJJbG5idHVzb29hR182VXFlZkk5REJHMWRCZlZibFp3amhULXNZNS1UWUNid2k4VnMwU1BCQmY4YUxaLV9JUzd3YWl6YkxBT000NDhGQkNUbjc5T3RZVjVzY0FiZ0RFQlR3NlNjREp5akswMkNKcWxpem56TUQwNDdtNnFnLS1GSmlYUWs2ZHEzOFV4Z19rdlZ2MEhhZWM3VGx1eExfci03NEtkM3NMTThTNFZlQnZpZmRpMWN1UlNITjl5TFJwN0l4aW5yd0M5dWtKLUZicE5zcW9qZ3NCdW5YeGVYOFhzMXlMU3VHOTJUOGV1VlBoYVdKSk1mWFpJaEtUVDAwLWhBNzRhWjBrbG9zeW9NUWJMNFdhTzNtYVVnZUFZZHlTUEtRTFFfaWVEdzQ2dER5RXB4Z1NvcF8wRmwzWGF4bkN1MUNfRHE5Qk5mN0NSbmdGNWhnVnVoaHI2eGctZS0xQVRMMVhPLU1Lb2s2ekhSUjZkRnFqcVV6OXNBcG1yalQ0U0Q2SV9zQ2gzWkZkQmFWU0FiT3BIMk04LTh0TS1mRXg0M0pVTGU3anRhTTVQT0NXT1J0WDF5QVhIMzZhelV1Sm1OU0R2TnpRLVM1T1RnVlFRaVpPMzJoZG1DVmlHNkNzT3k5NVRSbmt0cklRVmI1YVI0RnNmOGFTZEJMYkJWYjZpT0ZrazR6cWhBUlRYZlRUSjdGR2hhcmt4NngzVUs1aFBvMmRQV2xQUnZIMmhKUnRWV2FXZkg0bmtPT0wyUEJxazNsMzZaeHlQelo2dXFaRVRMSlREX0N5ME5BdmV0cTJXZXpzSzh3TUpwem5CejdHdjdtQVJKZFpJZVRLei11U1FTbFc2REZUTlpUOXFfdzB2MUJxQzdzSGVMVEV3RlQ0dWV6SVNEMV95WUx5eW9PV1B1eEctcVdNV0tSN3NSMkMyOUJhZ2lILUowR2JTOGp5UFpKS2hWdmRya0hIaWFmZUE0S0t0SDZJS2EySEdILTQtNmtvQ3B0MUV4VUtiUm9uZ3d2M3ljRXI4bS0way05cDUteVFFcDdkZl9LUmpwNTNTY2t2Z1owcnltYVN0VnBWamNFMWlTNGVyaEJCOG10NFd4aHdoRDFOQ21iSjNJRkEwU1Qzbk15MjE0NzUyVHBZb2JLa2s2d2lQRW9GSVNrdUF4clpQc0dFQVpGZFBXNkZKelF4WjRkTTF3NkhBelhLUlhDaE9MSm1scDdCQ2sxTHdqYS0xN0Njb09ydDZDX1hmVG94VG1zb25SRWZxeFNsYTFfcHJwdVVsVjR3VW1aSllTNDBEbXpXXy04alJ3bXBYUE1od3BQSXUwWnE0Z3hndTk4VnNpbDdfUzFiVG1xaHZELVNsMmVmTkNHeDcxOTV6dEdCekN4aGRDQnlpZUs4ZmlPMVNscXhSZm1EYUVrR2NWRGVwSGZ6WHRVREtMVWU1TDA1X19BZHhmTkNsblQ3WGJyYkJhNk5iMnFpbDdyTHYyZklpclZ5TE1JUXdBM2N1VzkzUUdoSmVnbmlwWC1obkxwTDk4ck5GNU4ycFpXc0RFRlRLQVdzSlZGUkE0TjI0N3NYU1NWQWNzcTNXTkhZdkZQMTJseWY3ZnNRdGpVMGVJNFF0S2w2SXc0LTR6ZmhKT2VlVTJ4S2RySjVXb2U2N0ZMYXFoYmkyaF9WVlJ3UVVLWXk4MF9KY1RHMmYzZzJkYmtzd3ZUZk9HSURzLUY3NWdKdlVLaWVHLU1QbmNkUjJDWFRRVGJ1UzlSMTNrbHBDb2hZYW1BS0dsMS1kQ0tCdGdjM1M2VEM0N0lhMjZJNXNua1JrN1hrQlpIY1NtNFBkcWE1MHpMdFppOGpoWmRfTkFOcjZlcnhiSW85YXRQX3BFLUQ3aFktQmEtNGxtOHVGaU1KYWg2XzZaVmYtYjFBaUhTWG9LZE5OTTZqN3A2NC1heWRwZVpJRWgteFk2Q2xBZjdOZzN2QTdvZDhDV1BWZFdDUzBzZC1QT3FMQmhzSE5nY1k5VmJtWXJvYTJSd3d0VzNYVmxmekoxZzhRUWFvc3ZzUHRMUjRSZC1wUVktSzVGeHYxYWN3NDhvOHhRN3UxVW4zNlZPcDVlMjg0dW5mREhBcUtPQmtNVDAzdXFQUlBaWGlnbTVMZVR2WWxQQmRLdE5pWkF3NjZUZkNjSWtJZDNCU2NSNXkzRDZUWEZQT2FvRUlpMjRmbEFDUXhmYkh5VUIxcW9DOU5PelhOZkMwIiwiaXYiOiJLa1NxZml3dm05TFk5cWxfIiwicHJvdGVjdGVkIjoiZXlKbGJtTWlPaUpCTWpVMlIwTk5JaXdpZEhsd0lqb2lZWEJ3YkdsallYUnBiMjR2YzNWd2NHeDVMWGtyYW5kbElpd2lZM1I1SWpvaVlYQndiR2xqWVhScGIyNHZjM1Z3Y0d4NUxYa3VjbVZoYzI5dWFXNW5MWEJoWTJ0aFoyVXJhbk52YmlJc0luTjVkaUk2SW5OMWNIQnNlUzE1THpFdU1DSjkiLCJyZWNpcGllbnRzIjpbeyJlbmNyeXB0ZWRfa2V5IjoidWdyTEdfLVBZNnZnMEZoTnNKUGF5d0ZOYk5lOV9SSWhheWxBdlhQbDhGWG9kUVhFb0VnSE9nIiwiaGVhZGVyIjp7ImFsZyI6IkVDREgtRVMrQTI1NktXIiwiZXBrIjp7ImNydiI6IlAtMjU2Iiwia3R5IjoiRUMiLCJ4IjoiM18wa2gtajFRcko4WC1WejJSM3RXTWNBR1JrRjZDa05HN29pVHFHVXJ6QSIsInkiOiI0d2I0QlBQNmZRdlo5LTVIa0RiMnRDa2xXdlY5LUJCYXRPeTNMN3MzLUE4In0sImtpZCI6ImtleV9zZW5kZXJfZW5jcnlwdGlvbl8wMDEifX0seyJlbmNyeXB0ZWRfa2V5IjoiZnJCYS1GYVdVZVZyRlNKUEN0b3c5S3ZuWlhHQXFDR09DMk9IUnhWVTZTSWpHX2xOS3Qzekl3IiwiaGVhZGVyIjp7ImFsZyI6IkVDREgtRVMrQTI1NktXIiwiZXBrIjp7ImNydiI6IlAtMjU2Iiwia3R5IjoiRUMiLCJ4IjoidERQUTRVUGRHYnNBOFBpR2pVMnVTdmhqQ3JZbkRUWFFVbzFWamJwV0o0WSIsInkiOiJGX2VQdmREVFZMZTFiQ2tEUm5qSTNsTmFSZEY5OGV6d3FGTm03R1pJc293In0sImtpZCI6ImtleV9yZWNpcGllbnRfZW5jcnlwdGlvbl8wMDEifX1dLCJ0YWciOiJ4TTd2VHRKTnlMcDE3YU5ueFQzUjlRIn0sIm1ldGFkYXRhIjp7ImNvbnRlbnRfZGlnZXN0Ijoic2hhLTI1Nj06MGxZZjRJeUowOHI0Mjkycy9OSnZhS3UxSlhpNWNqWGphVDBITnB0NnIwND06IiwiY29udGVudF90eXBlIjoiYXBwbGljYXRpb24vc3VwcGx5LXkucmVhc29uaW5nLXBhY2thZ2UranNvbiIsImNyZWF0ZWRfYXQiOiIyMDI2LTA3LTAzVDE4OjAwOjAwWiIsImV4cGlyZXNfYXQiOiIyMDI2LTA4LTAyVDE4OjAwOjAwWiIsInBhY2thZ2VfaWQiOiJwa2dfbWF0ZXJpYWxfY29uc3RyYWludF8wMDEiLCJwb2xpY3lfcmVjZWlwdF9pZCI6InBvbHJlY19tYXRlcmlhbF9yaXNrX2ZhbWlseV9sZXZlbF8wMDEiLCJwcm90b2NvbF92ZXJzaW9uIjoic3VwcGx5LXkvMS4wIiwicmVjaXBpZW50X2FnZW50X2lkIjoiYWdlbnRfY29tcG9uZW50X3BsYW5uaW5nIiwicmVjaXBpZW50X29yZ19pZCI6Im9yZ190aWVyMl9jb25uZWN0b3IiLCJzY2hlbWFfdmVyc2lvbiI6IjEuMC4wIiwic2VuZGVyX2FnZW50X2lkIjoiYWdlbnRfbWF0ZXJpYWxfcmlzayIsInNlbmRlcl9vcmdfaWQiOiJvcmdfdGllcjNfbWF0ZXJpYWwiLCJza2lsbF9pZCI6InN1cHBseS15Lm1hdGVyaWFsLXJpc2siLCJza2lsbF92ZXJzaW9uIjoiMC4xLjAiLCJ0aHJlYWRfaWQiOiJ0aHJlYWRfbWF0ZXJpYWxfY29uc3RyYWludF8wMSIsInRyYW5zcG9ydF9tb2RlIjoibmF0aXZlIn19",
  "protected": "eyJhbGciOiJFUzI1NiIsImtpZCI6ImtleV9zZW5kZXJfc2lnbmluZ18wMDEiLCJ0eXAiOiJhcHBsaWNhdGlvbi9zdXBwbHkteStqd3MiLCJjdHkiOiJhcHBsaWNhdGlvbi9zdXBwbHkteS5leGNoYW5nZS1lbnZlbG9wZStqc29uIiwic3l2Ijoic3VwcGx5LXkvMS4wIn0"
}
PackageCreate requestCatena-X transfer manifest
{
  "transport_mode": "catena_x",
  "metadata": {
    "package_id": "pkg_material_constraint_001",
    "thread_id": "thread_material_constraint_01",
    "sender_org_id": "org_tier3_material",
    "sender_agent_id": "agent_material_risk",
    "recipient_org_id": "org_tier2_connector",
    "recipient_agent_id": "agent_component_planning",
    "protocol_version": "supply-y/1.0",
    "schema_version": "1.0.0",
    "skill_id": "supply-y.material-risk",
    "skill_version": "0.1.0",
    "created_at": "2026-07-03T18:00:00Z",
    "expires_at": "2026-08-02T18:00:00Z",
    "content_type": "application/supply-y.reasoning-package+json",
    "content_digest": "sha-256=:0lYf4IyJ08r4292s/NJvaKu1JXi5cjXjaT0HNpt6r04=:",
    "transport_mode": "catena_x",
    "policy_receipt_id": "polrec_material_risk_family_level_001"
  },
  "edc": {
    "connector_id": "edc_tier3_001",
    "asset_id": "asset_pkg_material_constraint_001",
    "asset_digest": "sha-256=:AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA=:",
    "contract_agreement_id": "contract_agreement_001",
    "transfer_process_id": "transfer_process_001"
  },
  "sender_signature": {
    "key_id": "key_agent_signing_001",
    "algorithm": "ES256",
    "signature": "dGVzdC1vbmx5LXNpZ25hdHVyZQ"
  }
}
PackageResource responseaccepted Native Package
{
  "package_id": "pkg_material_constraint_001",
  "thread_id": "thread_material_constraint_01",
  "transport_mode": "native",
  "state": "accepted",
  "created_at": "2026-07-03T18:00:00Z",
  "updated_at": "2026-07-03T18:00:01Z",
  "metadata": {
    "package_id": "pkg_material_constraint_001",
    "thread_id": "thread_material_constraint_01",
    "sender_org_id": "org_tier3_material",
    "sender_agent_id": "agent_material_risk",
    "recipient_org_id": "org_tier2_connector",
    "recipient_agent_id": "agent_component_planning",
    "protocol_version": "supply-y/1.0",
    "schema_version": "1.0.0",
    "skill_id": "supply-y.material-risk",
    "skill_version": "0.1.0",
    "created_at": "2026-07-03T18:00:00Z",
    "expires_at": "2026-08-02T18:00:00Z",
    "content_type": "application/supply-y.reasoning-package+json",
    "content_digest": "sha-256=:0lYf4IyJ08r4292s/NJvaKu1JXi5cjXjaT0HNpt6r04=:",
    "transport_mode": "native",
    "policy_receipt_id": "polrec_material_risk_family_level_001"
  },
  "ciphertext_download_url": "https://api.supply-y.example/v1/packages/pkg_material_constraint_001/content?token=test-only"
}
GET/v1/packages/{package_id}Read authorized Package state and retrieval metadataVerified
Operation ID
getPackage
Authentication
oauth2 + mutualTLS
Success
200 Authorized Package resource

Parameters

NameInTypeRequiredDescription
package_idpathPackageIdYes-
X-Correlation-IDheaderstringYesEnd-to-end opaque trace identifier; must not contain business plaintext

Responses

200Authorized Package resourcePackageResource
401Machine-readable problem detailsProblem
403Machine-readable problem detailsProblem
404Machine-readable problem detailsProblem
PackageResource responseaccepted Native Package
{
  "package_id": "pkg_material_constraint_001",
  "thread_id": "thread_material_constraint_01",
  "transport_mode": "native",
  "state": "accepted",
  "created_at": "2026-07-03T18:00:00Z",
  "updated_at": "2026-07-03T18:00:01Z",
  "metadata": {
    "package_id": "pkg_material_constraint_001",
    "thread_id": "thread_material_constraint_01",
    "sender_org_id": "org_tier3_material",
    "sender_agent_id": "agent_material_risk",
    "recipient_org_id": "org_tier2_connector",
    "recipient_agent_id": "agent_component_planning",
    "protocol_version": "supply-y/1.0",
    "schema_version": "1.0.0",
    "skill_id": "supply-y.material-risk",
    "skill_version": "0.1.0",
    "created_at": "2026-07-03T18:00:00Z",
    "expires_at": "2026-08-02T18:00:00Z",
    "content_type": "application/supply-y.reasoning-package+json",
    "content_digest": "sha-256=:0lYf4IyJ08r4292s/NJvaKu1JXi5cjXjaT0HNpt6r04=:",
    "transport_mode": "native",
    "policy_receipt_id": "polrec_material_risk_family_level_001"
  },
  "ciphertext_download_url": "https://api.supply-y.example/v1/packages/pkg_material_constraint_001/content?token=test-only"
}
POST/v1/packages/{package_id}/receiptsRecord a signed recipient lifecycle receiptVerified
Operation ID
createPackageReceipt
Authentication
oauth2 + mutualTLS
Success
201 Receipt accepted

Parameters

NameInTypeRequiredDescription
package_idpathPackageIdYes-
X-Correlation-IDheaderstringYesEnd-to-end opaque trace identifier; must not contain business plaintext
Idempotency-KeyheaderstringYesDeduplicates a mutation within organization and endpoint scope

Responses

201Receipt acceptedReceiptResource
400Machine-readable problem detailsProblem
401Machine-readable problem detailsProblem
403Machine-readable problem detailsProblem
409Machine-readable problem detailsProblem
ReceiptCreate requestreceived receipt
{
  "receipt_id": "receipt_material_constraint_001",
  "state": "received",
  "occurred_at": "2026-07-03T18:05:00Z",
  "actor_agent_id": "agent_component_planning",
  "package_digest": "sha-256=:25ek/LF8FWyZGJbg+9ecD3Q5czs7LIvBVU4YtWy/Sd8=:",
  "signature": {
    "key_id": "key_agent_signing_001",
    "algorithm": "ES256",
    "signature": "dGVzdC1vbmx5LXNpZ25hdHVyZQ"
  }
}
ReceiptResource responseaccepted receipt
{
  "receipt_id": "receipt_material_constraint_001",
  "state": "received",
  "occurred_at": "2026-07-03T18:05:00Z",
  "actor_agent_id": "agent_component_planning",
  "package_digest": "sha-256=:25ek/LF8FWyZGJbg+9ecD3Q5czs7LIvBVU4YtWy/Sd8=:",
  "signature": {
    "key_id": "key_agent_signing_001",
    "algorithm": "ES256",
    "signature": "dGVzdC1vbmx5LXNpZ25hdHVyZQ"
  },
  "package_id": "pkg_material_constraint_001",
  "accepted_at": "2026-07-03T18:05:01Z"
}
POST/v1/packages/{package_id}/responsesCreate a response Package in the same threadVerified

The new Package must use the same thread_id and set metadata.responds_to_package_id to the Package in the path. It is encrypted, signed and delivered as an independent Package.

Operation ID
createPackageResponse
Authentication
oauth2 + mutualTLS
Success
202 Response Package accepted for durable delivery

Parameters

NameInTypeRequiredDescription
package_idpathPackageIdYes-
X-Correlation-IDheaderstringYesEnd-to-end opaque trace identifier; must not contain business plaintext
Idempotency-KeyheaderstringYesDeduplicates a mutation within organization and endpoint scope

Responses

202Response Package accepted for durable deliveryPackageResource
400Machine-readable problem detailsProblem
401Machine-readable problem detailsProblem
403Machine-readable problem detailsProblem
404Machine-readable problem detailsProblem
409Machine-readable problem detailsProblem
PackageCreate requestNative signed exchange
{
  "signature": "YCGjpUj1jq2GpCqDHNkwIp-jkV5-vxRfYBFf2sEmOxktnNNm5SdWtWgvCFlVQBL3SGOr9TniROpcYq1pYc_aMA",
  "payload": "eyJqd2UiOnsiYWFkIjoiZXlKamIyNTBaVzUwWDJScFoyVnpkQ0k2SW5Ob1lTMHlOVFk5T2pCc1dXWTBTWGxLTURoeU5ESTVNbk12VGtwMllVdDFNVXBZYVRWamFsaHFZVlF3U0U1d2REWnlNRFE5T2lJc0ltTnZiblJsYm5SZmRIbHdaU0k2SW1Gd2NHeHBZMkYwYVc5dUwzTjFjSEJzZVMxNUxuSmxZWE52Ym1sdVp5MXdZV05yWVdkbEsycHpiMjRpTENKamNtVmhkR1ZrWDJGMElqb2lNakF5Tmkwd055MHdNMVF4T0Rvd01Eb3dNRm9pTENKbGVIQnBjbVZ6WDJGMElqb2lNakF5Tmkwd09DMHdNbFF4T0Rvd01Eb3dNRm9pTENKd1lXTnJZV2RsWDJsa0lqb2ljR3RuWDIxaGRHVnlhV0ZzWDJOdmJuTjBjbUZwYm5SZk1EQXhJaXdpY0c5c2FXTjVYM0psWTJWcGNIUmZhV1FpT2lKd2IyeHlaV05mYldGMFpYSnBZV3hmY21semExOW1ZVzFwYkhsZmJHVjJaV3hmTURBeElpd2ljSEp2ZEc5amIyeGZkbVZ5YzJsdmJpSTZJbk4xY0hCc2VTMTVMekV1TUNJc0luSmxZMmx3YVdWdWRGOWhaMlZ1ZEY5cFpDSTZJbUZuWlc1MFgyTnZiWEJ2Ym1WdWRGOXdiR0Z1Ym1sdVp5SXNJbkpsWTJsd2FXVnVkRjl2Y21kZmFXUWlPaUp2Y21kZmRHbGxjakpmWTI5dWJtVmpkRzl5SWl3aWMyTm9aVzFoWDNabGNuTnBiMjRpT2lJeExqQXVNQ0lzSW5ObGJtUmxjbDloWjJWdWRGOXBaQ0k2SW1GblpXNTBYMjFoZEdWeWFXRnNYM0pwYzJzaUxDSnpaVzVrWlhKZmIzSm5YMmxrSWpvaWIzSm5YM1JwWlhJelgyMWhkR1Z5YVdGc0lpd2ljMnRwYkd4ZmFXUWlPaUp6ZFhCd2JIa3RlUzV0WVhSbGNtbGhiQzF5YVhOcklpd2ljMnRwYkd4ZmRtVnljMmx2YmlJNklqQXVNUzR3SWl3aWRHaHlaV0ZrWDJsa0lqb2lkR2h5WldGa1gyMWhkR1Z5YVdGc1gyTnZibk4wY21GcGJuUmZNREVpTENKMGNtRnVjM0J2Y25SZmJXOWtaU0k2SW01aGRHbDJaU0o5IiwiY2lwaGVydGV4dCI6IkVxbGtOMk5FTUFSdG5MaTJNczFuN291cUxCUUFSbFZWaWVhREFsX0lFZElOYWlueXZiZVEtdnZUYmpMeUNoV3pJWm83NnNSQkZfNEhZbDc3SndvMDBPbFNkcWpqRzc0SkxkVEJJR0JCM1JidnV3U1BwRkdySDA1OU5peUdsNmdwUFQ1c1RvT2FIb2hkR2xJTGZISU9FNGRHRnM1bThxNjdTWDQ0WTFiX1JaNnhLTlplbnoteEdSWGxtbVd1OXZFa1pORG9taWswOFh1ZWlSLTlGUjV0TDdwTEdMNjdWUWQ5ZklSREQ4Q0JrTGNBYVB3R19zTGY3dFJhUTZacHgxT1ZZeFFhbDhQcW1ZeWt5ZmZMOEJPWEt0NVFFOEdtVUh6Z0hKaXNNQnlBSnNNSXFWVkp0MWtiSTlKdDJKQV85c3F0azVKaUZfTVVuU2F4LTRMci1IMm9faUZzdGZfN3l3ZjZhYUVvb2ctcHZsWDVGX1AwV3Y2V085a2xuSldram1vYzBKQ2F2TjdPMmdLTzRIYTd4ZF9LdDZOWU0tQk1FYk5EdnJ5NjFOZzR0aVlpSTVoWXVpTDc1bXByNlRBQmxZTGpBR3hIRUNwcVBFTGVzR3l0QXJyZjg2Ynp0MFNIdU9lTE1CaTVmVzc2ci1jSjNRSkNsOVhjSHFLMkNYQlRnUXYyaGFOd19QenI2X08wNktCbzhhN2pKQWZGNHB5d3FiME8tdkV3Y0pnNmNLWWNlTkNQaWJ3U0w3cjN6dWpqOUlkNzduZ0tNa3Vva3JEcnZPWWs0eGhVYVhWbk4xWGw3dHBjSFpHWGVqWnR0Z0JwdGNHbVFHZWhLS3BDeGpFbGpudHFVRnI1Sy1PZjRmZ25XbHNFVzQwQUozQTVydTVzM3RoWm5nTTY2dk1JSnlJSW9RdkxsTE9zQTM2cEd0V1A5Y2JPYVZGaGFnN0R6YjFEOVNWUDF3VC1NdThuYV9WcjJjVmp1NFhlNl9fb3Q3T09VR092NmRHaktuaWluRXlPaDdvNDlBU0tIaDIwRXRMZXE1Q1p3QWRqZlN2QUpBS2FNbVkta0VKRy1BTDQtM2FPZFREOTJtaV82VzVEVFMyOGNrdTZYcXFaaEJTNGZMTGhTemtWaUJydzJTN1d3WXRISlVJSVpCR29TaEtFR21NaWktWHJYVXMzaTdMY0FDS09HUXZUa1JXQmZBY1YyblFJdUMxTnZYS0kzYXhRY0JSQTJhZ09WcURXMDVmdUwtendRa2E2Skx0cENiUnlfelhta0Z6YzdDUEJJdUpEVEloaDZ6WTZ4andGRzRPdnFEeUlFdXhLQjZFMk9JaGJabGJ6b3EwNWJ4MGdISUl5VVVfTlBtR19WY3ZOUlBQQVJxd3RMM1ExSmZoQ2tMQlRFN2RweUxhbDlZblo5cmpxZjBPQkZ6cWZHX3lrRl9XSWdDRmhyZnRXWGZMX3BMZFZETGRiZk9XdEVYaXFXc1UydFMtR2RyWjNMSEpVTmJBUzhQVnZ5Rm1SZXVMMjNkS3Jwa1dQTzVNcUEtcVJGdVhCY0xQRnh0SjBTWnRlck1JYmtfZWR4MnQ2WXpCbVhnMmV4UzV5TVhVOEp5OVBvOU1fNUFXQ0hERmsteEFSdE5QeW40RkZkS1RKZURKeXJVSENIRDNaTUdZcHA3UmJqMGR1ZGVOWURnNThMeFhHdjBlOHU3eG9XRDdtUFZrT3R3b3U4ZGhncDZvbGJQaWxMVUVfelFqa044WEtXX2RzWE1RRXd5MGdPSHZiQWhpWkJJbG5idHVzb29hR182VXFlZkk5REJHMWRCZlZibFp3amhULXNZNS1UWUNid2k4VnMwU1BCQmY4YUxaLV9JUzd3YWl6YkxBT000NDhGQkNUbjc5T3RZVjVzY0FiZ0RFQlR3NlNjREp5akswMkNKcWxpem56TUQwNDdtNnFnLS1GSmlYUWs2ZHEzOFV4Z19rdlZ2MEhhZWM3VGx1eExfci03NEtkM3NMTThTNFZlQnZpZmRpMWN1UlNITjl5TFJwN0l4aW5yd0M5dWtKLUZicE5zcW9qZ3NCdW5YeGVYOFhzMXlMU3VHOTJUOGV1VlBoYVdKSk1mWFpJaEtUVDAwLWhBNzRhWjBrbG9zeW9NUWJMNFdhTzNtYVVnZUFZZHlTUEtRTFFfaWVEdzQ2dER5RXB4Z1NvcF8wRmwzWGF4bkN1MUNfRHE5Qk5mN0NSbmdGNWhnVnVoaHI2eGctZS0xQVRMMVhPLU1Lb2s2ekhSUjZkRnFqcVV6OXNBcG1yalQ0U0Q2SV9zQ2gzWkZkQmFWU0FiT3BIMk04LTh0TS1mRXg0M0pVTGU3anRhTTVQT0NXT1J0WDF5QVhIMzZhelV1Sm1OU0R2TnpRLVM1T1RnVlFRaVpPMzJoZG1DVmlHNkNzT3k5NVRSbmt0cklRVmI1YVI0RnNmOGFTZEJMYkJWYjZpT0ZrazR6cWhBUlRYZlRUSjdGR2hhcmt4NngzVUs1aFBvMmRQV2xQUnZIMmhKUnRWV2FXZkg0bmtPT0wyUEJxazNsMzZaeHlQelo2dXFaRVRMSlREX0N5ME5BdmV0cTJXZXpzSzh3TUpwem5CejdHdjdtQVJKZFpJZVRLei11U1FTbFc2REZUTlpUOXFfdzB2MUJxQzdzSGVMVEV3RlQ0dWV6SVNEMV95WUx5eW9PV1B1eEctcVdNV0tSN3NSMkMyOUJhZ2lILUowR2JTOGp5UFpKS2hWdmRya0hIaWFmZUE0S0t0SDZJS2EySEdILTQtNmtvQ3B0MUV4VUtiUm9uZ3d2M3ljRXI4bS0way05cDUteVFFcDdkZl9LUmpwNTNTY2t2Z1owcnltYVN0VnBWamNFMWlTNGVyaEJCOG10NFd4aHdoRDFOQ21iSjNJRkEwU1Qzbk15MjE0NzUyVHBZb2JLa2s2d2lQRW9GSVNrdUF4clpQc0dFQVpGZFBXNkZKelF4WjRkTTF3NkhBelhLUlhDaE9MSm1scDdCQ2sxTHdqYS0xN0Njb09ydDZDX1hmVG94VG1zb25SRWZxeFNsYTFfcHJwdVVsVjR3VW1aSllTNDBEbXpXXy04alJ3bXBYUE1od3BQSXUwWnE0Z3hndTk4VnNpbDdfUzFiVG1xaHZELVNsMmVmTkNHeDcxOTV6dEdCekN4aGRDQnlpZUs4ZmlPMVNscXhSZm1EYUVrR2NWRGVwSGZ6WHRVREtMVWU1TDA1X19BZHhmTkNsblQ3WGJyYkJhNk5iMnFpbDdyTHYyZklpclZ5TE1JUXdBM2N1VzkzUUdoSmVnbmlwWC1obkxwTDk4ck5GNU4ycFpXc0RFRlRLQVdzSlZGUkE0TjI0N3NYU1NWQWNzcTNXTkhZdkZQMTJseWY3ZnNRdGpVMGVJNFF0S2w2SXc0LTR6ZmhKT2VlVTJ4S2RySjVXb2U2N0ZMYXFoYmkyaF9WVlJ3UVVLWXk4MF9KY1RHMmYzZzJkYmtzd3ZUZk9HSURzLUY3NWdKdlVLaWVHLU1QbmNkUjJDWFRRVGJ1UzlSMTNrbHBDb2hZYW1BS0dsMS1kQ0tCdGdjM1M2VEM0N0lhMjZJNXNua1JrN1hrQlpIY1NtNFBkcWE1MHpMdFppOGpoWmRfTkFOcjZlcnhiSW85YXRQX3BFLUQ3aFktQmEtNGxtOHVGaU1KYWg2XzZaVmYtYjFBaUhTWG9LZE5OTTZqN3A2NC1heWRwZVpJRWgteFk2Q2xBZjdOZzN2QTdvZDhDV1BWZFdDUzBzZC1QT3FMQmhzSE5nY1k5VmJtWXJvYTJSd3d0VzNYVmxmekoxZzhRUWFvc3ZzUHRMUjRSZC1wUVktSzVGeHYxYWN3NDhvOHhRN3UxVW4zNlZPcDVlMjg0dW5mREhBcUtPQmtNVDAzdXFQUlBaWGlnbTVMZVR2WWxQQmRLdE5pWkF3NjZUZkNjSWtJZDNCU2NSNXkzRDZUWEZQT2FvRUlpMjRmbEFDUXhmYkh5VUIxcW9DOU5PelhOZkMwIiwiaXYiOiJLa1NxZml3dm05TFk5cWxfIiwicHJvdGVjdGVkIjoiZXlKbGJtTWlPaUpCTWpVMlIwTk5JaXdpZEhsd0lqb2lZWEJ3YkdsallYUnBiMjR2YzNWd2NHeDVMWGtyYW5kbElpd2lZM1I1SWpvaVlYQndiR2xqWVhScGIyNHZjM1Z3Y0d4NUxYa3VjbVZoYzI5dWFXNW5MWEJoWTJ0aFoyVXJhbk52YmlJc0luTjVkaUk2SW5OMWNIQnNlUzE1THpFdU1DSjkiLCJyZWNpcGllbnRzIjpbeyJlbmNyeXB0ZWRfa2V5IjoidWdyTEdfLVBZNnZnMEZoTnNKUGF5d0ZOYk5lOV9SSWhheWxBdlhQbDhGWG9kUVhFb0VnSE9nIiwiaGVhZGVyIjp7ImFsZyI6IkVDREgtRVMrQTI1NktXIiwiZXBrIjp7ImNydiI6IlAtMjU2Iiwia3R5IjoiRUMiLCJ4IjoiM18wa2gtajFRcko4WC1WejJSM3RXTWNBR1JrRjZDa05HN29pVHFHVXJ6QSIsInkiOiI0d2I0QlBQNmZRdlo5LTVIa0RiMnRDa2xXdlY5LUJCYXRPeTNMN3MzLUE4In0sImtpZCI6ImtleV9zZW5kZXJfZW5jcnlwdGlvbl8wMDEifX0seyJlbmNyeXB0ZWRfa2V5IjoiZnJCYS1GYVdVZVZyRlNKUEN0b3c5S3ZuWlhHQXFDR09DMk9IUnhWVTZTSWpHX2xOS3Qzekl3IiwiaGVhZGVyIjp7ImFsZyI6IkVDREgtRVMrQTI1NktXIiwiZXBrIjp7ImNydiI6IlAtMjU2Iiwia3R5IjoiRUMiLCJ4IjoidERQUTRVUGRHYnNBOFBpR2pVMnVTdmhqQ3JZbkRUWFFVbzFWamJwV0o0WSIsInkiOiJGX2VQdmREVFZMZTFiQ2tEUm5qSTNsTmFSZEY5OGV6d3FGTm03R1pJc293In0sImtpZCI6ImtleV9yZWNpcGllbnRfZW5jcnlwdGlvbl8wMDEifX1dLCJ0YWciOiJ4TTd2VHRKTnlMcDE3YU5ueFQzUjlRIn0sIm1ldGFkYXRhIjp7ImNvbnRlbnRfZGlnZXN0Ijoic2hhLTI1Nj06MGxZZjRJeUowOHI0Mjkycy9OSnZhS3UxSlhpNWNqWGphVDBITnB0NnIwND06IiwiY29udGVudF90eXBlIjoiYXBwbGljYXRpb24vc3VwcGx5LXkucmVhc29uaW5nLXBhY2thZ2UranNvbiIsImNyZWF0ZWRfYXQiOiIyMDI2LTA3LTAzVDE4OjAwOjAwWiIsImV4cGlyZXNfYXQiOiIyMDI2LTA4LTAyVDE4OjAwOjAwWiIsInBhY2thZ2VfaWQiOiJwa2dfbWF0ZXJpYWxfY29uc3RyYWludF8wMDEiLCJwb2xpY3lfcmVjZWlwdF9pZCI6InBvbHJlY19tYXRlcmlhbF9yaXNrX2ZhbWlseV9sZXZlbF8wMDEiLCJwcm90b2NvbF92ZXJzaW9uIjoic3VwcGx5LXkvMS4wIiwicmVjaXBpZW50X2FnZW50X2lkIjoiYWdlbnRfY29tcG9uZW50X3BsYW5uaW5nIiwicmVjaXBpZW50X29yZ19pZCI6Im9yZ190aWVyMl9jb25uZWN0b3IiLCJzY2hlbWFfdmVyc2lvbiI6IjEuMC4wIiwic2VuZGVyX2FnZW50X2lkIjoiYWdlbnRfbWF0ZXJpYWxfcmlzayIsInNlbmRlcl9vcmdfaWQiOiJvcmdfdGllcjNfbWF0ZXJpYWwiLCJza2lsbF9pZCI6InN1cHBseS15Lm1hdGVyaWFsLXJpc2siLCJza2lsbF92ZXJzaW9uIjoiMC4xLjAiLCJ0aHJlYWRfaWQiOiJ0aHJlYWRfbWF0ZXJpYWxfY29uc3RyYWludF8wMSIsInRyYW5zcG9ydF9tb2RlIjoibmF0aXZlIn19",
  "protected": "eyJhbGciOiJFUzI1NiIsImtpZCI6ImtleV9zZW5kZXJfc2lnbmluZ18wMDEiLCJ0eXAiOiJhcHBsaWNhdGlvbi9zdXBwbHkteStqd3MiLCJjdHkiOiJhcHBsaWNhdGlvbi9zdXBwbHkteS5leGNoYW5nZS1lbnZlbG9wZStqc29uIiwic3l2Ijoic3VwcGx5LXkvMS4wIn0"
}
PackageCreate requestCatena-X transfer manifest
{
  "transport_mode": "catena_x",
  "metadata": {
    "package_id": "pkg_material_constraint_001",
    "thread_id": "thread_material_constraint_01",
    "sender_org_id": "org_tier3_material",
    "sender_agent_id": "agent_material_risk",
    "recipient_org_id": "org_tier2_connector",
    "recipient_agent_id": "agent_component_planning",
    "protocol_version": "supply-y/1.0",
    "schema_version": "1.0.0",
    "skill_id": "supply-y.material-risk",
    "skill_version": "0.1.0",
    "created_at": "2026-07-03T18:00:00Z",
    "expires_at": "2026-08-02T18:00:00Z",
    "content_type": "application/supply-y.reasoning-package+json",
    "content_digest": "sha-256=:0lYf4IyJ08r4292s/NJvaKu1JXi5cjXjaT0HNpt6r04=:",
    "transport_mode": "catena_x",
    "policy_receipt_id": "polrec_material_risk_family_level_001"
  },
  "edc": {
    "connector_id": "edc_tier3_001",
    "asset_id": "asset_pkg_material_constraint_001",
    "asset_digest": "sha-256=:AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA=:",
    "contract_agreement_id": "contract_agreement_001",
    "transfer_process_id": "transfer_process_001"
  },
  "sender_signature": {
    "key_id": "key_agent_signing_001",
    "algorithm": "ES256",
    "signature": "dGVzdC1vbmx5LXNpZ25hdHVyZQ"
  }
}
PackageResource responseaccepted Native Package
{
  "package_id": "pkg_material_constraint_001",
  "thread_id": "thread_material_constraint_01",
  "transport_mode": "native",
  "state": "accepted",
  "created_at": "2026-07-03T18:00:00Z",
  "updated_at": "2026-07-03T18:00:01Z",
  "metadata": {
    "package_id": "pkg_material_constraint_001",
    "thread_id": "thread_material_constraint_01",
    "sender_org_id": "org_tier3_material",
    "sender_agent_id": "agent_material_risk",
    "recipient_org_id": "org_tier2_connector",
    "recipient_agent_id": "agent_component_planning",
    "protocol_version": "supply-y/1.0",
    "schema_version": "1.0.0",
    "skill_id": "supply-y.material-risk",
    "skill_version": "0.1.0",
    "created_at": "2026-07-03T18:00:00Z",
    "expires_at": "2026-08-02T18:00:00Z",
    "content_type": "application/supply-y.reasoning-package+json",
    "content_digest": "sha-256=:0lYf4IyJ08r4292s/NJvaKu1JXi5cjXjaT0HNpt6r04=:",
    "transport_mode": "native",
    "policy_receipt_id": "polrec_material_risk_family_level_001"
  },
  "ciphertext_download_url": "https://api.supply-y.example/v1/packages/pkg_material_constraint_001/content?token=test-only"
}
POST/v1/packages/{package_id}/revokeRequest Package access revocationVerified

Stops future retrieval where possible and records an immutable revocation event. It cannot erase plaintext already decrypted by an authorized recipient.

Operation ID
revokePackage
Authentication
oauth2 + mutualTLS
Success
200 Revocation decision and its practical effect

Parameters

NameInTypeRequiredDescription
package_idpathPackageIdYes-
X-Correlation-IDheaderstringYesEnd-to-end opaque trace identifier; must not contain business plaintext
Idempotency-KeyheaderstringYesDeduplicates a mutation within organization and endpoint scope

Responses

200Revocation decision and its practical effectPackageRevocationResource
400Machine-readable problem detailsProblem
401Machine-readable problem detailsProblem
403Machine-readable problem detailsProblem
404Machine-readable problem detailsProblem
409Machine-readable problem detailsProblem
PackageRevocationRequest requestsender revocation request
{
  "requested_at": "2026-07-04T00:10:00Z",
  "reason_code": "wrong_recipient",
  "reason_detail": "Recipient routing was selected incorrectly.",
  "signature": {
    "key_id": "key_agent_signing_001",
    "algorithm": "ES256",
    "signature": "dGVzdC1vbmx5LXNpZ25hdHVyZQ"
  }
}
PackageRevocationResource responsefuture access blocked
{
  "package_id": "pkg_material_constraint_001",
  "state": "revoked",
  "revoked_at": "2026-07-04T00:10:01Z",
  "outcome": "access_blocked",
  "future_access_blocked": true,
  "audit_event_id": "event_package_revoked_001"
}

Threads

Ordered collaboration state

1 operations
GET/v1/threads/{thread_id}Read the ordered Package graph and collaboration stateVerified
Operation ID
getThread
Authentication
oauth2 + mutualTLS
Success
200 Authorized thread metadata

Parameters

NameInTypeRequiredDescription
thread_idpathThreadIdYes-
X-Correlation-IDheaderstringYesEnd-to-end opaque trace identifier; must not contain business plaintext

Responses

200Authorized thread metadataThreadResource
401Machine-readable problem detailsProblem
403Machine-readable problem detailsProblem
404Machine-readable problem detailsProblem
ThreadResource responsematerial constraint thread
{
  "thread_id": "thread_material_constraint_01",
  "protocol_version": "supply-y/1.0",
  "transport_mode": "native",
  "participants": [
    "org_tier3_material",
    "org_tier2_connector"
  ],
  "packages": [
    {
      "package_id": "pkg_material_constraint_001",
      "thread_id": "thread_material_constraint_01",
      "transport_mode": "native",
      "state": "accepted",
      "created_at": "2026-07-03T18:00:00Z",
      "updated_at": "2026-07-03T18:00:01Z",
      "metadata": {
        "package_id": "pkg_material_constraint_001",
        "thread_id": "thread_material_constraint_01",
        "sender_org_id": "org_tier3_material",
        "sender_agent_id": "agent_material_risk",
        "recipient_org_id": "org_tier2_connector",
        "recipient_agent_id": "agent_component_planning",
        "protocol_version": "supply-y/1.0",
        "schema_version": "1.0.0",
        "skill_id": "supply-y.material-risk",
        "skill_version": "0.1.0",
        "created_at": "2026-07-03T18:00:00Z",
        "expires_at": "2026-08-02T18:00:00Z",
        "content_type": "application/supply-y.reasoning-package+json",
        "content_digest": "sha-256=:0lYf4IyJ08r4292s/NJvaKu1JXi5cjXjaT0HNpt6r04=:",
        "transport_mode": "native",
        "policy_receipt_id": "polrec_material_risk_family_level_001"
      },
      "ciphertext_download_url": "https://api.supply-y.example/v1/packages/pkg_material_constraint_001/content?token=test-only"
    }
  ],
  "state": "active"
}

Notifications

Signed lifecycle delivery

3 operations
POST/v1/webhook-endpointsRegister a signed webhook endpointVerified
Operation ID
createWebhookEndpoint
Authentication
oauth2 + mutualTLS
Success
201 Webhook endpoint registered

Parameters

NameInTypeRequiredDescription
X-Correlation-IDheaderstringYesEnd-to-end opaque trace identifier; must not contain business plaintext
Idempotency-KeyheaderstringYesDeduplicates a mutation within organization and endpoint scope

Responses

201Webhook endpoint registeredWebhookEndpointResource
400Machine-readable problem detailsProblem
401Machine-readable problem detailsProblem
409Machine-readable problem detailsProblem
WebhookEndpointCreate requestprimary Agent webhook
{
  "url": "https://agent.tier2.example/webhooks/supply-y",
  "event_types": [
    "package.accepted",
    "package.delivered",
    "package.received"
  ]
}
WebhookEndpointResource responseactive Agent webhook
{
  "url": "https://agent.tier2.example/webhooks/supply-y",
  "event_types": [
    "package.accepted",
    "package.delivered",
    "package.received"
  ],
  "webhook_endpoint_id": "wh_tier2_primary_001",
  "status": "active",
  "signing_key_id": "key_agent_signing_001"
}
GET/v1/notificationsRead the ordered notification streamVerified

Returns organization-scoped lifecycle notifications in ascending sequence order. This endpoint is the recovery path when webhook delivery is delayed, missed or observed out of order.

Operation ID
listNotifications
Authentication
oauth2 + mutualTLS
Success
200 Ordered page of retained lifecycle notifications

Parameters

NameInTypeRequiredDescription
X-Correlation-IDheaderstringYesEnd-to-end opaque trace identifier; must not contain business plaintext
afterquerystringNoOpaque cursor returned by the previous page; omit to start at the earliest retained notification
limitqueryintegerNo-

Responses

200Ordered page of retained lifecycle notificationsNotificationPage
400Machine-readable problem detailsProblem
401Machine-readable problem detailsProblem
403Machine-readable problem detailsProblem
NotificationPage responseone retained event
{
  "items": [
    {
      "notification_id": "notification_material_constraint_001",
      "event_id": "event_material_constraint_accepted_001",
      "event_type": "package.accepted",
      "protocol_version": "supply-y/1.0",
      "sequence": 41,
      "occurred_at": "2026-07-04T00:00:00Z",
      "organization_id": "org_tier2_connector",
      "package_id": "pkg_material_constraint_001",
      "thread_id": "thread_material_constraint_01",
      "state": "accepted",
      "transport_mode": "native",
      "content_digest": "sha-256=:25ek/LF8FWyZGJbg+9ecD3Q5czs7LIvBVU4YtWy/Sd8=:",
      "correlation_id": "corr_material_constraint_001"
    }
  ],
  "next_cursor": "cursor_notification_041",
  "has_more": false
}
POST/v1/notifications/{notification_id}/ackAcknowledge durable local storage of a notificationVerified

Acknowledgement means the Agent has durably stored the event in its local inbox. It does not mean that the business Package was opened or acted on.

Operation ID
acknowledgeNotification
Authentication
oauth2 + mutualTLS
Success
200 Acknowledgement recorded or original acknowledgement returned for an exact retry

Parameters

NameInTypeRequiredDescription
notification_idpathstringYes-
X-Correlation-IDheaderstringYesEnd-to-end opaque trace identifier; must not contain business plaintext
Idempotency-KeyheaderstringYesDeduplicates a mutation within organization and endpoint scope

Responses

200Acknowledgement recorded or original acknowledgement returned for an exact retryNotificationAcknowledgement
400Machine-readable problem detailsProblem
401Machine-readable problem detailsProblem
403Machine-readable problem detailsProblem
404Machine-readable problem detailsProblem
409Machine-readable problem detailsProblem
NotificationAcknowledge requestdurable inbox acknowledgement
{
  "event_id": "event_material_constraint_accepted_001",
  "disposition": "stored",
  "stored_at": "2026-07-04T00:02:30Z",
  "last_contiguous_sequence": 41
}
NotificationAcknowledgement responserecorded acknowledgement
{
  "notification_id": "notification_material_constraint_001",
  "event_id": "event_material_constraint_accepted_001",
  "disposition": "stored",
  "acknowledged_at": "2026-07-04T00:02:31Z",
  "last_contiguous_sequence": 41
}

Audit

Authorized integrity and delivery evidence

2 operations
GET/v1/audit/threads/{thread_id}Read authorized thread integrity evidenceVerified
Operation ID
getThreadAuditEvidence
Authentication
oauth2 + mutualTLS
Success
200 Ordered metadata-only thread audit evidence

Parameters

NameInTypeRequiredDescription
thread_idpathThreadIdYes-
X-Correlation-IDheaderstringYesEnd-to-end opaque trace identifier; must not contain business plaintext

Responses

200Ordered metadata-only thread audit evidenceAuditThreadEvidence
401Machine-readable problem detailsProblem
403Machine-readable problem detailsProblem
404Machine-readable problem detailsProblem
AuditThreadEvidence responsethread hash-chain evidence
{
  "thread_id": "thread_material_constraint_01",
  "events": [
    {
      "notification_id": "notification_material_constraint_001",
      "event_id": "event_material_constraint_accepted_001",
      "event_type": "package.accepted",
      "protocol_version": "supply-y/1.0",
      "sequence": 41,
      "occurred_at": "2026-07-04T00:00:00Z",
      "organization_id": "org_tier2_connector",
      "package_id": "pkg_material_constraint_001",
      "thread_id": "thread_material_constraint_01",
      "state": "accepted",
      "transport_mode": "native",
      "content_digest": "sha-256=:25ek/LF8FWyZGJbg+9ecD3Q5czs7LIvBVU4YtWy/Sd8=:",
      "correlation_id": "corr_material_constraint_001"
    }
  ],
  "chain_head": "sha-256=:AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA=:",
  "integrity_verified_at": "2026-07-04T00:03:00Z"
}
GET/v1/audit/packages/{package_id}Read authorized integrity and delivery evidenceVerified
Operation ID
getPackageAuditEvidence
Authentication
oauth2 + mutualTLS
Success
200 Audit evidence without Package plaintext

Parameters

NameInTypeRequiredDescription
package_idpathPackageIdYes-
X-Correlation-IDheaderstringYesEnd-to-end opaque trace identifier; must not contain business plaintext

Responses

200Audit evidence without Package plaintextAuditEvidence
401Machine-readable problem detailsProblem
403Machine-readable problem detailsProblem
404Machine-readable problem detailsProblem
AuditEvidence responsePackage integrity evidence
{
  "package_id": "pkg_material_constraint_001",
  "content_digest": "sha-256=:25ek/LF8FWyZGJbg+9ecD3Q5czs7LIvBVU4YtWy/Sd8=:",
  "sender_signature": {
    "key_id": "key_agent_signing_001",
    "algorithm": "ES256",
    "signature": "dGVzdC1vbmx5LXNpZ25hdHVyZQ"
  },
  "events": [
    {
      "notification_id": "notification_material_constraint_001",
      "event_id": "event_material_constraint_accepted_001",
      "event_type": "package.accepted",
      "protocol_version": "supply-y/1.0",
      "sequence": 41,
      "occurred_at": "2026-07-04T00:00:00Z",
      "organization_id": "org_tier2_connector",
      "package_id": "pkg_material_constraint_001",
      "thread_id": "thread_material_constraint_01",
      "state": "accepted",
      "transport_mode": "native",
      "content_digest": "sha-256=:25ek/LF8FWyZGJbg+9ecD3Q5czs7LIvBVU4YtWy/Sd8=:",
      "correlation_id": "corr_material_constraint_001"
    }
  ],
  "integrity_verified_at": "2026-07-04T00:03:00Z"
}