Client Libraries
Sparrow’s interface is REST/OpenAPI only. There is no bespoke SDK to learn — every endpoint
is described by the committed OpenAPI 3.1 contract at api/openapi.yaml, so you can generate a
typed client for any language with a standard generator, or just call the API with plain HTTP.
The full, browsable API reference is generated from that same spec — see API Reference.
Authentication
Section titled “Authentication”All requests use an API key in the X-API-Key header (required only when the server is started
with SPARROW_API_KEY set):
curl -X POST "http://localhost:8080/v1/consumers/payments/events?event=invoice.paid" \ -H "Content-Type: application/json" \ -H "X-API-Key: sk_live_..." \ -d '{ "payload": {"id": "inv_01", "amount": 4999}, "idempotency_key": "idem_abc123" }'Generating a client
Section titled “Generating a client”Sparrow publishes no SDK packages. Generate the client in your own project, from the spec of the Sparrow version you run, with a standard generator. That keeps the client exactly in step with your server, in your language, with no SDK release to wait for.
Get the spec that matches your server. Any of these is the same file:
- From the running server:
GET /openapi.yaml(or/openapi.json). It needs no API key. - From the GitHub release you deploy:
openapi.yamlandopenapi.jsonare attached to every release. - From the repository at that release’s tag:
api/openapi.yaml.
curl -fsS https://sparrow.internal/openapi.yaml -o sparrow-openapi.yamlRegenerate when you upgrade Sparrow. Within /v1, changes are additive
(see Compatibility), so a client
generated from an older spec keeps working against a newer server; it just
does not know the new fields and endpoints yet. Commit the spec file you
generated from, or the generated code, in your project, whichever your
build prefers.
Generated with openapi-python-client
(typed, httpx/attrs-based):
uvx openapi-python-client generate \ --path sparrow-openapi.yaml \ --output-path sparrow_client --overwritefrom sparrow_client import AuthenticatedClientfrom sparrow_client.api.webhooks import register_webhookfrom sparrow_client.models.register_webhook_body import RegisterWebhookBody
client = AuthenticatedClient( base_url="http://localhost:8080", token="<api-key>", prefix="", auth_header_name="X-API-Key",)resp = register_webhook.sync_detailed( consumer="default", client=client, body=RegisterWebhookBody(events=["order.created"], url="https://example.com/hook"),)npx openapi-typescript sparrow-openapi.yaml -o src/sparrow/schema.d.tsUse with any typed fetch wrapper (for example openapi-fetch).
go run github.com/oapi-codegen/oapi-codegen/v2/cmd/oapi-codegen@latest \ -generate types,client -package sparrow \ sparrow-openapi.yaml > sparrow/sparrow.gen.goTreat generated code as build output: don’t edit it by hand, regenerate it.
Sparrow’s own end-to-end suite works the same way. Its Python client is
generated from api/openapi.yaml (make client-python) and checked in at
e2e/client/, only because the e2e tests import it. It is test code, not a
supported SDK: don’t depend on it, generate your own.
Hand-written code
Section titled “Hand-written code”Two things are hand-written, because they run on the receiving side and are small enough to vendor:
pkg/signature, the Go library that verifies delivery signatures.client/verify/, sample verifiers in eight other languages. See Verifying signatures.