Skip to content

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.

All requests use an API key in the X-API-Key header (required only when the server is started with SPARROW_API_KEY set):

Terminal window
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"
}'

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.yaml and openapi.json are attached to every release.
  • From the repository at that release’s tag: api/openapi.yaml.
Terminal window
curl -fsS https://sparrow.internal/openapi.yaml -o sparrow-openapi.yaml

Regenerate 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):

Terminal window
uvx openapi-python-client generate \
--path sparrow-openapi.yaml \
--output-path sparrow_client --overwrite
from sparrow_client import AuthenticatedClient
from sparrow_client.api.webhooks import register_webhook
from 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"),
)

Treat 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.

Two things are hand-written, because they run on the receiving side and are small enough to vendor: