---
seo:
  description: REST API for partners and integrations.
sidebar:
  label: Overview
title: Bloomcount Public API
---
REST API for partners and integrations.

## Authentication
All endpoints require an `Authorization: Bearer bloomcount_...` header. Keys are
issued from **Settings → API** in the app and are scoped — a key without
`products:write` cannot create products, etc.

## Bulk endpoints
Create / update endpoints accept arrays so a single request can cover up
to **500 items**. Per-row failures are reported in the `errors` array
rather than failing the whole call.

## Idempotency
POST endpoints honour `Idempotency-Key`. A replay with the same key
returns the cached response verbatim; the underlying mutation runs once.
Cache TTL is 24 hours, scoped to the API key.

## Rate limits & quotas
- **Per-key rate limit:** 60 requests / minute. Exceeding returns `429 rate_limited`.
- **Per-tenant monthly cap:** configured per plan (default unlimited via the
  override). Exceeding returns `429 monthly_limit_exceeded`.

## IDs
IDs are resource-prefixed strings — the prefix tells you what kind of
resource the ID refers to. Treat the part after the underscore as opaque
(do not parse), but you can rely on the prefix.

| Prefix      | Resource             |
|-------------|----------------------|
| `prod_`     | Product              |
| `var_`      | Product variant      |
| `sup_`      | Supplier             |
| `pl_`       | Price list           |
| `pe_`       | Price entry          |
| `tax_`      | Tax group            |
| `evt_`      | Event                |
| `evtgrp_`   | Event group          |
| `evti_`     | Event item (line)    |
| `whsub_`    | Webhook subscription |

Passing the wrong kind of ID (e.g. a `var_…` where a `prod_…` is expected)
returns `422 wrong_id_type:expected_<table>_got_<table>` so the mistake is
self-describing. Mismatched / malformed IDs return
`422 invalid_id_format` or `422 invalid_id_prefix:<prefix>`.

<ApiOverview source="reference" />

## Tax Groups

<ApiTagOperations source="reference" tag="tax-groups" />

## Products

<ApiTagOperations source="reference" tag="products" />

## Suppliers

The suppliers that products and per-variant prices can be assigned to. An integration needs a supplier ID before it can write per-supplier prices or per-(variant, supplier) minimum order quantities (MOQ), so it can create its own here rather than waiting for someone to add them in the app. The hidden Default supplier and archived rows aren't listed.

Suppliers archive rather than delete, because products keep referencing their IDs. Archiving relinks anything left without a supplier to the hidden Default.

<ApiTagOperations source="reference" tag="suppliers" />

## Price Lists

<ApiTagOperations source="reference" tag="price-lists" />

## Events

<ApiTagOperations source="reference" tag="events" />

## Webhook subscriptions

Manage which URLs receive event deliveries.

<ApiTagOperations source="reference" tag="webhook-subscriptions" />

## Venues

Where events happen. An event references a venue by ID, and the driving distance from your own address is worked out in the background.

<ApiTagOperations source="reference" tag="venues" />

## Staff

The people who work events, with their rates.

<ApiTagOperations source="reference" tag="staff" />

## Colours

The colour vocabulary. A variant's `colors` and an event's `colourScheme` are matched by label, not by ID, so listing these is how you learn which labels will match. Renaming one retags everything that used the old label.

<ApiTagOperations source="reference" tag="colours" />

## Categories

The category vocabulary. A product's `category` is matched by label, so listing these is how you learn which labels will match. Renaming one retags every product that carried the old label.

<ApiTagOperations source="reference" tag="categories" />