# API Overview (/docs/api/overview)



> 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 [#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 [#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 [#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](./authentication) for token lifecycles, header requirements, and the full
scope catalogue.

Channel entries can also be filtered by channel and row-level ACLs. See
[Channel Access Control](./channel-access-control) for `Session-Token`, `use_acl`, `_owner`, and
`_acl` behavior.

## Pagination, Filtering & Query Parameters [#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 [#error-handling]

Errors follow a consistent structure:

```json
{
  "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`.
* Channel entries hidden by row-level ACLs also return HTTP `404` on single-entry routes.
* 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 [#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.                               |
| `Session-Token` (request)          | Evaluates ACL-aware requests as a customer session.                    |
| `X-Nimbu-Session-Token` (request)  | Alternate customer session header accepted by CORS clients.            |
| `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 [#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 [#set-up-your-environment]

* [List accessible sites](/docs/api/reference/sites/sites/get) – discover site identifiers for subsequent calls.
* [Retrieve a site](/docs/api/reference/sites/sites/site_id/get) – fetch settings and status for a specific
  site.
* [Work with access tokens](/docs/api/reference/tokens/tokens/get) – list existing tokens, or create one with
  [POST /tokens](/docs/api/reference/tokens/tokens/post).

### Working with Complex Fields [#working-with-complex-fields]

* [Custom Field Types](./custom-fields) – how to send file uploads, references, galleries, and
  selects when creating or updating channel entries.

### Manage Content & Navigation [#manage-content--navigation]

* [List channels](/docs/api/reference/channels/channels/get) and
  [manage entries](/docs/api/reference/channel-entries/channels/channel_id/entries/get) to drive structured content.
  Use [Channel Access Control](./channel-access-control) when storefront customers should see
  different rows.
* [Create or update pages](/docs/api/reference/pages/pages/post) and [menus](/docs/api/reference/menus/menus/post) for static
  navigation.
* [Localise strings via translations](/docs/api/reference/translations/translations/count/get) or fetch specific keys
  with [GET /translations/\{translation\_key}](/docs/api/reference/translations/translations/translation_key/get).

### Commerce & Customer Data [#commerce--customer-data]

* [Manage products](/docs/api/reference/products/products/get) and related customisations such as
  [checkout profiles](/docs/api/reference/products/products/checkout_profiles/post).
* [Review orders](/docs/api/reference/orders/orders/get) or
  [update order state](/docs/api/reference/orders/orders/order_id/put).
* [Handle customers](/docs/api/reference/customers/customers/get) and
  [customer sessions](/docs/api/reference/customer-sessions/customers/login/post) for storefront authentication flows.

### Themes, Assets & Apps [#themes-assets--apps]

* [Inspect themes](/docs/api/reference/themes/themes/get) and update layouts, templates, snippets, or assets via
  the nested theme routes.
* [Upload media assets](/docs/api/reference/uploads/uploads/post) and fetch metadata with
  [GET /uploads/\{id}](/docs/api/reference/uploads/uploads/id/get).
* [Automate OAuth apps](/docs/api/reference/apps/listApps) or manage app-specific code bundles.

### Automation & Messaging [#automation--messaging]

* [Subscribe to webhooks](/docs/api/reference/webhooks/webhooks/get) to react to events in your integrations.
* [Send notifications](/docs/api/reference/notifications/notifications/post) or fetch a specific notification by slug.
* [Trigger serverless functions](/docs/api/reference/functions/executeFunction) or background jobs when
  available in your plan.

## Hypermedia Root [#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 [#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.