Looking for detailed request/response examples? Each endpoint is documented and can be used in the interactive playground for each example. Use the tag selector in the sidebar to jump to any specific route referenced below.

Domains & Formats

• All requests are issued against your API domain, typically https://api.nimbu.io. Self-hosted installations reuse the same path structure on their own hostname.
• JSON is the default representation. When an endpoint accepts file uploads, the specification explicitly calls out multipart/form-data.
• Every response echoes an X-Nimbu-API-Version header so clients can confirm the negotiated version.

Versioning & Content Negotiation

The current stable version is 0. You can ask for a specific version with the Accept header:

Accept: application/vnd.io.nimbu-v0+json

If the header is omitted the API still returns JSON and includes X-Nimbu-API-Version. Setting Accept: application/hal+json enables HAL-style envelopes with _links and _embedded relationships when available.

Authentication Overview

• Send OAuth access tokens in Authorization: Bearer <token>.
• Tokens may be user-scoped or site-scoped; user tokens generally need the X-Nimbu-Site header to select the site context.
• Responses mirror the granted scopes via X-OAuth-Scopes and list the scopes the route expected in X-Accepted-OAuth-Scopes.

See Authentication for token lifecycles, header requirements, and the full scope catalogue.

Pagination, Filtering & Query Parameters

• Collections accept page and per_page (default 30). Link headers advertise first, prev, next, and last.
• Many endpoints expose direct filters that mirror resource attributes (for example status, locale, or tag). Check the relevant operation description for the supported keys.
• Content-heavy resources often support helpers such as resolve, resolve_depth, only, or include_slugs to control payload size.
• Most major resources expose a /count route for lightweight dashboards. Soft-deleted records are available under /deleted collections where applicable.

Error Handling

Errors follow a consistent structure:

{
  "message": "Validation failed",
  "code": "validation_error",
  "errors": [
    {
      "resource": "Product",
      "field": "title",
      "message": "title can't be blank",
      "code": "blank"
    }
  ]
}

• Validation issues return HTTP 422 with field-level metadata.
• Missing resources return HTTP 404 with code: object_not_found.
• Partial successes in bulk requests may surface as HTTP 207 Multi-Status.
• Authentication failures return HTTP 401; insufficient scopes or ACL issues return HTTP 403.

Headers You Will See

Header	Meaning
X-OAuth-Scopes	Scopes the current token carries.
X-Accepted-OAuth-Scopes	Minimum scopes the endpoint required.
X-Nimbu-API-Version	Final API version used for the response.
Link	Pagination links for collection responses.
Location	Created resource URL on 201 Created responses.
X-Nimbu-Client-Version (request)	Enables feature-gating metadata in certain responses.
X-Nimbu-Log-Params (request)	Echoes parsed parameters in responses to help with debugging requests.

Explore Common Workflows

Each bullet links to the corresponding operation inside the explorer. Use them as starting points for deeper dives.

Set Up Your Environment

• List accessible sites – discover site identifiers for subsequent calls.
• Retrieve a site – fetch settings and status for a specific site.
• Work with access tokens – list existing tokens, or create one with POST /tokens.

Manage Content & Navigation

• List channels and manage entries to drive structured content.
• Create or update pages and menus for static navigation.
• Localise strings via translations or fetch specific keys with GET /translations/{translation_key}.

Commerce & Customer Data

• Manage products and related customisations such as checkout profiles.
• Review orders or update order state.
• Handle customers and customer sessions for storefront authentication flows.

Themes, Assets & Apps

• Inspect themes and update layouts, templates, snippets, or assets via the nested theme routes.
• Upload media assets and fetch metadata with GET /uploads/{id}.
• Automate OAuth apps or manage app-specific code bundles.

Automation & Messaging

• Subscribe to webhooks to react to events in your integrations.
• Send notifications or fetch a specific notification by slug.
• Trigger serverless functions or background jobs when available in your plan.

Hypermedia Root

GET / returns a discovery document pointing to canonical collections (activities, blogs, channels, etc.). Use it to bootstrap clients that prefer link-driven navigation over hard-coded paths.

Rate Limiting & CORS

Cross-origin requests follow standard CORS preflight behaviour. Responses include throttling headers whenever rate limits apply so clients can back off proactively.