Sunny API v1
The versioned Sunny API. /v1 changes are additive only: new endpoints,
new optional request fields, new response fields, new enum values, including
a new error type or code. A removal is announced with Deprecation and
Sunset headers at least six months ahead. Operations marked beta
(x-sunny-stability: beta) may still
change shape; everything else is held to the additive rule by CI.
TypeScript SDK
@sunnysdk/client wraps every operation here in a typed method
(sunny.quotes.get(id)), with retries, idempotency keys, pagination and
webhook verification. Install it with npm install @sunnysdk/client@beta;
each operation's @sunnysdk/client example shows its call, and the
SDK guide covers the rest.
Client contract
Ignore response fields you don't recognise, and handle enum values you
don't recognise (error types and codes included). That is what lets
new fields and values ship without a new version.
Authentication
Send an API key as x-api-key (sunny_wsk_… workspace or sunny_sk_…
personal), or an OAuth 2.1 Bearer token. Cookie sessions and the
first-party shared secret are not accepted on /v1. /v1 is
server-to-server: browsers get no CORS allowance.
Conventions
- Ids are opaque strings; don't parse them.
- Fields are snake_case. Timestamps are ISO 8601 in UTC.
- A field with no value is omitted, never
null. -
Lists are
{ data, next_cursor? }. Passnext_cursorback ascursor; it is omitted on the last page.limitis 1-100, default 25. - Every response carries
X-Request-Id. Quote it when reporting a problem.
Errors
Every error is { error: { type, code, message, param?, request_id } }.
The documented type values (invalid_request_error,
authentication_error, permission_error, idempotency_error,
rate_limit_error, api_error) are the current set. New types may be
added; clients must handle a type they don't recognise. code is
specific and grows the same way. Neither is renamed or repurposed.
param names the request field at fault when there is one.
Retries and limits
POST and PATCH accept an Idempotency-Key header (1-255 printable ASCII
characters); a retry with the same key and request replays the stored
response with Idempotent-Replayed: true.
Requests are limited per owner (per workspace for workspace keys, per user
otherwise): 600 reads and 120 writes per
60 seconds, shared with the unversioned API. A rejection is
429 with Retry-After.