Product Contract
The sole semantic contract is Protobuf Editions 2023 at api/proto/sylphx/events/v1/events.proto. Connect, gRPC, gRPC-Web, and generated clients are projections of that descriptor. The REST/SSE document is lineage-bound. It does not authorize a second wire model.
API: https://api.events.sylphx.com/v1. Discover api_base from the Binding. Events does not mint Binding.
Callers present a Platform-signed Project Binding in x-sylphx-project-binding and an Identity-signed short-lived delegation as Authorization: Bearer. Do not send a tenant or project header. Do not send an Events API key. There is no Events API key.
| Job | REST projection | Meaning |
|---|---|---|
| Admit an event | POST /v1/events | Immutable CloudEvents-compatible fact. Idempotent. |
| Read events | GET /v1/events, GET /v1/events/{id} | Project-scoped. Cursor created_at,id. |
| Connectors | POST/GET /v1/connectors, rotate, disable | Write-only secrets. Never returned. |
| Submit delivery | POST /v1/deliveries | Channel intent or opaque envelope events.delivery-intent.v1. |
| Observe | GET /v1/deliveries/{id}/attempts and /receipts | Immutable. Receipt is not human-read proof. |
| Realtime resume | SSE stream with durable cursor | Malformed, foreign, or expired cursors fail closed. |
| Privileged wake | ClaimDueDeliveries | Requires events.dispatch. Replay returns original fences. |
Expected failures use a typed envelope with stable code, message, occurrence id, and retryability. There are no success-shaped fallbacks. Reusing an idempotency key with a different digest fails 409 idempotency_conflict.
Buf module buf.build/sylphx/events and generated Connect stubs are contract projections. The customer SDK and CLI are generated from this contract under their own identities. Do not treat Platform sylphx-sdk or sylphx-cli as the Events client. Do not treat events-import as the customer CLI.
Authority files in the source repository: api/proto/sylphx/events/v1/events.proto and api/events.v1.openapi.yaml.