Pigeon Protocol v1

Design invariant

A governed operation requires an authenticated principal and a valid runtime communication contract. Clients do not assert their own authority. The broker resolves identity, negotiates a contract and validates subsequent operations under that contract ID.

Required headers

Header	Purpose
`authorization: Bearer <credential>`	Authenticate the calling principal.
`x-pigeon-contract: <contract_id>`	Bind a governed operation to a negotiated contract.
`x-pigeon-region: <region>`	Supply the runtime region used by current policy gates.
`content-type: application/json`	JSON request bodies.

Endpoints

Endpoint	Purpose
`GET /`	Broker metadata and protocol information.
`GET /health`	Broker health.
`GET /v1/subjects`	Discover registered subjects and selected public constraints.
`POST /v1/contracts`	Authenticate and negotiate permitted subjects and operations.
`POST /v1/messages`	Publish a governed message under x-pigeon-contract.
`POST /v1/subjects/{subject}/receive`	Receive messages when the contract contains receive authority.
`GET /v1/audit`	Read current audit records.
`GET /v1/quarantine`	Inspect quarantined communication.
`POST /v1/quarantine/{id}/release`	Release a quarantined record when the caller and contract permit it.

Negotiate a contract

POST /v1/contracts
Authorization: Bearer <credential>
Content-Type: application/json

{
  "subjects": ["payments.authorize"],
  "ttlMs": 900000
}

The broker returns only the requested subjects and operations permitted for the authenticated principal. A principal with no permitted requested subjects receives a typed denial and no contract is issued.

Publish

POST /v1/messages
Authorization: Bearer <credential>
x-pigeon-contract: contract_1
Content-Type: application/json

{
  "subject": "payments.authorize",
  "type": "payment.authorization.requested",
  "source": "checkout-service",
  "intent": "authorize_payment",
  "idempotencyKey": "order_42:authorize",
  "classification": "pci",
  "region": "uk",
  "data": {
    "merchantId": "m",
    "orderId": "order_42",
    "amount": 42.5,
    "currency": "GBP",
    "paymentToken": "tok"
  }
}

A new accepted message returns HTTP 202. A recognised duplicate may return HTTP 200 with status: "duplicate". Contract or policy failures can deny or quarantine an otherwise well-formed message.

Typed errors

{
  "error": {
    "code": "CONTRACT_REQUIRED",
    "message": "...",
    "details": {}
  }
}

Representative codes include UNAUTHENTICATED, CONTRACT_EXPIRED, SUBJECT_NOT_IN_CONTRACT, INTENT_DENIED, REGION_DENIED, SENSITIVE_FIELD_DENIED, IDEMPOTENCY_REQUIRED, SCHEMA_INVALID and RATE_LIMITED.

Versioning

SDK compatibility is defined against Pigeon Protocol v1, not identical package patch versions. A breaking wire or semantic change requires a new protocol version.

Canonical protocol specification ↗Quickstart →