Skip to content

API reference

1.0.0-beta.14
OpenAPI 3.1.0

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? }. Pass next_cursor back as cursor; it is omitted on the last page. limit is 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.

Server:https://api.sunnysdk.com

Production

Client Libraries

Projects (Collapsed)

​

A project is one job, usually one building. It holds the floors, and its Library holds the job's photos, documents and 3D models.

Floors (Collapsed)

​

A floor is one storey of a project. Rooms sit on its plate, and the floor check reports rooms that overlap, run off the plate or sit on the building core.

Rooms (Collapsed)

​

A room sits on a floor. Its furniture is the room's layout, which you can read or replace as a sunny-layout document. Every save keeps a version.

Catalog (Collapsed)

​

The furniture Sunny can place and quote: products with their sizes, finishes and photos, and the manufacturers that make them.

Customers (Collapsed)

​

The people and companies a workspace quotes for. Every quote belongs to a customer.

Quotes (Collapsed)

​

Present Links (Collapsed)

​

A Present link is the URL that shows a quote to the customer. A quote has one active link at a time; revoking it stops the URL working.

Discount Tables (Collapsed)

​

A discount table sets dealer cost: the discount off list price, by manufacturer, catalog, product group or SKU. Reading one needs quote_costs:read.

Search (Collapsed)

​

One query across projects, rooms, catalog items, typicals, product families, customers and quotes.

Search Operations

Audit Log (Collapsed)

​

Who changed what in the workspace: API keys, quotes, customers, discount tables and webhook endpoints.

Audit Log Operations

Sandbox (Collapsed)

​

A sandbox workspace holds test data for building against the API. Resetting it restores the starting customer and discount table.

Sandbox Operations

Models