# API Reference

> Read and write your workspace ontology programmatically — endpoints, auth, schemas, and a downloadable full reference.

**Category:** AI Integrations | **Tab:** integrations

---

The Black Ice API lets external tools — Claude Code, AI agents, scripts, or CI pipelines — read and write your workspace ontology programmatically. It's the same data layer the Black Ice UI uses, exposed over HTTPS with key-based authentication.

## What you can do

- **Read** the full ontology (concepts, terms, classes, relationships, markets, brand identity) as a single JSON document
- **Download** the AI Agent Bundle — the same Markdown files as the in-app ZIP and GitHub Sync — as a ZIP, one file at a time, or as a JSON list
- **Write** in batches: create, update, delete, or upsert concepts, terms, relationships, classes, and market constraints
- **Sync** terminology from external systems (TMS, PIM, CMS) without leaving your tool of choice

## Endpoints

| Method | Endpoint | Purpose |
|---|---|---|
| `GET`  | `/functions/v1/query-ontology`  | Export the full workspace ontology (JSON by default) |
| `GET`  | `/functions/v1/query-ontology?format=markdown-zip` | AI Agent Bundle as a ZIP |
| `GET`  | `/functions/v1/query-ontology?format=markdown&path=…` | One bundle file as plain Markdown |
| `GET`  | `/functions/v1/query-ontology?format=markdown-files` | All bundle files as JSON `{ path, content }` |
| `POST` | `/functions/v1/mutate-ontology` | Apply a batch of write operations |

Base URL: `https://oosdjmpzvcljxwaqxcko.supabase.co`

## Authentication

Every request must include the header `x-api-key: bice_xxxxxxxx`. Generate a key from **Settings → API Access** in the app. Keys are scoped to a single workspace.

### Key scopes

Each key is created as either **read only** or **read and write**:

- **Read only** — may call `GET /query-ontology` only. Use this for one-directional integrations that pull the ontology as reference data (a TMS, CMS, or RAG pipeline that never writes back).
- **Read and write** — may call both endpoints, including `POST /mutate-ontology`.

A read-only key used against `POST /mutate-ontology` returns **403** with `"code": "insufficient_scope"`. Choose the scope in **Settings → API Access** when generating the key; it cannot be changed afterwards (create a new key with the desired scope and revoke the old one).

### Submitting term candidates

`POST /functions/v1/mutate-ontology` also accepts a `candidates` array instead of `operations`. Candidates go to the [review queue](/docs/features/candidate-review-workflow), never directly into the ontology.

| Field | Required | Notes |
|---|---|---|
| `term` | yes | 1–200 characters |
| `locale_code` | yes | e.g. `en-us` |
| `definition` | no | up to 2,000 characters |
| `class_name` | no | linked if it matches an existing class |
| `source` | no | label for acceptance-by-source stats (default `api`) |
| `frequency`, `confidence` | no | confidence only orders the queue |
| `provenance` | no | object or array, e.g. `{ "url": "...", "note": "..." }` |

Up to **500** per request; requires a **read-and-write** key. The response returns `created`, `updated` (repeats), `suppressed` (on the rejection list), `resurfaced` and per-item `errors`. AI assistants can do the same through the MCP tool `suggest_candidates` (50 per call), once an owner or admin turns it on — it is off by default.

## Tier & limits

- Available on **all plans**, including Free — per-plan quotas (concepts, markets, members) apply as normal
- **Reads:** 60 requests/min per key
- **Writes:** 30 requests/min per key, max 50 operations per request
- Bidirectional relationships are auto-mirrored server-side — no need to insert both directions

## Quick example

```bash
curl --header "x-api-key: bice_YOUR_KEY_HERE" \
  "https://oosdjmpzvcljxwaqxcko.supabase.co/functions/v1/query-ontology"
```

## Markdown bundle

Add `format` to the read endpoint to get the AI Agent Bundle instead of JSON. Options: `locale` (one market), `approved_only=true` (approved target terms only), and `path` (for `format=markdown`, e.g. `markets/es-es.md`; unknown paths return 404 with the list of available paths).

```bash
curl --header "x-api-key: bice_YOUR_KEY_HERE" -o black-ice-ontology.zip \
  "https://oosdjmpzvcljxwaqxcko.supabase.co/functions/v1/query-ontology?format=markdown-zip"
```

Every file starts with the bundle version and generation time, and notes that it is a snapshot — the live workspace is the source of truth. Responses carry `ETag`, `X-Bundle-Version` and `X-Generated-At`; send `If-None-Match` to get `304 Not Modified` when nothing changed, or use `HEAD` to read just the version. Each request counts as one API call.

> Need Markdown? Use `format=markdown-zip` — don't rebuild the bundle from the JSON response. In JSON, each market's guidelines are in `definitions` (with saved section order and custom sections); `cultureDna` is an older name for the same value.

> For AI assistants, prefer the live MCP connection. Use the ZIP or GitHub Sync for pipelines.

## Full reference

The complete reference covers every entity (concept, term, relationship, class, market_constraint), all actions (create / update / delete / upsert), field-level schemas, error codes, and worked examples — including a section of best practices for AI agents.

<a href="/black-ice-api.md" download="BLACK_ICE_API.md" class="inline-flex items-center gap-2 mt-4 px-4 py-2.5 rounded-lg bg-primary text-primary-foreground font-medium hover:opacity-90 transition no-underline">📥 Download full API reference (Markdown)</a>

> 💡 **Tip for Claude Code users:** drop `BLACK_ICE_API.md` into your project's context folder. Claude can then call the API directly with the right schemas, IDs, and bidirectional handling already understood.

## Rate limits

All API and MCP calls are subject to per-plan throughput caps (Free 60 reads / 30 writes per minute, Pro 300 / 120, Builder 1,000 / 400). See [API & MCP rate limits](/docs/integrations/rate-limits) for headers, 429 handling, and pipeline design tips.