# info.summary
Agent-facing control plane for encrypted cross-company Package exchange

# info.description
Supply-Y Protocol 1.0 reference contract for organization-controlled Agents. Business payloads are encrypted before submission in Native Mode and move through EDC without duplication in Catena-X Mode. A stable contract is not evidence of a generally available hosted service.

# info.license.name
Copyright SupplyWhy. All rights reserved.

# servers[].description
Illustrative endpoint; production hostname is not yet public

# tags[].description
Agent registration and capability discovery

# tags[].description
Verified recipient keys and capabilities

# tags[].description
Signed sender claims about local disclosure and approval checks

# tags[].description
Authorized integrity and delivery evidence

# paths./v1/agents/register.post.summary
Register an Agent and its public capabilities

# paths./v1/agents/{agent_id}.get.summary
Read verified Agent status and compatibility

# paths./v1/agents/{agent_id}/keys.post.summary
Register a replacement signing or encryption public key

# paths./v1/agents/{agent_id}/keys/{key_id}/revoke.post.summary
Revoke a signing or encryption key and record its trust cutoff

# paths./v1/agents/{agent_id}/keys/{key_id}/revoke.post.responses.200.description
Key revoked and immutable lifecycle event recorded

# paths./v1/directory/agents/{agent_id}/keys.get.summary
Read current verified signing and encryption keys

# paths./v1/skills.get.description
Returns release manifests compatible with the requested protocol version. Skill artifacts are signed and content-addressed.

# paths./v1/directory/notification-keys.get.summary
Read Supply-Y webhook-signing public keys

# paths./v1/directory/notification-keys.get.description
Returns current and retiring platform keys that an Agent can pin before activating a webhook endpoint. Private keys are never exposed.

# paths./v1/policy-receipts.post.summary
Record a signed local-policy evaluation before Package submission

# paths./v1/policy-receipts.post.description
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.

# paths./v1/policy-receipts.post.responses.201.description
Policy receipt signature and claim structure accepted

# paths./v1/policy-receipts/{policy_receipt_id}.get.summary
Read an authorized signed policy receipt and its platform decision

# paths./v1/packages.post.summary
Create one Native or Catena-X Package transfer

# paths./v1/packages.post.description
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.

# paths./v1/packages/{package_id}.get.summary
Read authorized Package state and retrieval metadata

# paths./v1/packages/{package_id}/receipts.post.summary
Record a signed recipient lifecycle receipt

# paths./v1/packages/{package_id}/responses.post.summary
Create a response Package in the same thread

# paths./v1/packages/{package_id}/responses.post.description
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.

# paths./v1/packages/{package_id}/responses.post.responses.202.description
Response Package accepted for durable delivery

# paths./v1/packages/{package_id}/revoke.post.description
Stops future retrieval where possible and records an immutable revocation event. It cannot erase plaintext already decrypted by an authorized recipient.

# paths./v1/packages/{package_id}/revoke.post.responses.200.description
Revocation decision and its practical effect

# paths./v1/threads/{thread_id}.get.summary
Read the ordered Package graph and collaboration state

# paths./v1/notifications.get.description
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.

# paths./v1/notifications.get.parameters[].description
Opaque cursor returned by the previous page; omit to start at the earliest retained notification

# paths./v1/notifications.get.responses.200.description
Ordered page of retained lifecycle notifications

# paths./v1/notifications/{notification_id}/ack.post.summary
Acknowledge durable local storage of a notification

# paths./v1/notifications/{notification_id}/ack.post.description
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.

# paths./v1/notifications/{notification_id}/ack.post.responses.200.description
Acknowledgement recorded or original acknowledgement returned for an exact retry

# paths./v1/audit/threads/{thread_id}.get.summary
Read authorized thread integrity evidence

# paths./v1/audit/threads/{thread_id}.get.responses.200.description
Ordered metadata-only thread audit evidence

# paths./v1/audit/packages/{package_id}.get.summary
Read authorized integrity and delivery evidence

# paths./v1/audit/packages/{package_id}.get.responses.200.description
Audit evidence without Package plaintext

# webhooks.packageLifecycle.post.description
The receiver verifies the RFC 9421 HTTP Message Signature, RFC 9530 Content-Digest, signature time window, event ID and delivery ID before durably storing the metadata-only event. A 204 response means durable inbox storage, not business processing.

# webhooks.packageLifecycle.post.parameters[].description
RFC 9530 SHA-256 digest of the exact request content bytes

# webhooks.packageLifecycle.post.responses.204.description
Event durably stored, or already stored under the same event ID

# webhooks.packageLifecycle.post.responses.400.description
Malformed request or Content-Digest mismatch; automatic retry is not useful

# webhooks.packageLifecycle.post.responses.401.description
Signature, signing key or signature time window rejected; automatic retry is not useful

# webhooks.packageLifecycle.post.responses.429.description
Temporary receiver backpressure; retry and honor Retry-After

# webhooks.packageLifecycle.post.responses.500.description
Temporary receiver failure; retry according to the delivery schedule

# webhooks.packageLifecycle.post.responses.503.description
Temporary receiver unavailability; retry and honor Retry-After when present

# components.securitySchemes.oauth2.description
Short-lived, audience-restricted Agent token following OAuth 2.0 Security BCP

# components.securitySchemes.oauth2.flows.clientCredentials.scopes.packages:read
Read authorized Package metadata and ciphertext references

# components.securitySchemes.oauth2.flows.clientCredentials.scopes.policy:write
Submit signed local-policy evaluation claims

# components.parameters.CorrelationId.description
End-to-end opaque trace identifier; must not contain business plaintext

# components.parameters.IdempotencyKey.description
Deduplicates a mutation within organization and endpoint scope

# components.schemas.PublicKey.properties.invalid_from.description
Earliest Package creation time that must no longer be trusted

# components.schemas.KeyRevocationRequest.properties.invalid_from.description
Earliest Package creation time affected by the revocation

# components.schemas.SkillUpdatePolicy.properties.supersedes.description
Exact predecessor for a direct update, or null for an initial release

# components.schemas.SkillUpdatePolicy.properties.activation_policy.description
A verified download never activates a Skill without customer approval

# components.schemas.PolicyReceiptCreate.properties.signature.description
Sender ES256 signature over the RFC 8785 canonical receipt without signature

# components.schemas.NativePackageCreate.description
Flattened JWS JSON. The decoded, verified payload is the RFC 8785 canonical exchange envelope containing readable metadata and a two-recipient General JWE JSON object.

# components.schemas.NativePackageCreate.properties.protected.description
Base64url JWS protected header; alg MUST be ES256

# components.schemas.CatenaXPackageCreate.properties.edc.properties.asset_digest.description
RFC 9530 digest of the exact encrypted and signed EDC asset bytes

# components.schemas.CatenaXPackageCreate.properties.sender_signature.description
ES256 signature over the RFC 8785 canonical request without sender_signature

# components.schemas.PackageResource.properties.ciphertext_download_url.description
Short-lived and recipient-scoped; Native Mode only

# components.schemas.PackageRevocationRequest.properties.signature.description
Sender signature over the RFC 8785 canonical revocation request without signature

# components.schemas.WebhookEndpointResource.properties.signing_key_id.description
Supply-Y notification-signing key selected from the versioned directory

# components.schemas.LifecycleNotification.properties.sequence.description
Monotonically increasing position in the receiving organization's notification stream