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

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

The OpenAPI spec is committed at api/openapi.yaml (also api/openapi.json) and regenerated from the Go REST definitions in internal/rest (via Huma):

make generate

Point any OpenAPI 3.1-compatible generator at that file:

Any language works

Sparrow ships no hand-written SDK — the API is pure OpenAPI 3.1, so a client is generated, never maintained by us. The tabs below (Python, TypeScript, Go) are just examples; point any OpenAPI generator at api/openapi.yaml to get a typed client for Java, C#, Rust, Ruby, PHP, Kotlin, Swift, and dozens more — or skip generation entirely and call the endpoints with plain HTTP.

Python

Generated with openapi-python-client (typed, httpx/attrs-based) into client/python:

uvx openapi-python-client generate \
  --path api/openapi.yaml \
  --output-path client/python --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"),
)

TypeScript

npx openapi-typescript api/openapi.yaml -o client/ts/schema.d.ts

Use with any typed fetch wrapper (for example openapi-fetch).

Go

go run github.com/oapi-codegen/oapi-codegen/v2/cmd/oapi-codegen@latest \
  -generate types,client -package sparrow \
  api/openapi.yaml > client/go/sparrow.gen.go

All generated client code is derived from api/openapi.yaml; do not edit it by hand — regenerate instead.