# Black Ice — Complete Documentation
> The invisible semantic layer powering AI-native global content.
---
# Welcome to Black Ice
> Learn what Black Ice is and how it helps manage product terminology.
Welcome to Black Ice
# Launch faster. Own your brand in every market.
Black Ice gives teams a single, governed source of truth for product naming, messaging, and market rules — so every campaign, landing page, and product launch goes out with the right words, in the right market, without last-minute firefighting.
The problem it solves
## Brand inconsistency is a product problem in disguise.
When your product has different names in different markets — because legal said so, because the plan includes different features, because the term means something different in German — that complexity lives in spreadsheets, email threads, and tribal knowledge. Until it breaks.
> *"The French team launched the campaign with the wrong plan name. The feature isn't available there. Legal flagged it after go-live."*
>
> — A story every global marketing team knows.
Black Ice makes that complexity visible, governed, and connected to the teams who produce content — before it ships.
---
What it looks like in practice
## Your product — one source of truth, three markets
| Market | Plan Name | Key Rules |
|--------|-----------|-----------|
| 🇺🇸 **US** | Pro | Includes Analytics, API Access, Collaboration, Custom Exports. No restrictions. Standard brand voice. |
| 🇩🇪 **Germany** | Pro | Custom Exports available on Enterprise only. Formal register required. API retained as anglicism. Legal disclaimer required on pricing pages. |
| 🇧🇷 **Brazil** | Pro | Analytics renamed *Análise de Dados* per brand approval. API Access not yet launched. Warm, conversational register. |
> Every content producer — copywriter, campaign manager, localization vendor — works from the same approved data. No version confusion, no market mix-ups.
---
What your team gets
## Four pillars of brand governance
One approved source
Product names, feature terms, and market rules live in one place. Not three spreadsheets and a Notion doc.
Market-ready by default
Know exactly what's available where, what it's called, and what the brand voice requires — before the brief goes out.
Legal and brand approval baked in
Send terms for review via shareable link. Reviewers approve or comment without needing an account.
AI that uses your actual brand rules
When you use AI to draft or localize content, it reads your approved terminology and market conventions — not a generic prompt.
---
How it fits your workflow
## From setup to structured output
Set up your product model — define plans, features, and platform terms once
Add market rules — what's available where, what it's called, what register to use
Get sign-off — legal, brand, and regional reviewers approve inline, no account required
Share with your team — copywriters, agencies, and localization vendors all pull from the same approved source
Connect to your AI tools — Black Ice exports your brand knowledge as structured context your AI tools actually use
---
Who uses Black Ice
## Built for cross-functional brand teams
Global marketing teams
Brief agencies and content teams with market-specific naming and messaging rules already approved.
Brand and legal teams
Review and approve product terminology before it reaches campaigns. Full audit trail of who approved what.
Content and localization managers
One governed source replaces fragmented glossaries, style guides, and market-specific instructions.
Product marketers
Define canonical product positioning per market. Engineering, sales, and support stay aligned without chasing you.
---
# How Black Ice works
> A one-page picture of how decisions flow from your team to your tools, and where your data lives.
Black Ice runs no model. It stores the decisions your team makes about terminology, and your tools read those decisions. This page shows how that works and where your data lives.
## 1. Your people decide
Terminologists, brand, legal and regional reviewers define concepts, terms and market rules in the Black Ice app. Approvals and every change are recorded with who decided and when, in the term history.
## 2. The governed ontology
The result is your governed ontology: concepts, approved terms, market definitions and relationships. It is isolated per workspace, encrypted, and never used to train any model.
## 3. Your tools read it
- **Read API**: pull the ontology into pipelines and CI jobs. Read-only keys are available. See [Pulling the ontology into your stack](/docs/integrations/ontology-pull-integration) and the [API reference](/docs/integrations/api-reference).
- **MCP server**: AI agents such as Claude or your IDE look up approved terms live. See [Connect Claude](/docs/integrations/connect-claude-mcp).
Both are served from the EU region.
## Optional: GitHub Sync
GitHub Sync is **off by default** and entirely your choice. It only runs if a workspace owner connects a repository and a token. When enabled, it copies your approved terms as Markdown files to the repository you choose. GitHub is listed as a sub-processor for this opt-in feature only.
**If you don't enable GitHub Sync, your ontology stays in the EU.** You can disconnect it at any time. See [GitHub Sync](/docs/integrations/github-sync).
## Where your data lives
- Your ontology content is stored and processed in the EU (Frankfurt, eu-central-1).
- The Read API and MCP server serve it from there.
- GitHub Sync is the only feature that copies ontology content elsewhere, and only to a repository you pick.
- Supporting services (email delivery, payments, CDN) are listed with their regions on the [Sub-processors](/legal/sub-processors) page.
Read more in [Privacy by design for integrations](/docs/integrations/privacy-by-design-integrations) and [Security and data protection](/docs/getting-started/security-and-data-protection).
---
# Plans and pricing
> Compare Free, Pro, and Builder plans for Black Ice.
Black Ice offers three tiers designed to scale with your terminology management needs.
## Plan comparison
| | **Free** | **Pro** | **Builder** |
|---|---|---|---|
| **Price** | €0/month | €49/month | €199/month |
| **Concepts** | Up to 50 | Up to 350 | Unlimited |
| **Markets** | Up to 3 | Up to 20 | Unlimited |
| **Workspaces** | 1 | 1 | Up to 3 |
| **Team members** | — | — | Up to 10 |
| **Workspace API + MCP server** | ✓ | ✓ | ✓ |
| **API/MCP rate limits (read/write per min)** | 60 / 30 | 300 / 120 | 1000 / 400 |
| **Monthly API/MCP calls** | 10,000 | Unlimited | Unlimited |
| **Exports: JSON, Markdown, CSV, ZIP, PDF** | ✓ | ✓ | ✓ |
| **Exports: RDF/OWL (Turtle, JSON-LD)** | — | ✓ | ✓ |
| **Knowledge graph image export (SVG, PDF)** | — | ✓ | ✓ |
| **GitHub Sync** | — | — | ✓ |
| **Email digests & alert preferences** | — | ✓ | ✓ |
| **Priority support** | — | ✓ | ✓ |
## Free
Ideal for individual language professionals exploring structured terminology. Includes the full ontology editor, knowledge graph, approval workflows, custom fields, the Workspace API, the MCP server, and the JSON, Markdown, ZIP, PDF, and CSV exports.
Programmatic access on Free is capped at **10,000 API + MCP calls per calendar month** per workspace (reads and writes each count as one call). That covers evaluation, CI experiments, and everyday Claude or Cursor sessions; sustained agent pipelines need Pro or Builder, which have no monthly cap. Working in the app itself — editing, importing, exporting, syncing — never consumes the allowance. See [API & MCP rate limits](/docs/integrations/rate-limits).
## Pro — €49/month
For localization managers handling multiple markets. Adds higher concept and market limits, higher API/MCP rate limits, RDF/OWL exports, high-resolution graph exports, email digests, alert preferences, and the unified Permissions panel.
## Builder — €199/month
For teams and organizations. Adds team management with role-based access (owner, admin, editor, viewer), GitHub Sync for CI/CD distribution, multiple workspaces (up to 3), unlimited concepts and markets, and the highest rate limits.
Includes a monthly 1-hour consultancy session with our team to set up and refine your agentic workflows. For deeper, ongoing engagements, see the Custom Partner plan.
## Annual billing
Save approximately 17% with annual billing on Pro and Builder. Switch billing cadence anytime from **Settings → Subscription**.
## Upgrading and downgrading
Upgrades take effect immediately and are prorated. Downgrades take effect at the end of the current billing period. If you exceed a lower tier's limits after downgrading, your data is preserved but you cannot add new entries until you're back under the limit.
## FAQ
**Can I change plans later?** Yes — upgrade or downgrade at any time from Settings → Subscription.
**What happens if I exceed my concept limit?** You won't lose data, but you'll need to upgrade to add new concepts.
**Is there an enterprise plan?** [Contact us](/contact) to discuss custom pricing, SSO, and dedicated infrastructure for large organizations.
**How do I cancel?** Open the Stripe customer portal from Settings → Subscription and cancel there. Access continues until the end of your billing period.
---
# Best practices
> Tips for structuring your ontology and managing terminology effectively.
Follow these guidelines to get the most out of Black Ice and keep your ontology clean, scalable, and useful.
## Structure your classes thoughtfully
Classes are the backbone of your ontology. Define them early and keep them stable.
- **Use domain-specific names** — "Feature", "Plan", "Platform", "Campaign" are better than "Item" or "Thing"
- **Keep classes mutually exclusive** — A concept should belong to exactly one class
- **Add descriptions** — Future team members will thank you for documenting what each class represents
- **Set translation policies** — Some classes (like "Plan") may use do-not-translate policies, while "Feature" terms need localization
## Name concepts clearly
Concept names are the canonical, language-neutral identifiers for your terms.
- **Use the English source term** as the concept name
- **Be specific** — "MIDI Editor" is better than "Editor"
- **Avoid abbreviations** unless they're the official product name
- **Use title case** consistently
## Manage variants intentionally
Allowed and forbidden variants are powerful governance tools.
- **Allowed variants** — List acceptable alternatives (e.g., "Creator Starter Plan" alongside "Creator Starter")
- **Forbidden variants** — Explicitly block incorrect usage (e.g., "Starter Pack", "Basic Plan")
- **Review variants regularly** — As your product evolves, old variants may become incorrect
## Use market availability strategically
Not every term is ready in every locale at the same time.
- **Set availability early** — Mark source terms as "Available" and target terms as "Planned" during initial setup
- **Track readiness per locale** — Use availability statuses to see at a glance which translations are live, pending, or blocked
- **Review mismatches** — The concept detail page shows availability badges on each term, making it easy to spot gaps
## Keep relationships meaningful
Semantic relationships make your ontology a connected graph, not a flat list.
- **Define relationship types first** — Set up types like "hasFeature", "hasPillar", "isPartOf" before creating concept links
- **Use bidirectional relationships** — They generate inverse labels automatically
- **Don't over-connect** — Only create relationships that provide real navigational or structural value
## Approval workflow tips
- **Write clear messages** for reviewers explaining what they're approving and why
- **Set appropriate expiry dates** — Default is 30 days, but time-sensitive terms may need shorter windows
- **Use role-based filtering** — Configure which approver roles can review specific term types
---
# Quick start
> A step-by-step guide to creating your first concept in Black Ice.
Get up and running with Black Ice in under 5 minutes. This guide walks you through creating your first concept, connecting it to others, and adding translations.
## Prerequisites
- A Black Ice account (sign up at the login page)
- A workspace is automatically created when you sign up
## Step 1: Explore your workspace
After signing in, you'll land on the **Dashboard**. This shows your ontology stats, recent activity, and quick actions. Your workspace already has a source locale (English US by default).
## Step 2: Create your first class
Navigate to **Classes** in the sidebar. Classes are categories that group your concepts — like "Feature", "Plan", or "Platform".
1. Click **Add Class**
2. Enter a name (e.g., "Feature") and an optional description
3. Choose a color and translation policy
4. Click **Create**
## Step 3: Add a concept
Go to **Concepts** and click **Create Concept**.
1. Select the class you just created
2. Enter a name (e.g., "MIDI Editor")
3. Add an optional description
4. Click **Create** — Black Ice auto-generates a unique concept ID
## Step 4: Add translations
Open your new concept and scroll to the **Terms** section.
1. Your source term is pre-filled from the concept name
2. Click **Add Target Term** to add a translation
3. Select a locale (e.g., "Spanish (ES)")
4. Enter the preferred term and any allowed/forbidden variants
5. Set the approval status
## Step 5: Set market availability
Each term — source and target — has a **Market Availability** dropdown.
1. In the source term card, set availability (e.g., "Available")
2. In each target term card, set its own availability independently
3. Use this to track which translations are live, planned, or blocked
> Market availability is tracked per term, not per concept. This lets you manage rollout status for each locale separately.
## Step 6: Define relationship types and connect concepts
Relationships are what turn a flat list of concepts into a connected, navigable ontology. They express how concepts relate to each other — e.g., a Plan *hasFeature* a Feature, or a Feature *isPartOf* a Plan.
**First, create a relationship type:**
1. Navigate to **Relationships** in the sidebar
2. Click **Add Type**
3. Enter a label (e.g., "hasFeature"), a machine value, and an optional inverse label (e.g., "isFeatureOf")
4. Choose directionality — **unidirectional** or **bidirectional** (bidirectional auto-creates the inverse)
**Then, connect two concepts:**
1. Open a concept's detail page
2. Scroll to the **Semantic Relationships** section
3. Click **Add Relationship**
4. Select the relationship type and the target concept
5. The relationship appears on both concepts if bidirectional
> Relationships power the **Knowledge Graph** and structured exports. The more intentionally you connect concepts, the more useful your ontology becomes for downstream consumers — including AI tools.
## Step 7: Visualize your ontology
Navigate to **Knowledge Graph** in the sidebar. You'll see your concepts as nodes, connected by the relationships you defined. Use the filters to focus on specific classes or relationship types. Toggle **One-Hop** to reveal second-level connections.
## What's next?
- [Best practices →](/docs/getting-started/best-practices) — Tips for structuring your ontology
- [Import & Export →](/docs/features/csv-and-excel-import) — Bulk import existing terminology
- [Approval workflows →](/docs/features/approval-workflows) — Send terms for review
---
# Getting started with AI
> Connect your Black Ice ontology to AI models in minutes.
## Why connect AI to your ontology?
Black Ice structures your terminology, market rules, and brand voice. AI models consume that structure and turn it into governed content — translations, copy, QA checks — without guessing.
> Without an ontology, AI writes fluently. With one, it writes *correctly*.
## The 3-step pattern
**1. Pick a connection path**
There are three ways to get your ontology in front of an AI tool. They are complementary — most teams end up using two.
| Path | Best for | Access model | Plan |
|---|---|---|---|
| **MCP server** | Live agent access (Claude, Cursor, IDEs) | OAuth or API key, tools | All plans |
| **Workspace API** | Custom pipelines, CI jobs, bulk reads/writes | API key, JSON | All plans |
| **GitHub Sync** | Repo-native agents, review workflows, versioned snapshots | GitHub PAT, Markdown | Builder |
If a human is chatting with an AI client, start with **MCP** — it is always current and needs no export step. If you are scripting, use the **Workspace API**. If your agent lives in a code repo, use **GitHub Sync**.
**2. Connect your tool**
- **Claude (web or desktop)** — add Black Ice as a custom connector: [Connect Claude to your workspace (step by step)](/docs/integrations/connect-claude-mcp)
- **Cursor, VS Code, other MCP clients** — [Connect Cursor and other MCP clients](/docs/integrations/connect-cursor-mcp)
- **Custom pipelines** — [Workspace API access](/docs/integrations/workspace-api-access)
- **Repo-based agents (Claude Code, Codex, CI)** — [GitHub Sync](/docs/integrations/github-sync)
- **One-off use (Gemini, Custom GPTs, NotebookLM)** — use **Export** and attach the Markdown, ZIP, or PDF bundle
**3. Prompt with semantic context**
Your prompts no longer need to explain terminology, tone, or market rules. The ontology already contains all of that, so prompts become task-focused:
- *"Write a landing page for the Spain market"*
- *"Review these translated strings for terminology consistency"*
- *"Localize only the concepts that changed since last sprint"*
Ready-made prompts for localization workflows are in the [Claude guide](/docs/integrations/connect-claude-mcp).
## What can you do with it?
- **Generate market-specific content** without briefing docs
- **QA translations** against your approved terminology
- **Run delta localization** — only translate what changed
- **Enforce consistency** across multiple projects from a single ontology
- **Run fully local pipelines** for regulated industries
## Next steps
- [Black Ice + AI: What Your Ontology Unlocks](/docs/integrations/ai-integrations-overview) — model-specific workflows
- [Define your market rules](/docs/features/market-definitions) so AI models know your brand voice per locale
- [API & MCP rate limits](/docs/integrations/rate-limits)
---
# FAQ
> Answers to common questions about Black Ice.
Answers to the most common questions about Black Ice.
## General
**What is Black Ice?**
Black Ice is a semantic governance platform that helps teams govern how product terminology is defined, translated, and adapted across markets. It generates a structured bundle of markdown files — your ontology, translation rules, and market profiles — that AI localization pipelines consume directly.
**Is Black Ice a translation tool?**
No. Black Ice manages the semantic layer — the governed terminology, market context, and Culture DNA — that your AI pipeline needs to generate accurate, brand-consistent target content. The pipeline localizes automatically from that foundation.
**What happens to the translator?**
The role evolves. Translators become market owners — they architect the meaning, validate the terminology, and define the Culture DNA for their markets. The AI pipeline handles content generation. The market owner governs the rules it runs on and QAs the output.
**Do I need technical knowledge to use Black Ice?**
No. Black Ice is designed for terminology managers, localization PMs, and product teams. The interface is visual and no coding is required.
## Data & Import
**Can I import existing terminology?**
Yes. Black Ice supports CSV and Excel import with column mapping, duplicate detection, and conflict resolution.
**What export formats are available?**
JSON, Markdown, CSV (two layouts, with configurable columns), the AI Agent Bundle (ZIP), PDF, and — on Pro and Builder — RDF/OWL as Turtle or JSON-LD.
**Can I connect Black Ice to my TMS?**
Yes, in three ways: the Workspace API (all plans) for direct read/write integration, the MCP server (all plans) for live AI client access, and GitHub Sync (Builder) for repo- and CI-driven pipelines.
## Languages & Markets
**What languages are supported?**
Black Ice supports any language. You define your own locales with language codes, native names, and text direction (LTR/RTL).
**How many markets can I manage?**
Free plan: up to 3 markets. Pro: up to 20. Builder: unlimited.
**What is market availability?**
Market availability is a per-term status that tracks whether a source or target term is live, planned, unapproved, or not available in its locale. Each term has its own availability setting, giving you granular control over rollout readiness.
## Collaboration
**How do I invite team members?**
Go to **Settings → Team Management** and send an invite by email. Team members can be assigned roles: Admin, Editor, or Viewer.
**How do approvals work?**
You select terms and send them for review via a shareable link. The reviewer (who doesn't need a Black Ice account) can approve or reject each term with comments. All decisions are recorded in the approval history.
**Can multiple people edit the same workspace?**
Yes. Team members with Editor or Admin roles can create and modify concepts, terms, and relationships simultaneously.
## Security & Privacy
**Where is my data stored?**
All data is stored in a secure cloud database with row-level security policies. Only authenticated users with the correct workspace permissions can access your data.
**Can I delete my account and data?**
Yes. Go to **Settings → Account** to delete your account. This permanently removes all your data.
---
# Glossary
> Definitions of key terms used in Black Ice.
Key terms used throughout Black Ice and this documentation.
## Concept
A language-neutral unit of meaning in your ontology. Each concept has a unique auto-generated ID, a name, a class, and one or more terms in different locales. Example: "MIDI Editor" is a concept of class "Feature".
## Class
A category that groups related concepts. Classes define the type of thing a concept represents — such as Feature, Plan, Platform, or Campaign. Each concept belongs to exactly one class.
## Source term
The canonical term for a concept in your workspace's source locale (typically English). The source term serves as the reference for all translations.
## Target term
A translation of a concept in a specific locale. Each target term includes the preferred translation, optional allowed/forbidden variants, notes, and an approval status.
## Locale
A language-region combination used for translations (e.g., `en-us`, `es-es`, `de-de`). Each locale has a name, native name, text direction, and optional Culture DNA configuration.
## Culture DNA
A structured set of guidelines attached to a locale that defines voice, tone, terminology rules, UX microcopy standards, and cultural pragmatics for that market. Used to ensure translations align with local expectations.
## Market
A geographic or business region where your product is available (e.g., US, EU, LATAM, APAC). Markets correspond to locales in your workspace.
## Market availability
A per-term status indicating whether a source or target term is live, planned, unapproved, or not available in its locale. Each term tracks availability independently, enabling granular rollout control.
## Semantic relationship
A typed connection between two concepts (e.g., "Creator Starter" *hasFeature* "MIDI Editor"). Relationships can be unidirectional or bidirectional and include inverse labels.
## Relationship type
A reusable definition for a kind of semantic connection (e.g., `hasFeature` / `isFeatureOf`). Relationship types are defined per workspace and include labels, inverse labels, and directionality.
## Ontology
The complete structured system of concepts, terms, relationships, classes, and market availability statuses in your workspace. Your ontology is what you export, sync, and share.
## Approval workflow
The process of sending terms for review to stakeholders via shareable links. Reviewers can approve or reject individual terms with comments. All decisions are recorded with timestamps.
## Workspace
An isolated environment containing your ontology, team members, and settings. Each workspace has an owner and can include Admins, Editors, and Viewers.
## Knowledge graph
A visual representation of your ontology showing concepts as nodes and semantic relationships as edges. The graph is interactive and filterable by class and relationship type.
---
# Support
> How to get help with Black Ice.
Need help with Black Ice? Here's how to reach us.
## Contact form
For general questions, feature requests, or partnership inquiries, use our [contact form](/contact). We typically respond within 24 hours on business days.
## Community
Join the **Black Ice Discord community** to connect with other terminology professionals, share best practices, and get help from the community.
[Join Discord →](https://discord.gg/4CuCQvsh)
## Email support
Pro and Builder plan subscribers receive priority email support. Reach out at the email listed in your account settings.
## Bug reports
If you encounter a bug, please report it in the **#black-ice-feedback** channel on our [Discord server](https://discord.gg/4CuCQvsh). When reporting, please include:
1. **What you were trying to do** — the action you performed
2. **What happened** — the unexpected behavior
3. **What you expected** — the correct behavior
4. **Screenshots** — if applicable
## Feature requests
We love hearing how Black Ice can better serve your workflow. Submit feature requests through the [contact form](/contact) or discuss them in the Discord community.
## Documentation
You're already here! Browse the sidebar to explore guides, feature documentation, and integrations (MCP, the Workspace API, and GitHub Sync). Use **Ctrl+K** (or **⌘K** on Mac) to search across all articles.
---
# Security & data protection
> How Black Ice stores and isolates workspace data, our no-model-training commitment, retention, and how to request the DPA.
A summary of how Black Ice stores, isolates, and protects your data. The binding legal terms are in the [Privacy Policy](/privacy), [Terms](/terms), and [DPA](/legal/dpa).
## Where your data lives
Workspace data — concepts, terms, market definitions, relationships, custom fields — is stored in a managed PostgreSQL database with encryption in transit (TLS) and at rest. Uploaded approval images live in private object storage reachable only through short-lived signed URLs.
## Tenant isolation
Every table carrying workspace data is protected by row-level security. Queries are scoped to the workspace you belong to; there is no application path that returns another tenant's rows. API keys and MCP tokens are bound to a single workspace.
## AI and model training
**Your ontology data is never used to train Black Ice models or any third-party models.** When you use an AI feature, content is sent to the model provider only to produce that response and is not retained for training.
## Data you send outward
Two features deliberately move data outside Black Ice, and both are opt-in and under your control:
- **GitHub Sync** — writes the Markdown bundle to the repository *you* choose, using a token *you* issue. Use a private repo, and choose the region/organisation that fits your policy.
- **MCP and the Workspace API** — return data to the client you authorize. Revoke access at any time in Integrations.
## Retention and deletion
- Deleting a concept, term, or market removes it immediately.
- Deleting your account cascades into every workspace you own and removes you from workspaces you joined.
- Backups roll off on the platform's standard schedule; the DPA states the retention and deletion windows applied on termination.
## Access control
- Role-based access (owner, admin, editor, viewer) on Builder workspaces.
- Approval reviewers access a single, expiring share link and never see the rest of your workspace.
- Sign-in by password or one-time passcode; recovery links expire after 7 days.
## Requesting the DPA and security documentation
Paid workspaces can request a countersigned **Data Processing Agreement** including the Standard Contractual Clauses. Ask through the [contact form](/contact) or the address in your account settings, and see the [sub-processor list](/legal/sub-processors) and [security page](/legal/security) for the current details, including certification status and roadmap.
---
# Classes
> How Black Ice structures your product terminology as a connected ontology.
Classes are the foundation of your ontology. They define the *type* of thing each concept represents — giving structure, meaning, and governance rules to your terminology.
## What is a class?
A class is a category that groups related concepts. Think of classes as the taxonomy layer of your ontology:
- **Feature** — A specific capability or function in your product
- **Plan** — A pricing tier or subscription level
- **Platform** — A top-level product or ecosystem
- **Campaign** — A marketing initiative or promotional concept
Every concept belongs to exactly one class.
## Creating a class
Navigate to **Classes** in the sidebar and click **Add Class**.
| Field | Description |
|-------|-------------|
| **Name** | The class label (e.g., "Feature"). Used to generate concept ID prefixes. |
| **Description** | What this class represents. Helps team members understand when to use it. |
| **Color** | Visual identifier used throughout the UI and knowledge graph. |
| **Translation policy** | Sets the default localization rule: Prefer Adapt or Do Not Translate. Can be overridden per market. |
## Translation policies
Each class carries a translation policy that governs how its concepts should be handled during localization:
| Policy | Meaning |
|--------|---------|
| **Prefer Adapt** | Localize if a good equivalent exists; English fallback acceptable |
| **Do Not Translate** | Verbatim. No adaptation, no substitution |
The policy is applied at creation — a contributor adding a term to a class marked "Do Not Translate" gets the constraint before they type anything, not after a linguist catches it in QA.
## Market overrides
When reality is more nuanced, market-level overrides let you flip the policy for specific locales without changing the class default.
For example, a product name class might be "Do Not Translate" globally — but Japan and China need adapted forms. Instead of creating a separate class, you add market overrides:
```text
Class: "Plan"
Default: Do Not Translate
Override: ja-jp → Prefer Adapt
Override: zh-cn → Prefer Adapt
```
To manage overrides, open the **Overrides** dialog from the Classes table. Each row shows whether a market inherits the class default or has an explicit override. You can set or clear overrides per locale.
The design principle: **status describes intent, scope describes where.** Geography is never encoded in the policy name.
## Class-based concept IDs
When you create a concept, Black Ice auto-generates a unique ID based on the class name. For example, a concept in the "Feature" class might get the ID `feat_00000001`. This ensures IDs are:
- **Human-readable** — You can tell the class from the prefix
- **Unique** — Sequential numbering prevents collisions
- **Stable** — IDs never change, even if the concept name does
## Managing classes
You can edit a class's name, description, color, and translation policy at any time. Deleting a class requires removing all concepts in that class first.
> Classes are workspace-specific. Each workspace maintains its own set of classes independent of other workspaces.
---
# Concepts & IDs
> How concepts and auto-generated IDs work in Black Ice.
Concepts are the central building blocks of your ontology. Each concept represents a single unit of meaning — a product feature, a pricing plan, a platform element — independent of any specific language.
## What is a concept?
A concept is a language-neutral entity with:
- A **unique ID** (auto-generated from the class prefix)
- A **name** (the canonical English label)
- A **class** (the type of thing it represents)
- An optional **description**
- One or more **terms** in different locales
- **Market availability** tracking term readiness per locale
- **Semantic relationships** linking it to other concepts
## Auto-generated concept IDs
When you create a concept, Black Ice generates a unique ID based on the class:
```
feat_00000001 → First concept in the "Feature" class
plan_00000002 → Second concept in the "Plan" class
plat_00000001 → First concept in the "Platform" class
```
The prefix is derived from the first four characters of the class name. The number increments automatically and is padded to 8 digits.
**IDs are permanent.** Once assigned, a concept ID never changes — even if you rename the concept or change its class. This makes IDs safe to use as stable references in external systems.
## Creating a concept
Navigate to **Concepts** and click **Create Concept**:
1. Select a class
2. Enter a name
3. Add an optional description
4. Click **Create**
The concept is created with a source term matching the name you entered.
## Concept detail view
Opening a concept shows:
- **Basic info** — Name, class, description, concept ID
- **Source term** — The primary term in your source locale
- **Target terms** — Translations in other locales
- **Market availability** — Per-term readiness status across locales
- **Semantic relationships** — Connections to other concepts
- **Custom fields** — Any workspace-defined custom attributes
## Bulk operations
You can import concepts in bulk via CSV or Excel. See [CSV & Excel import](/docs/features/csv-and-excel-import) for details.
---
# Semantic relationships
> How semantic relationships connect concepts in your ontology.
Semantic relationships connect concepts to each other, transforming a flat list of terms into a structured, navigable ontology.
## What is a semantic relationship?
A semantic relationship is a typed link between two concepts. For example:
- "Creator Starter" **hasFeature** "MIDI Editor"
- "MIDI Editor" **isFeatureOf** "Creator Starter"
Relationships give your ontology structure and meaning — they express how concepts relate to each other in your product domain. Without relationships, concepts are isolated entries. With them, your data becomes a connected knowledge system that reflects real product architecture.
## Relationship types
Before creating relationships between concepts, you define **relationship types** at the workspace level. Navigate to **Relationships** in the sidebar to manage them.
Each relationship type has:
| Field | Description |
|-------|-------------|
| **Label** | The forward label (e.g., "hasFeature") |
| **Inverse label** | The reverse label shown from the target's perspective (e.g., "isFeatureOf") |
| **Value** | A machine-readable key used in exports (e.g., "hasfeature") |
| **Directionality** | Whether the relationship works in one or both directions |
| **Description** | What this relationship type represents |
### Common relationship types
| Label | Inverse | Use case |
|-------|---------|----------|
| `hasFeature` | `isFeatureOf` | A plan includes a feature |
| `hasPillar` | `isPillarOf` | A platform has a core domain |
| `hasPlan` | `isPartOfPlanGroup` | A plan group contains a pricing plan |
| `isRelatedTo` | `isRelatedTo` | General association between concepts |
| `requiresDisclaimer` | — | A concept requires a legal disclaimer |
| `dependsOn` | `isDependencyOf` | A feature depends on another |
## Bidirectional vs. unidirectional
This is one of the most important decisions when defining a relationship type.
### Bidirectional relationships
When a relationship is **bidirectional**, creating a link from A → B **automatically creates the inverse** from B → A. You don't need to create both manually.
For example, if you define a bidirectional type with label `hasFeature` and inverse label `isFeatureOf`:
- You link "Creator Starter" → "MIDI Editor" using `hasFeature`
- Black Ice automatically shows "MIDI Editor" → "Creator Starter" using `isFeatureOf`
Both links are visible in the Concept Detail view and the Knowledge Graph. The inverse relationship appears with a **bidirectional badge** so you can distinguish auto-created links from manually created ones.
### Unidirectional relationships
When a relationship is **unidirectional**, only the direction you explicitly create exists. Creating A → B does **not** create B → A.
Use unidirectional relationships when the reverse direction isn't meaningful — for example, `requiresDisclaimer` makes sense from concept to disclaimer, but not the other way around.
## Inverse labels
The **inverse label** defines how a relationship reads from the target concept's perspective. This is what makes your ontology readable from any entry point:
| From concept A | Label | From concept B | Inverse label |
|----------------|-------|----------------|---------------|
| "Pro Plan" | `hasFeature` | "Analytics" | `isFeatureOf` |
| "Platform" | `hasPillar` | "Music Creation" | `isPillarOf` |
When you view "Analytics" in the concept detail, you'll see the inverse: `isFeatureOf → Pro Plan`. This lets every team member navigate the ontology naturally, regardless of which concept they start from.
> **Tip:** For symmetric relationships like `isRelatedTo`, set the inverse label to the same value as the forward label.
## Creating relationships
1. Open a concept's detail view
2. Scroll to the **Semantic Relationships** section
3. Click **Add Relationship**
4. Select the relationship type from the dropdown
5. Search and select the target concept
6. Click **Create** — done
For bidirectional types, the inverse link is created automatically. You'll see it immediately on the target concept's detail page.
## Deleting relationships
Hover over any relationship row and click the delete icon. For bidirectional relationships, deleting the forward link also removes the auto-created inverse.
## Managing relationship types
Navigate to **Relationships** in the sidebar to view, create, edit, or delete relationship types.
> **Warning:** Deleting a relationship type removes **all relationships of that type** across your entire ontology. This action cannot be undone.
## How relationships power the Knowledge Graph
Every relationship you create becomes an edge in the [Knowledge Graph](/docs/features/knowledge-graph). The graph uses your relationship types as edge labels and your concept classes as node colors, giving you an interactive, visual map of your entire product ontology.
Relationships also appear in structured exports (JSON, CSV), making them available to downstream tools, AI prompts, and content systems.
---
# Knowledge graph
> Visualize your ontology with the interactive knowledge graph.
The Knowledge Graph is an interactive visualization of your entire ontology — concepts as nodes, relationships as edges — giving you a bird's-eye view of how your product domain fits together.
## Accessing the graph
Navigate to **Knowledge Graph** in the sidebar. The graph loads automatically with all concepts and relationships in your current workspace.
## Reading the graph
- **Nodes** represent concepts, colored by their class
- **Edges** represent semantic relationships, labeled with the relationship type
- **Node size** reflects the number of connections — concepts with more relationships appear larger
The graph uses an automatic **Dagre layout algorithm** that arranges nodes hierarchically, positioning related concepts near each other for readability.
## Interacting with the graph
| Action | Result |
|--------|--------|
| **Click a node** | Opens the concept detail panel |
| **Drag a node** | Repositions it in the graph |
| **Scroll wheel** | Zoom in/out |
| **Click and drag background** | Pan the view |
## One-Hop toggle
The **One-Hop** toggle (found in the graph toolbar) controls how deep the visualization goes:
- **Off** — Shows only direct (Level 1) connections from the selected concept
- **On** — Expands to show Level 2 connections — concepts connected to your direct connections
This is useful for exploring how concepts cluster. For example, selecting a Plan concept with One-Hop enabled shows not just its features, but also the features' own dependencies and related concepts.
## Filtering
Use the filter panel to focus on specific parts of your ontology:
- **By class** — Show only concepts of a specific class (e.g., only Features)
- **By relationship type** — Show only specific relationship types (e.g., only `hasFeature` links)
Filters are combinable — you can show only Feature concepts connected by `hasFeature` relationships, hiding everything else.
## Graph stats
The stats panel shows:
- Total concepts and relationships displayed
- Breakdown by class
- Most connected concepts
## Bidirectional relationships in the graph
Bidirectional relationships appear as edges with arrows in both directions. The forward label is shown on the edge; hovering reveals the inverse label. This reflects the auto-inverse logic — when you create a bidirectional relationship, both directions appear in the graph automatically.
## Tips for a useful graph
- **Define classes consistently** — classes determine node colors, so a clear class taxonomy makes the graph immediately readable
- **Use descriptive relationship labels** — edge labels should be scannable at a glance (`hasFeature` is better than `rel1`)
- **Start with filters** — large ontologies are easier to explore one class or relationship type at a time
- **Use One-Hop for discovery** — enable it to find unexpected connections between distant parts of your ontology
## Exporting the graph
Use the **Export** menu in the graph toolbar to save the current view as an image:
| Format | Notes |
|---|---|
| **PNG 1x** | Quick screenshot for chat or tickets |
| **PNG 2x** | Retina-quality image for slide decks |
| **PNG 4x** | Print-quality, large canvases |
| **SVG** | Vector — scale infinitely, edit in Figma or Illustrator |
| **PDF** | Vector document for reports and stakeholder reviews |
The export captures what is currently on screen, so apply your filters and layout first. SVG and PDF exports are available on **Pro and Builder**.
For exporting the underlying data rather than the picture — JSON, Markdown, CSV, PDF, or RDF/OWL as Turtle and JSON-LD — see [Export formats](/docs/features/export-formats).
---
# Custom fields
> Extend your ontology with custom metadata fields on concepts and terms.
Custom fields let you attach additional metadata to concepts and terms beyond the built-in attributes — without changing the underlying data model.
## Why custom fields?
Every team has domain-specific metadata that doesn't fit neatly into a generic ontology structure. Custom fields let you track things like:
- **Internal product codes** or SKU references
- **Launch dates** or deprecation dates
- **Compliance flags** (e.g., "requires legal review")
- **Priority scores** or lifecycle stages
- **External URLs** to specifications, Figma files, or Jira tickets
Instead of overloading the description field or maintaining a parallel spreadsheet, custom fields keep this data structured, searchable, and co-located with the concepts it belongs to.
## Field types
Custom fields support six data types:
| Type | Description | Example |
|------|-------------|---------|
| **Text** | Free-form string | `"PROD-4821"` |
| **Number** | Numeric value | `42` |
| **Date** | Calendar date | `2025-03-15` |
| **Boolean** | True/false toggle | `true` |
| **Select** | Dropdown with predefined options | `"In Review"` |
| **URL** | Clickable link | `https://figma.com/file/...` |
## Applies to: concepts or terms
Each custom field definition specifies whether it applies to **concepts** or **terms**:
- **Concept-level fields** appear in the Concept Detail view, directly after the Class selector. Use these for metadata that applies to the concept as a whole (e.g., internal ID, launch date, compliance status).
- **Term-level fields** appear inline within source and target term forms. Use these for metadata specific to a particular translation or locale (e.g., character count limit, reviewer name).
## Scoping by class
You can optionally restrict a custom field to a specific **class**. For example:
- A `"Launch Date"` field that only appears on concepts with class **Plan**
- A `"Compliance Flag"` field that only appears on **Feature** concepts
If no class is selected, the field appears on all concepts (or all terms, depending on the applies-to setting).
## Creating custom fields
1. Navigate to the **Concepts** dashboard
2. Open the **Actions** dropdown in the toolbar
3. Click **Custom Fields**
4. Click **Add Field**
5. Configure the field:
- **Name** — a descriptive label (e.g., "Internal SKU")
- **Type** — choose from Text, Number, Date, Boolean, Select, or URL
- **Applies to** — Concept or Term
- **Class restriction** — optionally limit to a specific class
- **Required** — whether the field must be filled in
- **Options** — for Select fields, define the dropdown choices
6. Click **Save**
The field immediately appears on all matching concepts or terms.
## Editing and deleting fields
From the Custom Fields manager:
- **Edit** a field to change its name, type, or options. Existing values are preserved where compatible.
- **Delete** a field to remove it and all its stored values permanently.
> **Warning:** Deleting a custom field removes all saved values across every concept or term. This cannot be undone.
## Custom fields during concept creation
Custom fields work during concept creation too. When you create a new concept, any applicable custom fields appear inline in the form. Values are buffered locally and saved automatically once the concept is created.
## Display order
Fields appear in the order you define them. You can adjust the display order from the Custom Fields manager to control how fields are presented in the concept and term forms.
## Custom fields in exports
Custom field values are included in structured exports (JSON, CSV), making them available to downstream tools, content systems, and AI workflows. Each field appears as a named column or property in the export output.
---
# Source & target terms
> How to manage multilingual terms, culture guidelines, and approval workflows.
Every concept in Black Ice has one or more **terms** — the actual words used in specific languages and markets. Terms are the human-facing layer of your ontology.
## Source vs. target terms
**Source term** — The canonical term in your workspace's source locale (typically English). This is the reference that all translations are based on. Each concept has exactly one source term.
**Target term** — A translation of the concept in another locale. Each concept can have multiple target terms, one per locale.
## Term fields
| Field | Description |
|-------|-------------|
| **Preferred term** | The approved translation (e.g., "Editor MIDI" in French) |
| **Allowed variants** | Acceptable alternatives (e.g., "Éditeur MIDI") |
| **Forbidden variants** | Explicitly blocked alternatives (e.g., "MIDI Éditeur") |
| **Usage context (start)** | How the term appears at the start of a sentence (target terms only) |
| **Usage context (mid)** | How the term appears mid-sentence (target terms only) |
| **Notes** | Internal notes for translators or reviewers |
| **Status** | Approval status: Pending, Approved, or Rejected |
| **Market availability** | Whether this term is available, restricted, or unavailable in specific markets |
## Variants
Variants provide governance beyond the preferred term:
- **Allowed variants** are acceptable alternatives that won't trigger errors in quality checks
- **Forbidden variants** are explicitly wrong — useful for catching common mistranslations or outdated terms
## Status workflow
Terms follow a simple status workflow:
1. **Pending** — Newly created, awaiting review
2. **Approved** — Reviewed and accepted by a stakeholder
3. **Rejected** — Reviewed and declined, with comments explaining why
Status can be changed manually or through the [approval workflow](/docs/features/approval-workflows).
## Adding terms
Open any concept and scroll to the **Terms** section:
1. The source term is pre-filled from the concept name
2. Click **Add Target Term** to create a translation
3. Select the target locale
4. Fill in the preferred term and any variants
5. Save — the term is created with "Pending" status by default
---
# Batch availability updates
> Update availability across many concepts at once.
Manually toggling availability one concept at a time is fine for small ontologies — but when you launch a new market or roll out a feature, you need bulk operations.
## How it works
1. Open **Concepts**.
2. Tick the checkbox on the row(s) you want to update — or use the header checkbox to select the visible page.
3. A floating **Action bar** appears at the bottom of the screen.
4. Choose what to update:
- **Source availability** — `available`, `not_set`, or `unavailable`
- **Target availability** — applied to one specific market or to all markets at once
5. Confirm. Updates are atomic — either the whole batch succeeds or nothing changes.
## Filtering before selecting
Combine bulk select with the **Filters** popover:
- Filter by class to update only "Plan" concepts
- Filter by availability to flip everything currently `not_set` to `available`
- Filter by market to focus on one rollout region
## What gets logged
Every batch update is recorded in the [Activity log](/docs/features/activity-log) per concept, so the audit trail stays granular.
## Tips
- Use **Market Inspection Mode** (toolbar) to see availability per market in a wide table before bulk-editing.
- Pair this with **Approval workflows** to send the freshly-flipped terms to your regional reviewers in a single batch.
---
# Market availability
> Track term-level readiness across locales with availability statuses.
Market availability lets you control the readiness status of each term — both source and target — across your locales. This helps teams track which terms are live, planned, or blocked in each market.
## How it works
Market availability is set **per term**, not per concept. Every source term and target term has its own availability status. This gives you granular control: a concept's source term might be "Available" in English, while its Spanish translation is still "Planned".
## Availability statuses
| Status | Meaning |
|--------|---------|
| **Not Set** | Default — no availability decision has been made yet |
| **Available** | Live in market — this term is approved and in use |
| **Planned** | Coming later — the term exists but isn't live yet |
| **Unapproved** | The term exists but hasn't passed governance review |
| **Not Available** | Not planned for this market |
## Setting availability
When creating or editing a concept:
1. In the **Source Term** card, find the **Market Availability** dropdown
2. Select the appropriate status
3. For each **Target Term**, set its availability independently
4. Save the concept
Each term card — source and target — has its own Market Availability selector, so you can track readiness per locale.
## Comparing source and target availability
On the **Concept Detail** page, availability badges appear next to each term. This makes it easy to spot mismatches — for example, a source term marked "Available" while a target term is still "Planned" or "Not Set".
## Batch updates
You can update market availability for multiple terms at once from the **Concepts** table. Select concepts and use the batch action toolbar to apply a status across all source or all target terms.
## Common patterns
**Staged rollout** — Set the source term to "Available" and target terms to "Planned" until translations are reviewed and approved.
**Governance hold** — Mark a target term as "Unapproved" when it exists but hasn't passed legal or brand review for that locale.
**Deprecation** — Set a term to "Not Available" when it's being retired from a specific market.
---
# Locales & markets
> Managing locales, source markets, and brand identity per region.
Locales define the languages and regions your terminology covers. Each locale can have detailed market definitions that guide how content should sound in that market.
## What is a locale?
A locale is a language-region combination identified by a code like `en-us`, `es-es`, or `ar-sa`. Each locale has:
| Field | Description |
|-------|-------------|
| **Code** | Standard locale code (e.g., `de-de`) |
| **Name** | Display name in English (e.g., "German (Germany)") |
| **Native name** | Display name in the locale's own language (e.g., "Deutsch") |
| **Direction** | Text direction — LTR (left-to-right) or RTL (right-to-left) |
| **Status** | Active or inactive |
## Adding locales
Navigate to **Markets** in the sidebar and click **Add Locale**. Select from the predefined list or create a custom locale code.
Your workspace's **source locale** is set in workspace settings and determines which terms are treated as source terms. The source locale is visually distinguished by a badge and cannot be deleted.
## Source market
One locale per workspace is designated as the **source market**. This is your primary locale (typically English US) and holds your canonical brand identity — name, tagline, and positioning statement. All other locales are considered target markets.
## Brand identity per locale
Each locale can have its own brand identity fields:
- **Brand name** — may remain the same or be adapted for the market
- **Brand tagline** — localized or retained from the source
- **Brand positioning** — market-specific positioning statement
These fields appear in the locale detail view and are included in exports.
## Market definitions
Each locale can have detailed **market definitions** — structured guidelines covering voice, tone, grammar, cultural conventions, and more. These definitions are what make your ontology actionable for translators and AI agents.
→ See [Market definitions](/docs/features/market-definitions) for a full guide on the ten sections and best practices.
---
# Market definitions
> Define voice, tone, grammar, and cultural conventions for each locale.
## What are market definitions?
Market definitions are structured guidelines attached to each locale that describe **how** content should sound in that market. They go beyond translation rules to capture voice, cultural expectations, and brand conventions specific to a region.
When you open a locale in the **Markets** page and expand the **Market Definitions** panel, you'll find ten structured sections — each designed to give translators, copywriters, and AI tools the context they need to produce content that fits the market.
## The ten sections
| Section | What it captures |
|---------|-----------------|
| **Market Snapshot** | Competitive landscape, audience segments, and market expectations |
| **Voice & Locale DNA** | Core personality traits, brand keywords, and anti-patterns for this market |
| **Tone & Style Rules** | Sentence structure, active/passive voice, formality level, and preferred patterns |
| **Culture & Pragmatics** | Implicit cultural expectations, communication norms, and sensitivity areas |
| **Grammar & Mechanics** | Spelling conventions, contractions, sentence length, and punctuation rules |
| **UX Microcopy Rules** | CTA patterns, system message tone, error handling, and UI label conventions |
| **Locale Conventions** | Currency format, date/time format, number separators, and pricing psychology |
| **Terminology Rules** | Preferred and avoided terms specific to this market |
| **Golden Examples** | Reference copy — headlines, subheadings, feature descriptions — that exemplify the right tone |
| **Output Constraints** | Hard rules: never claim X, always include Y, mandatory disclaimers |
Each section is a free-form text field. You can write as little or as much as needed — from a single line to detailed multi-paragraph guidance.
## Editing market definitions
1. Navigate to **Markets** in the sidebar
2. Click the **detail icon** on any locale row
3. Scroll to the **Market Definitions** panel
4. Expand any section and enter your guidelines
5. Click **Save** — changes are stored immediately
> Market definitions are workspace-scoped. Each workspace maintains independent definitions per locale.
## Import and export definitions as Markdown
The Market Definitions panel works with Markdown files, so you can draft definitions outside the app and load them in — or take them with you.
- **Download** — export the current locale's definitions as a single `.md` file with one heading per section.
- **Upload** — drop in a `.md` or `.txt` file. Black Ice parses the section headings and fills the matching fields; anything it cannot match is left untouched so nothing is silently lost.
- **Template** — if a locale has no definitions yet, start from the built-in template so your headings match the parser.
This makes it easy to keep market definitions under review in a repo, hand them to an agency for drafting, or clone one market's structure into another.
> Uploading replaces the content of the sections present in the file. Review the preview before saving.
## Source market vs. target markets
Your workspace has one designated **source market** (typically your primary locale, e.g., English US). The source market's definitions capture your canonical brand voice — the baseline that target markets adapt from.
Target market definitions describe how to **adapt** that voice for each region. For example:
- **Source (en-US)**: Casual, direct, uses contractions, second-person address
- **Target (de-DE)**: Formal register, no contractions, third-person where culturally expected
- **Target (ja-JP)**: Polite form (です/ます), indirect phrasing, honorific conventions
## How market definitions power AI agents
When you sync your ontology to GitHub via **GitHub Sync**, market definitions are exported as structured Markdown files in the `markets/` directory — one file per locale.
AI agents (Claude Code, Cursor, custom pipelines) read these files to understand **how** to write for each market. Instead of guessing tone and style, the agent follows your explicit guidelines:
```
ontology/
├── markets/
│ ├── en-US.md ← Source voice: casual, direct
│ ├── de-DE.md ← Formal register, legal disclaimers
│ └── pt-BR.md ← Warm, conversational, adapted brand terms
```
This means every AI-generated translation or adaptation follows the same rules your human translators would — without re-briefing.
## Best practices
- **Start with Voice & Locale DNA** — This is the most impactful section. Define personality traits, keywords to use, and patterns to avoid.
- **Add Golden Examples early** — Concrete examples are more useful than abstract rules. Show what good copy looks like in each market.
- **Keep Output Constraints tight** — Use this for non-negotiable rules (legal requirements, brand mandates) that must never be violated.
- **Review quarterly** — Markets evolve. Revisit definitions as your product, audience, or regulatory landscape changes.
- **Don't duplicate terminology rules** — Term-level governance (preferred/allowed/forbidden variants) belongs in concept terms, not in market definitions. Use the Terminology Rules section for market-wide patterns only.
---
# Brand identity per market
> Localize your brand name, tagline, and positioning per locale.
Brand identity in Black Ice has two layers:
1. **Workspace-level brand** — your default brand name, tagline, and positioning
2. **Per-market overrides** — localized brand expression for each locale
## Setting the workspace default
In **Settings → Workspace**, fill in:
- **Brand name** — the canonical name (often kept verbatim)
- **Brand tagline** — short positioning line shown in marketing
- **Brand positioning** — a paragraph capturing the value proposition
These default values feed every market unless overridden.
## Per-locale overrides
Open **Markets**, click a market row, and the details dialog includes a **Brand identity** section. Enter the localized values:
- A localized brand name (only when policy allows — e.g. transliteration into Japanese)
- A locale-appropriate tagline (e.g. shorter for German, warmer for Brazilian Portuguese)
- A positioning paragraph reflecting cultural pragmatics
Empty fields fall back to the workspace default.
## Why this matters
The exported ontology bundle includes brand identity per market. AI assistants generating marketing copy use this — together with **Culture DNA** — to produce on-brand output without you re-prompting per region.
## Related
- [Locales & markets](/docs/features/locales-and-culture-dna)
- [Market definitions](/docs/features/market-definitions)
---
# Reference markets
> Mark a market as a reference language you use internally but don't ship products in.
A reference market is your **source market** when it serves only as a working language for your team — not a market you ship products in. It exists to solve a specific, common problem in terminology management.
## The problem
When your working language is also your source market but you don't ship products in that language, every source term reads **Not Available**. That's misleading — "not available" is a shipping decision, and here there's no decision to make. Worse, a column full of "Not Available" drags your coverage percentage down even though nothing is wrong.
The typical case is a team that works in English (English is the source market and the canonical language for concept names) but ships products only into Spanish, Polish, and other markets — there are no English products for end users.
## What a reference market changes
When you mark your source market as a reference market:
- The Concepts table shows **Reference** in the source availability column. There is no status to set per term.
- This applies automatically to **every** concept, including new ones you add later — you never need to mark new terms.
- The market is excluded from **coverage calculations**, so it no longer lowers your coverage percentage.
- The source **availability filter** and the **source/target mismatch view** are hidden, since there is nothing to compare.
- In bulk availability updates, the "apply to source" checkbox is hidden.
- The Markets table shows a **REFERENCE** badge next to the market.
## How to enable it
1. Go to **Settings → Markets**.
2. Find your **source market** (it carries the SOURCE badge) and click **Edit**.
3. Toggle **Reference market** on.
4. Save.
This is a one-time setting. Toggling it off restores normal availability tracking.
## Why source market only
The setting only appears when editing the source market, because that is the only place it means something. Source terms are canonical concept names — the anchor everything else is translated from — so asking whether they are "available" in a market you don't sell in is a category error.
Target markets are different: those are real shipping markets, and availability there is a genuine decision you want recorded per term. If your source market changes, the reference designation is cleared from the old source automatically.
## When to use it
Use it when your source language is a working language you don't ship products in.
Don't use it for a market you *do* ship in where a specific concept simply won't appear — that's a per-term availability decision, tracked at the term level.
---
# Workspaces
> How to collaborate with your team using workspaces, roles, and activity tracking.
Workspaces are isolated environments that contain your entire ontology — concepts, terms, relationships, classes, locales, and team members.
## What is a workspace?
A workspace is the top-level container for everything in Black Ice. When you sign up, a workspace is automatically created for you. All your data lives within this workspace, and team members you invite share access to the same ontology.
## Workspace settings
Each workspace has configurable settings:
| Setting | Description |
|---------|-------------|
| **Name** | The workspace display name |
| **Source locale** | The primary language for your source terms (default: English US) |
| **Brand name** | Your product or company name |
| **Brand tagline** | A short brand description |
| **Brand positioning** | Positioning statement used for context in translations |
## Workspace limits by plan
| | **Free** | **Pro** | **Builder** |
|---|---|---|---|
| Workspaces | 1 | 1 | Up to 3 |
| Concepts | 50 | 350 | Unlimited |
| Markets | 3 | 20 | Unlimited |
| Team members | — | — | 10 |
## Creating additional workspaces
Builder plan users can create up to 3 workspaces. Navigate to the workspace selector in the sidebar and click **Create Workspace**.
Each workspace is fully independent — concepts, classes, locales, and team members are not shared between workspaces.
## Archiving and deleting
- **Archive** — Temporarily hides a workspace from the selector. Data is preserved.
- **Clear data** — Removes all ontology data (concepts, terms, relationships) while keeping the workspace shell.
- **Delete** — Permanently removes the workspace and all its data. This cannot be undone.
---
# Team management
> Invite team members and manage roles and permissions.
Black Ice supports collaborative terminology management with role-based access control. Invite team members and control what each person can do.
## Roles
Black Ice has four roles, from most to least permissive:
| Role | Capabilities |
|------|-------------|
| **Owner** | Full control — manage workspace settings, billing, team members, and all data |
| **Admin** | Manage team members, create/edit/delete all ontology data |
| **Editor** | Create and edit concepts, terms, relationships, and classes |
| **Viewer** | Read-only access to all ontology data — cannot create, edit, or delete anything |
## Inviting team members
1. Navigate to **Settings → Team Management**
2. Click **Invite Member**
3. Enter the person's email and select a role
4. Click **Send Invite**
The invitee receives a branded email with a link to accept the invitation. If they don't have a Black Ice account, they'll be prompted to create one first.
## Invitation lifecycle
- Invitations include a secure token and expiry date
- Pending invitations can be re-sent if the original email wasn't received
- Once accepted, the team member appears in the workspace with their assigned role
- Re-inviting an email address cancels any previous pending invitation
## Changing roles
Owners and Admins can change a team member's role at any time from the Team Management settings.
## Removing members
Owners and Admins can remove team members. Removing a member revokes their access immediately — their data contributions (concepts, terms) remain in the workspace.
## Viewer restrictions
Viewers see a **View Only** banner on restricted pages. All create, edit, and delete actions are hidden from the UI. Direct URL access to protected routes (like create or import pages) redirects viewers back to the concepts list.
## Plan limits
Team management is available on the **Builder** plan, which supports up to 10 team members per workspace.
---
# Approval workflows
> Send terms for external review with shareable approval links.
Approval workflows let you send terms for review to stakeholders — legal teams, brand managers, regional experts — without requiring them to have a Black Ice account.
## How it works
1. **Select terms** — Choose one or more terms that need review
2. **Create a request** — Add the reviewer's email, an optional message, and any supporting images
3. **Share the link** — The reviewer receives a unique, time-limited link
4. **Review inline** — The reviewer sees a guided presentation of each term and can approve or reject with comments
5. **Track decisions** — All decisions are recorded with timestamps in the approval history
## Creating an approval request
From any concept's detail view:
1. Click **Send for Approval**
2. Select the terms to include
3. Enter the reviewer's email address
4. Add an optional message explaining context
5. Optionally attach images (mockups, screenshots, brand guidelines)
6. Click **Send**
## The reviewer experience
Reviewers don't need an account. They click the link and see a step-by-step presentation:
1. **Welcome slide** — Context about what they're reviewing
2. **Identity verification** — Name, email, and role (if required by your settings)
3. **Concept overview** — The concept being reviewed with its description and class
4. **Term details** — Each term with preferred translation, variants, and context
5. **Visual context** — Any attached images
6. **Related concepts** — Semantic relationships for additional context
7. **Decision form** — Approve or reject each term with optional comments
## Approval settings
Configure approval behavior in **Settings → Permissions**:
| Setting | Description |
|---------|-------------|
| **Require approver identity** | Reviewers must provide name, email, and role |
| **Require role match** | Only specified roles can approve |
| **Allowed approver roles** | Which roles are permitted to review |
| **Default link expiry** | How long approval links remain valid (default: 30 days) |
| **Hide internal notes** | Don't show term notes to external reviewers |
| **Hide market availability** | Don't show market constraints to reviewers |
| **Hide variant lists** | Don't show allowed/forbidden variants to reviewers |
## Approval history
Navigate to **Approval History** to see all past and pending requests, including who reviewed what, when, and their comments.
---
# CSV & Excel import
> Import terminology from CSV or Excel files with column mapping and conflict resolution.
Import existing terminology into Black Ice from CSV or Excel files. The importer handles column mapping, duplicate detection, and conflict resolution.
## Supported formats
- **CSV** (.csv) — Comma-separated values
- **Excel** (.xlsx) — Microsoft Excel workbooks (first sheet is used)
## Import process
1. Navigate to **Import** in the sidebar
2. Upload your file
3. **Map columns** — Match your file's columns to Black Ice fields (concept name, class, locale, preferred term, etc.)
4. **Preview** — Review the parsed data before importing
5. **Resolve conflicts** — If concepts already exist, choose to skip, overwrite, or merge
6. Click **Import**
## Column mapping
The importer auto-detects common column names but lets you manually map any column:
| Black Ice field | Common CSV headers |
|----------------|-------------------|
| Concept name | name, concept, term |
| Class | class, category, type |
| Description | description, notes, definition |
| Locale | locale, language, lang |
| Preferred term | translation, target, preferred_term |
| Allowed variants | variants, alternatives, allowed |
| Forbidden variants | forbidden, blocked, do_not_use |
## Conflict resolution
When an imported concept matches an existing one (by name or ID):
- **Skip** — Keep the existing concept, ignore the import row
- **Overwrite** — Replace the existing concept with the imported data
- **Merge** — Add new terms and relationships without modifying existing ones
## Tips
- **Include a header row** — The first row should contain column names
- **One row per term** — Each row represents one term in one locale for one concept
- **Use consistent locale codes** — Match the codes defined in your workspace (e.g., `en-us`, `es-es`)
---
# Export formats
> Export your ontology as JSON, Markdown, CSV, PDF, AI Agent Bundle, or RDF/OWL (Turtle and JSON-LD) — and when to use each.
Export your ontology in multiple formats, each optimized for different tools and workflows.
## JSON
Structured data export for programmatic use and AI tool configuration.
**What's included:**
- All concepts with their classes and descriptions
- All terms with variants, status, and market availability
- Semantic relationships between concepts
- Market definitions and constraints
**Best for:** MCP tool configuration, API integration, TMS import, programmatic access.
## Markdown
Human-readable export with clear headings, tables, and structured prose.
**What's included:**
- Concepts organized by class with descriptions
- Terms per locale with preferred term, variants, and status
- Market availability overview
- Relationship summaries
**Best for:** LLM prompts, Gemini, Custom GPTs, internal documentation, knowledge sharing.
## CSV
Flat tabular data with configurable columns and two layout options.
**Layout options:**
- **Translation Grid** — Wide format with one row per concept and markets as columns. Best for spreadsheet review and side-by-side comparison across locales.
- **Detailed Rows** — Long format with one row per target term. Best for translation management and per-term filtering.
You can configure exactly which columns to include and in what order using the CSV column configurator.
**Best for:** Spreadsheets, translators, bulk editing, data review.
## AI Agent Bundle (ZIP)
A structured folder of Markdown files with a top-level `CLAUDE.md` entry point, optimized for AI coding agents.
**What's included:**
- `CLAUDE.md` — Agent entry point with ontology overview and navigation instructions
- Per-class folders with concept definitions
- Per-locale term files with variants and usage context
- Market definitions and relationship data
The AI Agent Bundle is designed for the **GitHub Sync → Claude Projects** workflow: sync your ontology to a GitHub repo, then attach it as a Claude Project for context-aware AI assistance.
**Best for:** Claude Projects, Claude Code, AI coding agents, developer workflows.
## RDF/OWL — Turtle and JSON-LD
Standards-based semantic web exports built on **SKOS-XL + OWL**, for graph databases, ontology tooling, and linked-data publishing.
Both files describe **exactly the same graph** — the same concept IRIs, the same labels, the same predicates. The only difference is serialization, so pick whichever your consuming tool reads most naturally.
### Turtle (`.ttl`)
Compact, human-readable RDF. The default interchange format for the semantic web stack.
**Choose Turtle when:**
- You are loading into a triple store or graph database — GraphDB, Stardog, Neo4j (via n10s), Apache Jena, Virtuoso
- You will query the data with SPARQL
- You are opening the ontology in an editor such as Protégé or TopBraid
- A reviewer needs to read the raw model by eye — Turtle is by far the most legible RDF syntax
### JSON-LD (`.jsonld`)
The same RDF expressed as JSON, with a `@context` that maps the short keys onto the full vocabulary.
**Choose JSON-LD when:**
- The consumer is a web or JavaScript pipeline that already parses JSON
- You are storing the graph in a document database, search index, or vector store alongside other JSON
- You need structured data for the web, or a procurement/tender checklist asks for a machine-readable linked-data format
- Your team is comfortable with JSON but not with RDF syntax — JSON-LD degrades gracefully to plain JSON
### What's included in both
Concepts as `skos:Concept`, source and target terms as `skosxl:Label` per locale, classes as `skos:ConceptScheme`, and semantic relationships as typed `owl:ObjectProperty` predicates. Black Ice-specific predicates (market, status, availability, allowed and forbidden variants, translation policy) live under the published namespace `https://black-ice.ai/ns#`, which is dereferenceable at `/black-ice-ns.ttl`.
Predicate names are frozen for the lifetime of schema version `1.0`, so downstream consumers can safely pin to the namespace.
**Best for:** GraphDB, Neo4j (via n10s), Stardog, Protégé, SPARQL pipelines, RAG grounding, public-sector and linked-data publishing.
> RDF/OWL exports are available on **Pro and Builder**.
## PDF
Prose document with formatted headings, tables, and structured content for document-based AI tools.
**What's included:**
- Full ontology overview with concepts organized by class
- Term tables per locale
- Market availability summaries
- Relationship descriptions
**Best for:** NotebookLM & document-based AI.
## Knowledge graph images (PNG, SVG, PDF)
Separate from the data exports above, the **Knowledge Graph** view exports the visual graph itself from its own export menu.
- **PNG** — standard, retina (2×) and print (4×) resolutions
- **SVG** — vector, scales to any size and stays editable in design tools
- **PDF** — vector page, ready to drop into a document
Retina PNG, print PNG, SVG and PDF are available on **Pro and Builder**; standard PNG is available on every plan.
**Best for:** Slides, board decks, architecture documentation, onboarding material, client presentations.
## JSON Schema
The export dialog also offers the **JSON Schema** that describes the JSON export — copy it to the clipboard or download it as a file.
**Best for:** Validating exported files in a pipeline, generating typed clients, and documenting the contract for engineering teams.
---
## Where each format comes from
| Surface | Formats produced |
|---|---|
| **Export Ontology dialog** (in app) | JSON, Markdown, CSV, AI Agent Bundle, PDF, Turtle, JSON-LD, JSON Schema |
| **Knowledge Graph view** (in app) | PNG, SVG, PDF images of the graph |
| **GitHub Sync** | AI Agent Bundle — Markdown files written into your repository |
| **Workspace API and MCP** | JSON responses from `GET /query-ontology` and the MCP read tools |
RDF/OWL, PDF and graph images are produced in the app rather than through the API. If you need them on a schedule, export from the app and commit the file, or sync the Markdown bundle to GitHub and convert downstream.
---
## Which format should I use?
Use this table to find the right format for your tool or workflow:
| Tool / Workflow | Recommended Format |
|---|---|
| **Gemini** | Markdown |
| **Custom GPTs** | Markdown |
| **Claude Projects** | AI Agent Bundle (ZIP) |
| **Claude Code** | AI Agent Bundle (ZIP) |
| **NotebookLM** | PDF |
| **MCP tools** | JSON |
| **Spreadsheet review** | CSV (Translation Grid) |
| **Translation management** | CSV (Detailed Rows) |
| **API / TMS integration** | JSON |
| **Internal documentation** | Markdown or PDF |
| **Graph databases / triple stores** | Turtle |
| **SPARQL queries** | Turtle |
| **Ontology editors (Protégé, TopBraid)** | Turtle |
| **Web / JavaScript linked-data pipelines** | JSON-LD |
| **Public-sector tenders and RFPs** | JSON-LD (or Turtle, if specified) |
| **RAG grounding for LLMs** | JSON-LD or Turtle |
| **Slides and presentations** | Knowledge graph PNG or SVG |
| **Validating exports in CI** | JSON Schema |
> **Tip:** If you're using GitHub Sync, the AI Agent Bundle format is automatically optimized for your synced repository structure — making it ideal for Claude Projects and AI-assisted development.
---
# Restoring an ontology from a bundle
> Rebuild a workspace from an exported ZIP bundle or from the GitHub repository that GitHub Sync writes to.
Beyond CSV and Excel, Black Ice can rebuild a workspace from a previously exported **AI Agent Bundle (ZIP)** or from a **GitHub repository** that GitHub Sync wrote to. This is the fastest way to move an ontology between workspaces or recover after a bad bulk edit.
## Restoring from a ZIP bundle
1. Export the source workspace with **Export → AI Agent Bundle (ZIP)** and keep the file.
2. In the destination workspace, go to **Concepts → Import**.
3. Upload the `.zip` — Black Ice reads the Markdown files inside (classes, concepts, terms, market definitions, relationships) instead of asking for column mapping.
4. Review the preview and resolve conflicts (skip, overwrite, merge) exactly as with a CSV import.
## Restoring from a GitHub repo
If the workspace uses GitHub Sync, the repo already holds the full bundle. In **Integrations → GitHub**, use **Import from repository** to pull the current contents of the configured repo, branch, and path back into the workspace.
This makes the repo a genuine backup: sync writes to it, import reads from it.
## What comes back
| Restored | Not restored |
|---|---|
| Classes and their colours/policies | Activity log history |
| Concepts, IDs, and descriptions | Approval request history |
| Source and target terms with variants and availability | API keys and GitHub tokens |
| Market definitions per locale | Team members and roles |
| Relationship types and relationships | Custom field values not present in the bundle |
## Good practice
- Restore into an **empty workspace** when migrating, to avoid conflict resolution entirely.
- Export a ZIP before any large bulk operation (batch availability changes, mass deletes).
- If you are on Builder, enable **auto-sync** so the repo is always a current backup.
> Concept IDs are preserved by the bundle, so relationships and downstream references keep working after a restore.
---
# Activity log
> Audit trail of every change made in your workspace.
The Activity Log records every successful in-app change so you can see who did what, when, and to which entity.
## What gets logged
- **Concepts** — created, updated, deleted
- **Terms** — created, updated, deleted (source and target)
- **Classes** — created, updated, deleted
- **Relationships** — created, updated, deleted
- **Markets** — created, updated, deleted
- **Workspace events** — bulk imports, data clears, ownership transfers
External actions (approval link clicks, GitHub pushes, exports) are tracked separately.
## Where to find it
Open **Activity** from the sidebar. Logs are grouped by day, sorted newest-first, paginated 30 per page.
## Filtering
Use the toolbar to filter by:
- **Action type** — create, update, delete
- **Entity type** — concept, term, class, market, relationship
- **User** — see only changes from a specific teammate
## Retention
Activity logs are retained for **90 days** then automatically purged. Export or sync to GitHub if you need a longer audit trail.
## Permissions
Every workspace member (any role) can view the activity log for workspaces they belong to. Logs are isolated by workspace.
---
# Notifications & alerts
> Customize what you get notified about and when.
Black Ice surfaces in-app notifications for ontology changes, approval activity, and expiring links. You control everything from **Settings → Alert Preferences**.
## In-app notifications
Toggle each event independently:
- **Concept created / updated / deleted**
- **Term created / updated**
- **Class changes**
- **Relationship changes**
The bell icon in the header shows unread notifications and links to the source entity.
## Approval activity
- **Approval decisions** — get notified when a reviewer approves or rejects a term
- **All terms reviewed** — single summary when an approval request is complete
- **Expiring links** — heads-up before an approval link goes stale
## Quiet hours
Suppress all in-app notifications during a daily window (e.g. 22:00–08:00). Bundles still queue silently and reappear after the window ends.
## Email digests *(Pro / Builder)*
- **Daily digest** — one summary email per day instead of per-event noise
- **Approval activity** — email each time a reviewer makes a decision
Tier-restricted toggles are visibly grayed out on Free with an upgrade hint.
## Bundle similar notifications
Collapse multiple updates to the same entity into one entry (e.g. ten edits to one concept become a single "updated 10 times" item).
---
# Permissions & data visibility
> Control who can approve and what reviewers see.
The **Permissions** panel in Settings (Pro / Builder) gives you fine-grained control over the approval workflow and the data exposed to external reviewers.
## Approval workflow rules
- **Require approver identity** — reviewers must enter name, email, and role before deciding (default: on)
- **Allowed approver roles** — restrict approvals to a whitelist (e.g. only "Legal", "Brand")
- **Auto-approve roles** — terms submitted by trusted internal roles bypass review
- **Require role match** — only users whose role matches the approver requirement can decide
- **Default link expiry** — how long approval links remain valid (default: 30 days)
## Data visibility on approval pages
Hide sensitive fields from external reviewers without altering the underlying data:
- **Hide internal notes** — strip notes from the term detail slide
- **Hide market availability** — omit availability badges
- **Hide variant lists** — drop allowed/forbidden variant arrays
These settings apply to every approval link you generate. Existing live links respect the setting at request time.
## Permissions vs. team roles
Permissions in this panel govern the **external approval flow**. To restrict who can edit data **inside** the app, see [Team management](/docs/features/team-management).
---
# Account & security
> Manage your sign-in, password, and account deletion.
The **Account** section in Settings is where you manage identity and security.
## Email
Your email is set at signup and visible (read-only) in Settings. To change it, contact support — email changes require re-verification.
## Password
Click **Change Password** to set a new one. You will be asked for your current password and the new password twice. The new password takes effect immediately and existing sessions stay valid.
## Sign in with a one-time passcode
You don't need your password to sign in. On the sign-in screen, choose **Email me a code**:
1. Enter your email and request the code.
2. Black Ice emails you a numeric passcode.
3. Enter it in the code field and you're signed straight into your dashboard.
Codes are single-use and short-lived. If the code doesn't arrive, check spam, then request a new one — requesting a new code invalidates the previous one.
## Forgot password
From the sign-in screen, click **Forgot password?** to receive a recovery link. Recovery links expire after **7 days**.
## Remember me
When signing in, the **Remember me** checkbox persists your session across browser restarts. Without it, the session ends when you close the tab.
## Delete account
From Settings → Account → **Delete Account**, you can permanently remove your account. This:
- Cascades into all workspaces you own (concepts, terms, markets, classes, custom fields, GitHub configs, approval requests)
- Removes you as a member from any workspaces you joined
- Frees up your email so it can be re-used to sign up again
You will be asked to confirm by typing your email. The action is irreversible.
## Sign-in providers
Email + password and email one-time passcodes are supported today. SSO and additional providers are on the roadmap for Builder.
→ See also: [Security & data protection](/docs/getting-started/security-and-data-protection)
---
# Translation policy
> Decide what gets translated, what stays in English, and how to override per market.
Every class has a **default translation policy** that tells your team (and AI tools) how to handle terminology in target locales.
## The two policies
- **Prefer Adapt** — translators should produce a localized version (default for editorial/marketing terms)
- **Do Not Translate** — keep the source term verbatim (typical for product names, plan names, brand IP)
Policies are part of the structured ontology export, so AI assistants and TMS pipelines can apply them automatically.
## Setting the default at the class level
When you create or edit a class, choose its policy. All concepts in that class inherit it. Examples:
| Class | Typical policy |
|---|---|
| Feature | Prefer Adapt |
| Plan | Do Not Translate |
| ProductLine | Do Not Translate |
| MarketingMessage | Prefer Adapt |
## Per-market overrides
Some markets need to break the default. From the class detail dialog, open **Market overrides** and set a different policy for one or more locales.
> Example: "Plan" is *Do Not Translate* by default, but Brazil legally requires Portuguese plan names — add a `pt-BR → Prefer Adapt` override.
## How AI tools see this
When you export the ontology (JSON, ZIP bundle, GitHub sync), each class includes:
```yaml
translationPolicy: do_not_translate
overrides:
pt-BR: prefer_adapt
de-DE: prefer_adapt
```
LLM agents reading this bundle will know to render `Pro` as-is in Spanish but adapt it in Brazilian Portuguese — without you writing prompts.
---
# Integrations Overview
> Connect Black Ice to your AI localization pipeline via GitHub Sync, MCP, REST API, or Workspace API. Compare paths and pick the right one for your team.
# Black Ice Integrations — connect your ontology to any AI workflow
Black Ice is the **semantic governance layer** for AI localization pipelines. Your ontology — concepts, terminology, market definitions, and relationships — becomes the source of truth that downstream AI systems read from to produce on-brand, market-accurate output.
There are **three** ways to connect Black Ice to the rest of your stack.
## At a glance
| Integration | Best for | Plan | Direction |
|---|---|---|---|
| MCP server | Live AI clients (Claude, Cursor, IDEs) querying in real time | All plans | Bidirectional |
| Workspace API | Custom pipelines, CI jobs, TMS connectors, batch work | All plans | Bidirectional |
| GitHub Sync | Repo-native agents (Claude Code, Codex), CI, versioned bundles | Builder | Black Ice → Repo |
## MCP — live access for AI clients
The Model Context Protocol server exposes your workspace as tools that MCP-compatible clients (Claude, Cursor, IDE agents) call directly. Queries hit Black Ice in real time, so there is no export step and no stale data.
**Use it when:**
- A human is in the loop, asking an AI client about terminology, markets, or relationships.
- Freshness matters more than versioning.
- You want the AI to read *and* propose writes interactively.
→ [Connect Claude (step by step)](/docs/integrations/connect-claude-mcp) · [Connect Cursor and other clients](/docs/integrations/connect-cursor-mcp) · [MCP client reference](/docs/integrations/claude-desktop-mcp)
## Workspace API — programmatic read/write
Generate scoped API keys and call two endpoints: `query-ontology` for reads and `mutate-ontology` for writes. Available on every plan, with tier-based rate limits.
**Use it when:**
- You are building a custom AI system, RAG pipeline, or content generator.
- You need to script bulk imports, exports, or migrations.
- You want key-scoped access per service.
→ [Workspace API access](/docs/integrations/workspace-api-access) · [API Reference](/docs/integrations/api-reference)
## GitHub Sync — a versioned Markdown snapshot
GitHub Sync exports your approved ontology as a structured **Markdown bundle** (`ontology/CLAUDE.md`, `classes/`, `markets/`, `terminology/`, `relationships/`) into a repository you choose. Push on demand or enable auto-sync.
**Use it when:**
- Your AI agent lives in a code repo (Claude Code, Cursor, Codex, GitHub Actions).
- You want the ontology versioned, diffable, and reviewable through pull requests.
- You need a deterministic, auditable artifact that CI can consume.
→ [GitHub Sync](/docs/integrations/github-sync)
## Choosing the right path
```text
Is a human chatting with Claude, Cursor, or an IDE agent? → MCP
Building a custom backend, CI job, or TMS connector? → Workspace API
Does your agent read files from a code repo? → GitHub Sync
```
Most teams start with **MCP** because it needs no export step, add the **Workspace API** for automation, and enable **GitHub Sync** when they want a reviewable, versioned artifact next to their code.
## Next steps
- [Connect Claude to your workspace](/docs/integrations/connect-claude-mcp)
- [Generate API keys and call the REST endpoints](/docs/integrations/api-reference)
- [Set up GitHub Sync](/docs/integrations/github-sync)
- [API & MCP rate limits](/docs/integrations/rate-limits)
---
# GitHub Sync
> Push your ontology to GitHub as a structured markdown bundle for AI agents and programmatic consumption.
> **GitHub Sync is optional.** It is off by default and only runs if a workspace owner connects a repository. If you don't enable it, your ontology stays in the EU. See [How Black Ice works](/docs/getting-started/how-black-ice-works).
## Overview
GitHub Sync pushes your approved ontology to a GitHub repository as a structured bundle of Markdown files. Every sync writes an `ontology/` directory that your AI localization pipeline, Claude Code project, or CI job can read straight from the file system or through the GitHub API.
GitHub Sync is **one of three integration paths** into Black Ice, alongside the [Workspace API](/docs/integrations/workspace-api-access) and the [MCP server](/docs/integrations/claude-desktop-mcp). None of them replaces the others — pick the one that matches your use case, or combine them.
## Choosing an integration path
| Path | Best for | Access model | Direction |
| --- | --- | --- | --- |
| [Workspace API](/docs/integrations/workspace-api-access) | Custom pipelines, CI jobs, bulk reads and writes, dashboards | API key, JSON over HTTPS | Read + write |
| [MCP server](/docs/integrations/claude-desktop-mcp) | Live agent access from Claude, Cursor, and other MCP clients | OAuth or API key, MCP tools | Read + write |
| GitHub Sync | Repo-resident agents, PR review workflows, versioned snapshots, offline use | GitHub PAT, Markdown files | Push from Black Ice |
**Rules of thumb**
- Need **live, queryable, writable** access to terminology? Use the API or MCP.
- Need the ontology to **live next to your code**, be reviewed in pull requests, and be readable without network access? Use GitHub Sync.
- Many teams run both: MCP for interactive agent work, GitHub Sync for a versioned snapshot the build pipeline consumes.
See [API & MCP rate limits](/docs/integrations/rate-limits) for the caps that apply to the programmatic paths.
## What gets exported
When you sync, Black Ice generates an `ontology/` directory in your repository containing:
```
ontology/
├── CLAUDE.md # Agent instructions and ontology overview
├── classes/ # One file per concept class
│ ├── feature.md
│ ├── plan.md
│ └── platform.md
├── markets/ # One file per target market
│ ├── de-DE.md
│ ├── fr-FR.md
│ └── ja-JP.md
├── terminology/ # Term definitions per locale
│ ├── en-US/
│ ├── de-DE/
│ └── fr-FR/
└── relationships/ # Semantic relationships between concepts
└── relationships.md
```
**CLAUDE.md** is the entry point. It tells your AI agent what the ontology contains, how it is structured, and how to use it.
**Classes** define the taxonomy — what types of concepts exist (Feature, Plan, Platform, etc.) and their translation policies.
**Markets** contain the Culture DNA for each locale — tone of voice, cultural pragmatics, grammar rules, brand identity, and golden examples that guide how content should sound in that market.
**Terminology** holds the actual term definitions — source terms, target translations, allowed/forbidden variants, usage context, and approval status.
**Relationships** maps how concepts connect to each other semantically (e.g. a Plan *hasFeature* relationships).
## Creating a GitHub token
GitHub Sync writes files to your repository, so it needs a token with **write access to repository contents**. A fine-grained personal access token scoped to a single repository is the recommended option.
### 1. Create a fine-grained token
In GitHub, go to **Settings → Developer settings → Personal access tokens → Fine-grained tokens → Generate new token**. Give it a name, choose the account that owns the repository as the **Resource owner**, and set an expiration you can live with.
> Fine-grained tokens **expire**. Note the expiry date — when the token lapses, syncs start failing with a permission error until you generate and save a new one.
### 2. Scope it to the repository and grant Contents: Read and write
Under **Repository access**, choose **Only select repositories** and select the repository you want to sync to. Then under **Permissions → Repository permissions**, add **Contents** and set it to **Read and write**. GitHub adds **Metadata: Read-only** automatically — that is expected.
**"Public repositories (read-only)" will not work** — Black Ice cannot commit with a read-only token.
Click **Generate token** and copy the `github_pat_...` value. GitHub shows it only once.
> Using a classic token instead? It needs the full `repo` scope.
## Setting up GitHub Sync
1. Go to **Settings** in your workspace
2. Open the **GitHub Sync** section
3. Paste the personal access token you just created
4. Specify the repository owner, name, branch, and target path
5. Choose an approval filter — sync all terms, only approved terms, or approved + pending
6. Enable **Auto-sync** to push changes automatically whenever terms are updated
7. Click **Sync now** to verify the connection
## How AI agents consume the ontology
### Direct file access (Claude Code, Cursor, etc.)
If your AI agent runs inside the repo (e.g. Claude Code with a `CLAUDE.md` file), it reads the ontology files directly from disk. No API calls needed.
```
# The agent reads CLAUDE.md first, then navigates the ontology structure
# to find the relevant class, market, and terminology files.
```
If you also want the agent to *query or update* Black Ice live during the same session, connect the [MCP server](/docs/integrations/claude-desktop-mcp) in parallel.
### GitHub API consumption
External systems can fetch ontology files programmatically via the GitHub API:
```bash
# Fetch the agent instructions
curl -H "Authorization: token YOUR_GITHUB_TOKEN" \
https://api.github.com/repos/OWNER/REPO/contents/ontology/CLAUDE.md
# Fetch a specific market profile
curl -H "Authorization: token YOUR_GITHUB_TOKEN" \
https://api.github.com/repos/OWNER/REPO/contents/ontology/markets/de-DE.md
# Fetch all terminology for a locale
curl -H "Authorization: token YOUR_GITHUB_TOKEN" \
https://api.github.com/repos/OWNER/REPO/contents/ontology/terminology/de-DE/
```
### GitHub Actions integration
Trigger downstream workflows whenever the ontology is updated:
```yaml
# .github/workflows/on-ontology-update.yml
on:
push:
paths:
- 'ontology/**'
jobs:
process-ontology:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Process updated ontology
run: |
echo "Ontology updated — trigger localization pipeline"
# Your pipeline logic here
```
## When Markdown files are the right choice
Black Ice exposes a REST API and an MCP server as well — files are not a workaround for a missing API, they are a different delivery model with different strengths:
- **Diff-friendly** — every ontology change creates a readable Git diff, so terminology updates can be reviewed and rolled back like code
- **Repo-native** — agents that already run inside your repository read the ontology with no extra auth, client, or network round-trip
- **Offline-capable** — once cloned, the ontology works without connectivity
- **Prose over payloads** — Markdown market profiles and translation policies read well as LLM context
- **Existing infrastructure** — branch protection, CODEOWNERS, webhooks, and GitHub Actions apply to the ontology for free
And the trade-offs, which is where the API and MCP win:
- Files are a **snapshot**, not live state — they are only as current as the last sync
- GitHub Sync is **one-way**: changes made in the repo do not flow back into Black Ice
- No filtering or querying at request time — you read whole files
## Troubleshooting
**"Sync failed" with a permission error** — the token is missing **Contents: Read and write**, or it is scoped to a different repository. Regenerate it following the steps above.
**Sync worked before and now fails** — the fine-grained token has most likely expired. Generate a new one and save it in Integrations → GitHub.
**Repository or branch not found** — check the owner, repository name, and branch for typos, and confirm the token repository access includes that repo. The branch must already exist.
**Sync succeeds but few or no terms appear** — your approval filter is excluding them. Switch it to "approved + pending" or "all terms" to confirm.
**Private repository in an organisation** — the organisation may need to approve fine-grained tokens. Ask an owner to enable them under the organisation personal access token policy.
## Availability
GitHub Sync is available on the **Builder** tier. See [Plans and Pricing](/docs/getting-started/plans-and-pricing) for details.
## Token expiry at a glance
Once a token is saved, the **GitHub Personal Access Token** field shows when it expires:
- **Expires in N days** — normal state, read from GitHub when the token is saved or used.
- **Expires in N days** (amber) — fewer than 14 days left; generate a replacement soon.
- **Expired** — syncing will fail until you paste a new token.
Fine-grained tokens always expire (90 days by default), so put a reminder in your calendar or pick a longer expiry when you create one.
---
# Black Ice + AI: What Your Ontology Unlocks
> How to feed your Black Ice ontology to Claude, ChatGPT, Gemini, and local models via MCP, the REST API, or GitHub Sync — with a comparison of access paths.
Black Ice governs meaning. AI scales it. These are not two separate tools — they're a stack. Once your ontology lives in Black Ice, every AI model you connect to it stops guessing and starts reasoning from structured truth.
## How models reach your ontology
Before picking a model, pick an access path. There are three, and any model can use at least one of them:
| Path | What it is | Freshness | Tier |
|---|---|---|---|
| **MCP** | Your workspace exposed as tools an MCP client calls directly (Claude Desktop, Claude Code, Cursor) | Live, real time | All plans |
| **API** | REST endpoints (`query-ontology`, `mutate-ontology`) and the Workspace API, called with a scoped key | Live, on demand | All plans |
| **GitHub Sync** | A versioned Markdown bundle pushed to a repo you own | Snapshot per sync | Builder |
A file export is no longer the only way in. Nothing below requires you to paste an ontology into a prompt unless you want to.
→ [Integrations Overview](/docs/integrations/integrations-overview) · [MCP setup](/docs/integrations/claude-desktop-mcp) · [API Reference](/docs/integrations/api-reference) · [GitHub Sync](/docs/integrations/github-sync)
---
## Claude ★ Recommended Integration
### Why Claude is the recommended AI for Black Ice
Claude's extended context window, instruction-following precision, and native support for both MCP and repository workflows make it the natural partner for ontology-fed work. Claude Desktop and Claude Code connect to Black Ice over **MCP**, so they query your live workspace — concepts, terms, market rules, relationships — without any export step. For agents that live in a repo, **GitHub Sync** gives Claude Code a diff-able Markdown bundle it can read offline, review in pull requests, and feed to CI.
> **Recommended setup:** Human in the loop, asking questions or drafting content → **MCP**. Agent running in a repo or CI pipeline → **GitHub Sync**. Many teams run both: MCP for interactive sessions, the bundle as the versioned artifact.
### 01 — Market-Specific Content Generation — No TMS Required
Connect Claude to your workspace over MCP (or point Claude Projects at the GitHub bundle). Claude now knows your approved terms, market availability rules, brand voice per locale, and forbidden expressions — and over MCP it's always current, because it reads at query time. Ask it to write a landing page for Spain. It doesn't translate — it writes, correctly, from first principles. No briefing doc. No terminology spreadsheet.
> **The difference:** Generic Claude writes fluent Spanish. Ontology-fed Claude writes *your* Spanish — for *that* market.
### 02 — Localization QA That Knows Your Product
Run Claude against translated strings with the ontology attached. It flags terminology inconsistencies not against a generic dictionary but against your defined concepts — catching the translator who used "Plan Familiar" when your market DNA specifies "Plan Familia," or who left a feature name untranslated that you've explicitly approved as an anglicism. The MCP `validate_translation` and `check_term` tools do exactly this in one call.
> **The difference:** Rule-based QA checks patterns. Ontology-fed Claude checks meaning.
### 03 — Sprint-Based Delta Localization
Your product shipped a new feature. Three concepts changed. Query the API for what's new, modified, stable, or deprecated. Claude gets only the delta, with full semantic context, and localizes precisely what changed. Nothing more, nothing less. No re-translation of stable strings. No fuzzy-match guesswork.
> **The difference:** Traditional workflows re-translate everything. This one reasons about change.
### 04 — Multi-Project Consistency from a Single Ontology
One workspace, multiple Claude Projects: marketing copy, developer docs, support content, UI strings. All reading from the same semantic source — over MCP they see updates the moment you make them; over GitHub Sync they see them on the next push. Consistency isn't enforced by style guides that get ignored — it's structural.
> **The difference:** Style guides are read once and forgotten. Ontology constraints are active every time Claude runs.
### 05 — Agentic Pipelines with Claude Code
Claude Code can talk to Black Ice two ways: over MCP for live reads and writes, or against the synced repo bundle for a deterministic, reviewable artifact. It applies market rules, generates localized variants, and commits outputs — no UI, no manual handoffs. Three connected layers: Figma (design), GitHub (strings), Black Ice (meaning governance).
> **The difference:** You're not prompting a chatbot. You're running a governed localization agent.
---
## ChatGPT / GPT-4o — Supported Integration
### 01 — Custom GPT Actions against the API
Give a Custom GPT an Action that calls `query-ontology` with a scoped Black Ice API key. The GPT looks terminology up on demand instead of carrying a stale knowledge file, and can write back through `mutate-ontology` if you allow it. This is the closest OpenAI equivalent to the MCP experience, and it works on every plan.
> **Best for:** teams standardised on ChatGPT who want live, governed lookups rather than a snapshot.
### 02 — Knowledge-File GPT for Non-Technical Teams
If nobody wants to configure an Action, upload a Black Ice export as a knowledge file inside a Custom GPT and reference your terminology rules and market definitions in the system prompt. Zero setup, no keys — at the cost of the ontology being a snapshot you have to refresh manually.
> **Best for:** non-technical teams who need governed content generation without any pipeline work.
### 03 — Structured Output in API Pipelines
Use structured/JSON output to generate translation payloads that map directly to your concept IDs. Pull source context from `query-ontology`, hand it to the model, and write results back through `mutate-ontology` or your own store. Useful when output structure matters as much as linguistic quality.
> **Best for:** API-based pipelines where output structure is critical.
---
## Gemini — Supported Integration
### 01 — Large-Document Ontology Ingestion
Gemini's very large context window means you can load an entire Black Ice ontology — concept definitions, market rules, relationship maps, glossaries — in a single prompt. No chunking, no retrieval logic, no RAG overhead. Fetch it fresh from the API at run time rather than pasting a stale copy.
> **Best for:** large enterprise ontologies where context size would be a constraint with other models.
### 02 — Google Workspace Localization Workflows
If your content team lives in Google Docs and Sheets, Gemini's native Workspace integration brings your ontology into existing editorial workflows. An Apps Script call to the Black Ice API can pull the current terminology for a locale into the sheet your reviewers already use.
> **Best for:** teams already embedded in Google Workspace who need governance without workflow disruption.
### 03 — Multimodal Localization QA
Feed screenshots of localized UI alongside your terminology rules and ask Gemini to flag visual string inconsistencies — truncation, untranslated labels, wrong register for the market. Useful for mobile localization QA where the rendered string matters as much as the source string.
> **Best for:** UI and mobile localization QA where visual context matters.
---
## Local Models (Ollama) — Private Deployment
### 01 — Self-Hosted Models Calling the API
A local model doesn't have to work from a static file. If your infrastructure can reach the internet, a small wrapper can call `query-ontology` before each batch so the model always reasons over current terminology, while generation itself never leaves your hardware.
> **Best for:** private inference where the *content* must stay in-house but ontology lookups are acceptable.
### 02 — Air-Gapped Terminology Enforcement
Fully isolated? Export the ontology as Markdown, JSON, or the GitHub bundle and load it into a local model via Ollama — Mistral, LLaMA, Phi, or Qwen all handle structured context reasonably well. Nothing leaves your network. For regulated industries — legal, medical, financial — this is often the only viable route.
> **Best for:** regulated industries or any team where data leaving the building is not an option.
### 03 — High-Volume Batch Localization at Zero API Cost
Running 50,000 strings through a cloud API gets expensive fast. Running them through a local model costs compute, not per-token pricing. Load your ontology once, batch your source strings, run on your own hardware. Quality will be lower than Claude on complex tasks — but for high-volume, lower-complexity sets with strong ontology grounding, the trade-off is often acceptable.
> **Best for:** large-volume, lower-complexity localization where cost per token is a primary constraint.
### 04 — Model Routing: Local for Volume, Claude for Quality
The most pragmatic architecture: route high-volume, stable, low-ambiguity strings to a local model for cost efficiency. Route complex, market-sensitive, brand-critical strings to Claude for quality and nuance. Black Ice is the shared semantic layer across both, reachable by either over the same API.
> **The difference:** The ontology is model-agnostic. The semantic layer doesn't care who's executing — it just enforces the rules.
---
## Integration Comparison
| Capability | Claude ★ | ChatGPT | Gemini | Local (Ollama) |
|---|---|---|---|---|
| Native MCP client | ✓ Desktop, Code, Cursor | ~ client-dependent | ✗ | ~ with a wrapper |
| Calls the Black Ice API | ✓ | ✓ GPT Actions | ✓ via scripts | ✓ if network allowed |
| Reads the GitHub Sync bundle | ✓ Claude Code, Projects | ~ manual upload | ~ manual upload | ✓ local clone |
| Live data without an export step | ✓ MCP | ✓ Actions | ~ scripted fetch | ~ scripted fetch |
| Writes back to the ontology | ✓ MCP + API | ✓ API | ~ API | ~ API |
| Agentic file & repo operations | ✓ Claude Code | ✗ | ✗ | ~ custom tooling |
| Very large ontology in one prompt | ✓ | ~ | ✓ Largest window | ~ model-dependent |
| Multi-market logic in a single prompt | ✓ Excellent | ~ Good | ~ Good | ✗ Struggles |
| Multimodal UI / screenshot QA | ✓ | ✓ | ✓ Strong | ~ limited models |
| Generation stays on-premise | ✗ | ✗ | ✗ | ✓ Full control |
| Zero per-token cost at scale | ✗ | ✗ | ✗ | ✓ |
## Rate limits and freshness
MCP and API calls are capped per workspace per minute — Free 60 reads / 30 writes, Pro 300 / 120, Builder 1,000 / 400 — with `X-RateLimit-*` headers on every response. That's ample for interactive sessions and most pipelines, but a job that resolves terminology for tens of thousands of strings should read the GitHub Sync bundle once instead of querying per string. Live access and bulk access are different tools; use both.
→ [API & MCP rate limits](/docs/integrations/rate-limits)
## Next steps
- [Connect Claude Desktop or Cursor via MCP](/docs/integrations/claude-desktop-mcp)
- [Generate API keys and call the REST endpoints](/docs/integrations/api-reference)
- [Set up GitHub Sync](/docs/integrations/github-sync)
- [Compare all integration paths](/docs/integrations/integrations-overview)
---
# Connect Claude to your workspace (step by step)
> Step-by-step guide with screenshots: add Black Ice as a custom connector in Claude, authorize the workspace over OAuth, and start asking Claude about your terminology.
Connect Claude to your Black Ice workspace in about three minutes. Once connected, Claude consults your ontology live — approved terms, forbidden variants, market availability, voice and tone — without you pasting anything into the chat.
> **Any plan.** The MCP connector is available on Free, Pro, and Builder. Access is read-only (`mcp:read`) and scoped to one workspace per connection.
## Before you start
- A Black Ice account with at least one workspace.
- Claude (Desktop or web) on a plan that allows custom connectors.
- That's it. The OAuth path below needs **no API key**.
---
## Step 1 — Open Connectors in Claude
Click your name in the bottom-left corner, choose **Settings**, then **Connectors** in the sidebar.
## Step 2 — Add a custom connector
Open the **Add** dropdown in the top right and choose **Add custom connector**.
## Step 3 — Paste the Black Ice MCP URL
Give it the name **Black Ice** and paste this URL:
```text
https://mcp.black-ice.ai/mcp
```
Leave the OAuth Client ID and Client Secret fields empty — Black Ice supports Dynamic Client Registration, so Claude registers itself automatically. Save.
## Step 4 — Connect
The connector appears with a **Connect** button and the note "You are not connected to Black Ice yet." Click it.
## Step 5 — Authorize and pick a workspace
A Black Ice authorization page opens in your browser. Sign in if you aren't already, then pick which workspace Claude should read. Click **Allow access**.
> **One workspace per connection.** If you work across several workspaces, add a second custom connector and authorize the other workspace there. You can also switch later — see [Switching the workspace Claude or Cursor uses](/docs/integrations/switch-mcp-workspace).
## Step 6 — Review the tools
Back in Claude, the connector now lists seven read-only tools. Set **Always allow** if you want Claude to use them without asking each time.
| Tool | What it answers |
| --- | --- |
| Check approved term | What is the approved term for this concept in this locale? |
| Validate translation draft | Does this draft use forbidden or non-preferred variants? |
| Check market availability | Is this concept available in that market, and under what conditions? |
| List concepts | What concepts exist, optionally filtered by class? |
| List concept classes | What taxonomy classes does this workspace use? |
| List semantic relationships | What is related to this concept, and how? |
| Get market profile | What is the voice, tone, and culture DNA for this locale? |
## Step 7 — Try it
Open a new conversation and ask something only your ontology can answer:
> _"Using Black Ice, what's the approved Spanish (`es-es`) term for MIDI Editor, and which variants are forbidden?"_
If Claude answers with your approved terminology and flags the forbidden variant, you're connected. For more, jump to the [ready-to-copy prompt library](#ready-to-copy-prompts-for-localization-workflows) below.
---
## Ready-to-copy prompts for localization workflows
Copy any prompt below, swap the `` for your values, and paste it into Claude. Each one is built around the tools Black Ice exposes, so Claude pulls live ontology data instead of guessing from general knowledge.
### Terminology & QA
**1. Terminology lookup**
```
Using Black Ice, what is the approved term for ""?
List forbidden variants, the translation policy, and any usage notes.
```
**2. Draft validation (QA pass)**
```
Validate this draft against Black Ice terminology and flag every
term that is forbidden, unapproved, or inconsistent. Return a table:
term found | status | approved replacement | reason.
Draft:
""
```
**3. Batch string translation with governance**
```
Translate these UI strings from to .
Before translating, look up every product term in Black Ice and use the
approved target term. Never translate terms marked Do Not Translate.
Output as JSON keeping the original keys.
```
### Markets & availability
**4. Market availability check**
```
Using Black Ice, is "" available in ? Include availability
status, tier restrictions, and any legal or marketing disclaimers required
in that market.
```
**5. Market & culture briefing before a campaign**
```
Using Black Ice, summarise the market definition for : voice, tone,
culture DNA, formality, and what to avoid. Then rewrite this headline to fit:
""
```
### Launch readiness
**6. Gap report before a launch**
```
Using Black Ice, list concepts in class "" that have no approved
term yet. Group by priority and suggest candidate translations
consistent with existing approved terminology.
```
**7. Consistency audit across locales**
```
Using Black Ice, compare the approved terms for "" across
, , and . Flag any locale where the term
drifts in meaning, register, or capitalisation from the source definition.
```
### Authoring & stakeholder comms
**8. Onboard a new term (write-enabled workspaces)**
```
Using Black Ice, create a concept for "" in class "" with the
definition "", then propose approved terms for
following each market's translation policy. Show me the proposal before writing.
```
**9. Explain a decision to a stakeholder**
```
Using Black Ice, explain in plain language why "" is translated as
"" in and not "". Cite the concept
definition, policy, and market notes.
```
### Marketing & campaigns
**10. Localised marketing campaign for a plan and market**
```
Using Black Ice, draft a 3-email launch campaign for aimed at the
market. Pull the market definition for voice, tone, formality,
and culture DNA, then enforce approved terminology for all product names
and features. For each email give: subject line, preview text, body
(120–180 words), and CTA. Keep Do-Not-Translate terms untranslated and
respect any availability or disclaimer constraints for that locale.
```
This prompt chains three MCP tools — market briefing, approved terms, and availability flags — so the output is on-brand and compliant, not just translated.
### Project instruction
**11. Project instruction (paste once, not per chat)**
```
When the user asks about terminology, translations, market availability,
or tone of voice, call Black Ice first and use only approved terms.
If a term is missing from Black Ice, say so instead of inventing one.
```
> **Prompt 8 needs a write-enabled connection.** The OAuth connector is read-only; to create concepts you'll need an API key with write scope. See [API Access](/docs/integrations/workspace-api-access).
>
> **Prompt 11 is a Project instruction**, not a chat message. Paste it once into a Claude Project's custom instructions so it applies to every conversation.
---
## Prefer an API key instead of OAuth?
Some clients can't run the OAuth flow. Every MCP endpoint also accepts a Black Ice API key:
- **Header (recommended):** `x-api-key: bice_…` against `https://mcp.black-ice.ai/mcp`
- **Query parameter:** `https://mcp.black-ice.ai/mcp?apikey=bice_…` — for clients that can't send custom headers. Treat that URL as a secret.
Generate keys under **Integrations → API Access**. Examples for Claude Code, Cursor, and MCP Inspector are in [Connecting MCP clients to Black Ice](/docs/integrations/claude-desktop-mcp).
## Troubleshooting
**Claude never opens the authorization page.** The URL must be exactly `https://mcp.black-ice.ai/mcp` with no trailing slash or path. Remove the connector and add it again.
**"You don't have access to any workspaces yet."** You're signed into Black Ice with a different account than the one holding the workspace. Use **Sign in as a different user** on the authorization screen.
**Claude answers from general knowledge instead of Black Ice.** Say "using Black Ice" in the prompt, or add a project instruction: _"When the user asks about terminology, translations, or market availability, call Black Ice first."_
**A forbidden variant isn't flagged.** Only terms with status **approved** are enforced; drafts and pending terms are ignored on purpose.
**Wrong terminology comes back.** The connection is authorized against a different workspace. Re-authorize, or add a separate connector for the other workspace.
**You want to revoke access.** In Black Ice, go to **Integrations → MCP** and revoke the authorization under *Active OAuth authorizations*. Disconnecting inside Claude also ends the session.
## Rate limits
MCP calls are capped per workspace per minute — Free 60 reads / 30 writes, Pro 300 / 120, Builder 1,000 / 400. See [API & MCP rate limits](/docs/integrations/rate-limits).
## Next steps
- [All MCP clients and tool reference](/docs/integrations/claude-desktop-mcp)
- [Switching the workspace Claude or Cursor uses](/docs/integrations/switch-mcp-workspace)
- [Black Ice + AI: what your ontology unlocks](/docs/integrations/ai-integrations-overview)
---
# Connect Cursor and other MCP clients
> Connect Cursor, VS Code, and other MCP clients to your Black Ice workspace over the remote MCP server.
Black Ice exposes your workspace through a **remote MCP server**, so any MCP-compatible client can query your ontology live. This guide covers Cursor, VS Code agents, and generic clients. For Claude, see the [step-by-step Claude guide](/docs/integrations/connect-claude-mcp).
## What you need
- The server URL: `https://mcp.black-ice.ai/mcp`
- Either an OAuth sign-in (recommended, browser-based) or a workspace API key from **Integrations → API Keys**
## Cursor
1. Open **Cursor Settings → MCP → Add new MCP server**.
2. Choose a **remote / URL** server and paste `https://mcp.black-ice.ai/mcp`.
3. Save. Cursor opens a browser window for the Black Ice authorization screen — approve access for the workspace you want.
4. The Black Ice tools appear in the MCP tool list. Toggle them on for the chats where you want ontology access.
If your Cursor version does not support OAuth for remote servers, use the API key form instead:
```json
{
"mcpServers": {
"black-ice": {
"url": "https://mcp.black-ice.ai/mcp",
"headers": {
"Authorization": "Bearer bk_live_xxxxxxxxxxxxxxxx"
}
}
}
}
```
## VS Code and other agent IDEs
Any client that supports **streamable HTTP MCP servers** works the same way: register the URL, authenticate with OAuth or a bearer API key, and enable the tools. Clients that only support stdio servers need a bridge process — in that case, prefer the [Workspace API](/docs/integrations/workspace-api-access).
## Choosing the workspace
The workspace is bound at authorization time. To point a client at a different workspace, disconnect the connector and re-authorize while that workspace is active.
→ See [Switching the workspace Claude or Cursor uses](/docs/integrations/switch-mcp-workspace)
## Verifying the connection
Ask the client:
```text
List the Black Ice tools you have available, then show me five concepts from my workspace with their Spanish (es-ES) terms.
```
If the tools are connected you get real data back. If not, the client will say it has no matching tools — re-check the URL and authorization.
## Troubleshooting
| Symptom | Cause and fix |
|---|---|
| Client shows the server as failed | URL typo — it must end in `/mcp` |
| Browser opens but authorization never completes | Pop-up blocker, or you were signed out of Black Ice — sign in first, then retry |
| `401 Unauthorized` | API key revoked or malformed; generate a new one in Integrations → API Keys |
| `429 Too Many Requests` | Plan rate limit reached — see [rate limits](/docs/integrations/rate-limits) |
| Tools return no concepts | The authorized workspace is empty or you authorized the wrong one |
## Rate limits
MCP calls share the same tier-based limits as the Workspace API: 60/30 per minute on Free, 300/120 on Pro, 1000/400 on Builder.
---
# Connecting MCP clients to Black Ice
> Connect Claude Desktop, Claude Code, Cursor, and other MCP clients to your Black Ice workspace to check approved terms and market availability live.
Connect Claude Desktop directly to your Black Ice workspace using the Model Context Protocol (MCP). Once connected, Claude can consult your ontology in real time — checking approved terms, flagging forbidden variants in draft translations, and confirming market availability — without you copying anything into the chat.
> **What you get.** Seven governance tools, single-workspace per connection, authenticated by API key or OAuth 2.1. The MCP connector is available on **all plans**, including Free.
## Before you start
You will need:
1. A Black Ice workspace on **any plan** — Free, Pro, or Builder. There is no tier gate on the MCP connector itself; per-plan limits (concepts, markets, members) apply as normal.
2. **Claude Desktop** with custom-connector support enabled in Settings.
3. Five minutes.
## Step 1 — Generate an API key
1. Open Black Ice and go to **Settings → API Access**.
2. Click **Generate API key**, give it a recognisable name (for example, `Claude Desktop — laptop`), and copy the value.
3. The key starts with `bice_…` and is shown **only once**. Paste it somewhere safe before leaving the page.
> **Single-tenant, by design.** One key authorises one workspace. If you work across multiple Black Ice workspaces, generate a separate key for each and create a separate Claude Desktop connection per workspace.
## Step 2 — Add Black Ice as a custom connector in Claude Desktop
1. In Claude Desktop, open **Settings → Connectors → Add custom connector**.
2. Use the following configuration:
| Field | Value |
| --- | --- |
| Name | `Black Ice` |
| Remote MCP server URL | `https://mcp.black-ice.ai/mcp?apikey=YOUR_BICE_KEY` |
| Advanced settings | Leave OAuth Client ID and OAuth Client Secret empty |
> **Why a URL parameter?** Claude Desktop's custom connector UI does not currently support custom request headers, so the API key travels as a query parameter. Treat the full URL as a secret — anyone with it can read your workspace ontology. Header-based auth (`x-api-key`) remains the recommended path for programmatic clients (curl, MCP Inspector, custom integrations). OAuth 2.1 with Dynamic Client Registration is also available — see **What's next** below.
3. Save. Claude Desktop will run an `initialize` handshake and discover the seven tools.
## Step 3 — Try each tool
Open a new Claude conversation and try one prompt per tool. The point of each prompt is to demonstrate something that a generic translator would not catch.
### `check_term` — see the governance metadata
> _"Use Black Ice to check the approved Spanish (`es-es`) term for **MIDI Editor**. Show me the forbidden variants too."_
Claude will return the approved term, status, market availability, and the `forbiddenVariants` list. The forbidden list is the part that matters: it's the vocabulary your team has explicitly ruled out.
### `validate_translation` — catch a forbidden variant in a draft
> _"Validate this Spanish draft against Black Ice: 'El nuevo MIDI Editor permite editar pistas con precisión.' Locale: `es-es`."_
If your workspace marks `MIDI Editor` as a forbidden variant for `es-es` (with `Editor MIDI` as the approved term), Claude will return a `forbidden`-severity flag pointing at the exact span and suggesting the approved replacement. This is the demo moment: the AI being told **"no, not that word."**
### `check_market_availability` — confirm a feature ships in a market
> _"Is the **Stem Splitter** feature available for the `es-es` market according to Black Ice? Include any tier or disclaimer constraints."_
Claude will return the availability state (`available`, `planned`, `not_available`, `unapproved`, `not_set`) and any market_constraint metadata you've recorded — tier, disclaimer, local plan name, supported platforms.
### `list_concepts` — discover what's in the ontology
> _"Using Black Ice, list all concepts available in `es-es` and tell me which ones are restricted by plan."_
Returns a slim list (`conceptId`, `conceptName`, `className`, `term`, `status`, `availability`) for every concept in the workspace ontology for the locale. Optional `class` filter narrows the list to a single class (`Feature`, `Plan`, `Market`, etc.). Useful as a first call before drilling into a specific concept with `check_term` or `check_market_availability`.
### `list_classes` — discover the workspace taxonomy
> _"Using Black Ice, what concept classes exist in this workspace for `es-es`?"_
Returns the distinct class names in the workspace ontology with concept counts, sorted by count descending. Recommended discovery flow: `list_classes` → `list_concepts(locale, class)` → `check_term` or `check_market_availability`. This makes prompts workspace-agnostic — no need to hardcode class names.
### `list_relationships` — traverse the semantic graph
> _"Using Black Ice, what concepts are part of `plan_00000001` in `es-es`?"_
Returns semantic relationships (`part_of`, `requires`, `variant_of`, etc.) between concepts. Inputs: `locale` (required), `conceptId` (optional — filter to relationships involving this concept), `direction` (optional — `outgoing`, `incoming`, or `both`; default `both`), `relationshipType` (optional — case-insensitive filter like `part_of`). Recommended graph traversal flow: `list_concepts(locale, class)` → pick a `conceptId` → `list_relationships(locale, conceptId)` to discover what it depends on, includes, or is part of.
### `get_market_profile` — voice, tone, and culture DNA for a locale
> _"Using Black Ice, what's the voice and tone profile for `es-es`?"_
Returns the full market profile for a locale: brand identity (name, tagline, positioning) plus the 10-section culture DNA — Market Snapshot, Voice/Locale DNA, Tone & Style Rules, Culture & Pragmatics, Grammar & Mechanics, UX/Microcopy Rules, Locale Conventions, Terminology Rules, Golden Examples, and Output Constraints. Use this to ground translation and content generation in the same market definition that drives Black Ice's in-app workflows. Input: `locale` (required, e.g. `es-es`). Returns `{ found: false }` if the locale is not configured for the workspace.
## How disambiguation works
If a concept name resolves to more than one concept (for example, two classes both have a "Studio" concept), the tool returns:
```json
{
"ambiguous": true,
"matches": [
{ "conceptId": "feat_00000007", "conceptName": "Studio", "className": "Feature" },
{ "conceptId": "plan_00000003", "conceptName": "Studio", "className": "Plan" }
],
"hint": "Multiple concepts share that name. Re-call this tool with the conceptId from `matches`."
}
```
Claude will follow up with the `conceptId` directly, bypassing name matching entirely.
## Troubleshooting
**"Missing or invalid x-api-key header"** — the connector URL is missing the `?apikey=bice_…` parameter, or the value doesn't start with `bice_`. Re-check the Remote MCP server URL.
**"No concept matched 'X' for locale 'Y'"** — either the concept doesn't exist in your workspace or no target term has been created yet for that locale. Check **Concepts** in Black Ice and confirm the locale has been added under **Markets**.
**Claude isn't suggesting Black Ice tools.** Add a system instruction to your Claude Project: _"When the user asks about a translation, terminology decision, or market availability, call Black Ice first."_
**Forbidden variant not flagged.** Only target terms with `status: approved` enforce. Pending or draft terms are ignored on purpose so in-progress edits don't generate noise. Approve the term in Black Ice and try again.
**Wrong workspace.** Each `bice_` key is bound to one workspace. If Claude returns the wrong terms, you've connected the key for a different workspace — generate a new key in the correct workspace.
## What's next
- **OAuth 2.1 with Dynamic Client Registration is live.** Clients that prefer OAuth over a static API key can discover the authorization server via `https://mcp.black-ice.ai/.well-known/oauth-protected-resource` and run the standard PKCE flow. Listing on the public Anthropic Connectors Directory is pending Anthropic review.
- A write API so Claude can propose new terms or flag drift directly into your workspace pending approval is on the roadmap.
## Other MCP clients
The endpoint is transport-agnostic Streamable HTTP and works with any MCP client. Claude Desktop is walked through above because its custom-connector UI cannot send custom headers, so the API key has to ride in the URL. Other clients should pass the key via the `x-api-key` header instead:
- **Claude Code** — `claude mcp add black-ice --transport http https://mcp.black-ice.ai/mcp --header "x-api-key: bice_…"`
- **Cursor** — add an MCP server in settings, point it at `https://mcp.black-ice.ai/mcp`, set `x-api-key` as a custom header.
- **MCP Inspector** — `npx @modelcontextprotocol/inspector` and configure the same endpoint + header.
- **Custom SDK clients** — any TypeScript or Python MCP SDK client; just include the `x-api-key` header on every request.
Both auth paths (`?apikey=` query param and `x-api-key` header) are accepted by the server. Use the header form whenever your client supports it — it keeps the key out of URL logs.
## 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.
---
# API Reference
> Read and write your workspace ontology programmatically — endpoints, auth, schemas, and a downloadable full reference.
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
- **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 |
| `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).
## 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"
```
## 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.
📥 Download full API reference (Markdown)
> 💡 **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.
---
# API & MCP rate limits
> Per-plan throughput caps for the MCP server and Workspace API, response headers, and how to design pipelines around them.
Black Ice applies rate limits to every programmatic entry point — the MCP server, the Workspace REST API, and the OAuth client registration endpoint. Limits scale with your plan so paid workspaces can run parallel agents and CI pipelines without being throttled.
## Limits by plan
Limits are counted **per workspace**, in a rolling one-minute window.
| Plan | Read calls / min | Write calls / min |
|---|---|---|
| Free | 60 | 30 |
| Pro | 300 | 120 |
| Builder | 1,000 | 400 |
**Reads** are lookups: `check_term`, `validate_translation`, `check_market_availability`, `list_concepts`, `list_classes`, `list_relationships`, `get_market_profile`, and every `GET` against the Workspace API.
**Writes** are mutations: creating or updating concepts, terms, markets, and market definitions — through MCP write tools or `POST`/`PATCH`/`DELETE` on the Workspace API.
MCP tool calls and direct REST calls share the same budget: an MCP call is internally a call to the same ontology functions, so 100 MCP reads and 100 REST reads both consume 100 read units.
## Monthly call cap (Free plan)
Beyond the per-minute throttle, the **Free plan has a hard cap of 10,000 API + MCP calls per calendar month, per workspace**. Pro and Builder have **no monthly cap** — only the per-minute limits above apply.
| Plan | Monthly API + MCP calls |
|---|---|
| Free | 10,000 |
| Pro | Unlimited |
| Builder | Unlimited |
**What counts as a call:** every MCP tool call and every REST request to the Workspace API — reads and writes alike — counts as one call. Using the Black Ice web app, importing a spreadsheet, exporting an ontology, or running GitHub Sync does **not** consume the allowance.
**When it resets:** at 00:00 UTC on the 1st of each calendar month. Upgrading to Pro or Builder lifts the cap immediately.
**What happens at the cap:** calls return `429 Too Many Requests` with `Retry-After` and a body carrying the machine-readable code `monthly_cap_reached`:
```json
{
"error": "Monthly call limit reached: 10,000 calls/month on the Free plan. Resets on 1 September.",
"code": "monthly_cap_reached",
"tier": "free",
"limit": 10000,
"used": 10000
}
```
Treat this differently from a per-minute 429: retrying in a few seconds will not help. Branch on `code === "monthly_cap_reached"`, stop the run, and either wait for the reset or upgrade.
**Checking your remaining allowance:** Free-plan responses carry monthly headers alongside the per-minute ones.
| Header | Meaning |
|---|---|
| `X-RateLimit-Scope` | `month` when the monthly cap applies |
| `X-RateLimit-Month-Limit` | Monthly allowance (10,000 on Free) |
| `X-RateLimit-Month-Remaining` | Calls left this month |
| `X-RateLimit-Month-Reset` | Unix timestamp of the reset (1st of next month, 00:00 UTC) |
The same figure is shown in the app under **Integrations → Usage & Analytics**, with a warning once you pass 80% of the allowance.
## Client registration (OAuth DCR)
Dynamic client registration on the MCP OAuth endpoint is capped at **10 registrations per hour per IP address**, on all plans. This protects the authorization server and is unrelated to your tool-call budget — a normal MCP client registers once and reuses its credentials.
## Reading the response headers
Every API and MCP response carries the current budget state:
| Header | Meaning |
|---|---|
| `X-RateLimit-Limit` | Maximum calls allowed in the current window |
| `X-RateLimit-Remaining` | Calls left before throttling |
| `X-RateLimit-Reset` | Unix timestamp (seconds) when the window resets |
When you exceed the limit, the response is `429 Too Many Requests` with a `Retry-After` header (seconds to wait) and a JSON body describing the limit and your plan.
```json
{
"error": "rate_limit_exceeded",
"message": "Rate limit exceeded for plan 'pro'. Try again in 24 seconds.",
"limit": 300,
"retry_after": 24
}
```
## Designing pipelines that stay under the cap
- **Respect `Retry-After`.** Treat a 429 as a scheduling signal, not an error. Sleep for the advertised interval and resume.
- **Use exponential backoff with jitter** for retries beyond the first, so parallel workers do not retry in lockstep.
- **Batch where possible.** `list_concepts` with a filter returns many concepts in one call; looping `check_term` per string does not.
- **Cache market profiles.** Market definitions change rarely — fetch `get_market_profile` once per run and reuse it across all strings for that locale.
- **Watch `X-RateLimit-Remaining`** and slow down proactively when it drops below ~10% rather than sprinting into a 429.
- **Split heavy jobs across workspaces** if you run genuinely independent pipelines, since budgets are per workspace.
## Worked example: a CI translation check
A pull request touching 200 strings, checked on the Builder plan:
1. One `get_market_profile` call per target locale (5 locales = 5 reads, cached for the run).
2. One `list_concepts` call to pull the relevant class (1 read).
3. `validate_translation` per string per locale — 200 x 5 = 1,000 reads.
That is 1,006 reads. On Builder (1,000/min) the job completes in just over a minute with a single short pause; on Free (60/min) it would take roughly 17 minutes. Caching profiles and batching concept lookups is what keeps the number close to the theoretical minimum.
## Need more throughput?
Limits are a fair-use protection, not a hard product boundary. If your workload consistently needs more than the Builder allowance — for example a high-volume localization pipeline or an agent fleet running continuously — contact support and we will review a custom limit for your workspace.
---
# Switching the workspace Claude or Cursor uses
> Force an MCP client to re-authorize against a different workspace.
# Switching the workspace Claude or Cursor uses
When you authorize an MCP client (Claude, Cursor, …) it gets an OAuth token **bound to one specific workspace**. Disconnecting in the MCP client only removes the connection locally — the token stays valid on the Black Ice server, and many clients silently reuse it when you reconnect, so you never see the authorization screen again.
To force a fresh authorization (and pick a different workspace or user):
1. In Black Ice, open **Integrations → MCP Integration**.
2. Under **Active OAuth authorizations**, click **Revoke** on the client you want to reset (or **Revoke all**).
3. Back in your MCP client (Claude, Cursor), the next tool call will fail with an auth error. Remove and re-add the MCP server, or trigger a tool call — the client will start a fresh OAuth flow.
4. Black Ice will show the **Authorize MCP connector** screen. Pick the workspace you want, or use **Sign in as a different user** if you need a different account.
Tokens are workspace-scoped by design: this keeps each MCP session strictly isolated. If you regularly switch between workspaces, revoking + re-authorizing takes about 10 seconds.
---
# Workspace API access
> Read and write your ontology programmatically from external tools.
The Workspace API lets external AI tools, scripts, and integrations read and write a workspace directly — no GitHub bundle in between.
> Workspace API access is available on **all plans, including Free**. Higher tiers get higher rate limits and larger concept/market quotas. Free workspaces are capped at **10,000 API + MCP calls per calendar month**; Pro and Builder have no monthly cap. See [API & MCP rate limits](/docs/integrations/rate-limits).
## Generating an API key
1. Open **Integrations → API Keys** (`/integrations/api-keys`).
2. Click **Create API key** and give it a label (e.g. `production-llm`).
3. Choose an **access level**:
- **Read only** — for one-directional integrations that pull the ontology as reference data (TMS, CMS, RAG pipeline). Cannot modify the workspace.
- **Read and write** — for two-way sync that creates, updates, or deletes concepts and terms.
4. Copy the key shown — it is displayed **once**. Only a hash is stored, so it cannot be retrieved later.
5. Store the key in your tool's secret manager.
Each key shows its prefix, access level, and a **last used** timestamp so you can spot stale keys.
## Endpoints
| Method | Endpoint | Purpose |
|---|---|---|
| `GET` | `/functions/v1/query-ontology` | Read the full workspace ontology (concepts, terms, relationships, markets) |
| `POST` | `/functions/v1/mutate-ontology` | Create, update, delete, or upsert concepts, terms, relationships, classes, and market constraints |
Base URL: `https://oosdjmpzvcljxwaqxcko.supabase.co`
## Authentication
Send your API key in the `x-api-key` header:
```
x-api-key: bice_xxxxxxxxxxxxxxxx
```
Each request is scoped to the workspace that owns the key. A read-only key used against `mutate-ontology` returns `403` with `"code": "insufficient_scope"` — generate a read-and-write key for two-way sync.
## Rate limits
Limits are per key, per minute, and depend on the workspace plan:
| Plan | Read requests/min | Write operations/min |
|---|---|---|
| Free | 60 | 30 |
| Pro | 300 | 120 |
| Builder | 1000 | 400 |
Payload cap is 1 MB per request. Exceeding a limit returns `429 Too Many Requests` with a `Retry-After` header and `X-RateLimit-*` headers on every response.
→ Full details: [API & MCP rate limits](/docs/integrations/rate-limits)
## When to use the API vs. MCP vs. GitHub Sync
- **Workspace API** — custom pipelines, CI jobs, TMS connectors, bulk reads and writes.
- **MCP** — live, interactive access from Claude, Cursor, and other MCP clients.
- **GitHub Sync** — a versioned, diffable Markdown snapshot living next to your code.
They can be combined: most teams run MCP for interactive work and the API for automation.
## Revoking a key
Click the trash icon next to a key in **Integrations → API Keys**. Integrations using that key start receiving `401 Unauthorized` immediately.
→ See also: [Managing and troubleshooting API keys](/docs/integrations/api-key-management)
See also: [Pulling the ontology into your stack (integration guide)](/docs/integrations/ontology-pull-integration).
---
# Pulling the ontology into your stack (integration guide)
> Step-by-step guide for pulling your Black Ice ontology into an external system over the read API: read-only keys, pagination, incremental sync, rate limits, and errors.
# Pulling the ontology into your stack
This guide walks through the most common integration pattern: an external system (a TMS, CMS, search index, or RAG pipeline) keeps an internal, read-only copy of your Black Ice ontology as reference data. The flow is strictly one-directional — all edits continue to happen in Black Ice by your licensed users, and the integration only pulls.
Estimated setup time: under 30 minutes.
## How it works
```
Black Ice (source of truth)
|
| GET /functions/v1/query-ontology
| x-api-key: bice_... (read-only)
v
Your integration service
|
v
Internal copy (reference data)
```
1. You create a **read-only API key** in Black Ice.
2. Your service calls the read endpoint on a schedule (or on demand), authenticating with that key.
3. It paginates through the full ontology — concepts, terms, definitions, classes, relationships, market constraints — and stores an internal copy.
4. On subsequent runs it uses the `since` parameter to fetch only what changed.
## Step 1: Create a read-only API key
1. Open **Integrations → API Keys** (`/integrations/api-keys`).
2. Click **Create API key** and give it a label, e.g. `tms-production-sync`.
3. Choose the **Read only** access level. This is the important part for security review: the credential physically cannot modify the ontology. A read-only key used against the write endpoint returns `403` with `"code": "insufficient_scope"`.
4. Copy the key immediately — it is shown **once** and only a hash is stored.
5. Store it in your secrets manager (AWS Secrets Manager, Vault, Doppler, etc.). Never embed it in client-side code or commit it to a repository.
Keys look like `bice_xxxxxxxxxxxxxxxx`. Each key is scoped to exactly one workspace.
## Step 2: Call the endpoint
Base URL: `https://oosdjmpzvcljxwaqxcko.supabase.co`
```bash
curl "https://oosdjmpzvcljxwaqxcko.supabase.co/functions/v1/query-ontology?limit=1000" \
-H "x-api-key: bice_xxxxxxxxxxxxxxxx"
```
### Node.js
```js
const res = await fetch(
"https://oosdjmpzvcljxwaqxcko.supabase.co/functions/v1/query-ontology?limit=1000",
{ headers: { "x-api-key": process.env.BLACK_ICE_API_KEY } }
);
if (!res.ok) throw new Error(`Black Ice API error: ${res.status} ${await res.text()}`);
const ontology = await res.json();
```
### Python
```python
import os, requests
res = requests.get(
"https://oosdjmpzvcljxwaqxcko.supabase.co/functions/v1/query-ontology",
headers={"x-api-key": os.environ["BLACK_ICE_API_KEY"]},
params={"limit": 1000},
timeout=30,
)
res.raise_for_status()
ontology = res.json()
```
## Step 3: Paginate through everything
The endpoint pages over **concepts** (default 1000 per page, max 5000):
| Parameter | Meaning |
|---|---|
| `limit` | Concepts per page (1–5000, default 1000) |
| `offset` | How many concepts to skip (default 0) |
The response tells you how to continue:
```json
{
"pagination": {
"limit": 1000,
"offset": 0,
"returned": 1000,
"totalConcepts": 2400,
"hasMore": true,
"nextOffset": 1000
},
"_links": { "next": ".../query-ontology?limit=1000&offset=1000" }
}
```
Loop until `hasMore` is `false` (or follow `_links.next` until it is `null`).
> **Payload ceiling:** a single response is capped at 4 MB. If your page exceeds it, the API returns `413` with a `suggestedLimit` — retry with that `limit` and keep paginating.
## Step 4: Sync only what changed
For scheduled re-syncs, add `since` with the timestamp of your last successful run (ISO 8601). Only concepts updated at or after that moment are returned:
```
GET /functions/v1/query-ontology?since=2026-09-01T00:00:00Z
```
Use `locale` to pull a single target market instead of all of them:
```
GET /functions/v1/query-ontology?locale=es-es
```
Store the response's `exportedAt` timestamp as the cursor for your next run.
## What the response contains
| Field | Contents |
|---|---|
| `terminology` | One entry per concept (× target locale): concept ID and name, definition, class, source term, target term with allowed/forbidden variants, notes, and status |
| `relationships` | Typed links between concepts (source, relationship type, target, conditions) |
| `classes` | Concept classes with their translation policy |
| `markets` | Locales with name, native name, direction, culture DNA, and localized brand identity |
| `marketConstraints` | Per-concept availability, tier, platforms, disclaimer, and local plan name per market |
| `brandIdentity` | Workspace-level brand name, tagline, and positioning |
A term entry looks like:
```json
{
"conceptId": "plan_00001234",
"conceptName": "Free Trial",
"definition": "A time-limited evaluation period...",
"className": "Plans",
"sourceTerm": { "locale": "en-us", "term": "Free Trial", "availability": "available" },
"targetTerm": {
"locale": "es-es",
"term": "Prueba gratuita",
"availability": "available",
"allowedVariants": ["periodo de prueba"],
"forbiddenVariants": ["versión gratis"],
"status": "approved"
}
}
```
`status` is one of `pending_approval`, `approved`, `rejected`, or `deprecated`. Most integrations only apply `approved` terms and treat the rest as unpublished.
## Rate limits and quotas
Limits depend on the workspace plan:
| Plan | Read requests/min | Monthly cap |
|---|---|---|
| Free | 60 | 10,000 calls/month |
| Pro | 300 | none |
| Builder | 1000 | none |
Every response carries `X-RateLimit-Limit`, `X-RateLimit-Remaining`, and `X-RateLimit-Reset` headers (plus monthly quota headers on Free). If you receive `429`, wait for the `Retry-After` number of seconds and retry — do not hammer the endpoint. A well-behaved sync (a handful of paginated calls per run) stays far below every tier's limits.
## Error reference
| Status | Meaning | What to do |
|---|---|---|
| `400` | Invalid parameter (e.g. a malformed `since`) | Fix the parameter value |
| `401` | Missing or invalid API key | Check the `x-api-key` header and that the key hasn't been revoked |
| `403` | `insufficient_scope` — a read-only key was used against the write endpoint | Expected for pull-only integrations; generate a read-and-write key only if you truly need writes |
| `413` | Response too large | Retry with the `suggestedLimit` from the error body |
| `429` | Per-minute rate limit or monthly cap reached | Back off per `Retry-After`; on Free, the monthly cap resets on the 1st |
## Security checklist for your review
- Read-only key for pull-only integrations — write access is never held by a system that has no reason to write.
- Key stored in a secrets manager, injected via environment variable.
- Only the key hash is stored by Black Ice; the raw key cannot be retrieved or leaked from the platform.
- Rotate periodically: create a new key, update the secret, verify, then revoke the old key from **Integrations → API Keys**.
- Each key shows a **last used** timestamp, so stale credentials are easy to spot and revoke.
## Alternative for AI assistants: the MCP server
If the consumer is an AI assistant (Claude, ChatGPT, an internal copilot) rather than a backend service, use the Black Ice MCP server instead. It is **read-only by design** and uses OAuth with the `mcp:read` scope — no API keys to manage at all. See the AI Integrations section.
## Related guides
- [Workspace API access](/docs/integrations/workspace-api-access)
- [Managing and troubleshooting API keys](/docs/integrations/api-key-management)
- [API Reference](/docs/integrations/api-reference)
- [API & MCP rate limits](/docs/integrations/rate-limits)
---
# Managing and troubleshooting API keys
> Create, rotate, revoke, and debug Workspace API keys, including the meaning of 401, 403, and 429 responses.
API keys authenticate the Workspace API and can also authenticate MCP clients. They are created and revoked in **Integrations → API Keys**.
## Key format and storage
Keys look like `bice_` followed by a random secret. Black Ice stores only a hash plus a short prefix, so the full key is shown **once**, at creation. If you lose it, revoke the key and create a new one.
## Key scopes (access level)
Each key is created with an **access level**:
| Access level | Can read (`GET /query-ontology`) | Can write (`POST /mutate-ontology`) |
|---|---|---|
| **Read only** | ✅ | ❌ — returns `403` with `"code": "insufficient_scope"` |
| **Read and write** | ✅ | ✅ |
Use a **read-only** key for one-directional integrations that pull the ontology as reference data — a TMS, CMS, or RAG pipeline that never writes back. This keeps the blast radius small: even if the key leaks, no one can modify the ontology with it.
## What the list shows
| Column | Meaning |
|---|---|
| **Label** | Your description of where the key is used |
| **Access level** | Read only, or Read and write |
| **Prefix** | The first characters of the key, to match it against your secret manager |
| **Last used** | When a request last authenticated with this key |
| **Created** | When the key was generated |
Use one key per system (`ci`, `tms-connector`, `internal-bot`) so you can revoke a single integration without breaking the others.
## Rotating a key
1. Create the replacement key first with the **same access level** and give it the same label plus a version suffix.
2. Deploy the new key to your integration.
3. Confirm the new key shows a recent **Last used** value.
4. Revoke the old key.
Rotate at least annually, and immediately if a key may have been exposed in logs, a repo, or a shared document.
## Revoking
Click the trash icon next to the key. Revocation is immediate and cannot be undone — any caller using it starts receiving `401 Unauthorized`.
## Troubleshooting
| Response | Meaning | Fix |
|---|---|---|
| `401 Unauthorized` | Key missing, malformed, or revoked | Check the `x-api-key` header; create a new key |
| `403 insufficient_scope` | Read-only key used for a write | Generate a read-and-write key for this integration |
| `403 Forbidden` | The key's workspace does not contain the requested resource | Use a key from the right workspace |
| `429 Too Many Requests` | Plan rate limit hit | Back off using the `Retry-After` header; see [rate limits](/docs/integrations/rate-limits) |
| `413` / payload error | Request body above the 1 MB cap | Split the batch into smaller requests |
Every response includes `X-RateLimit-Limit` and `X-RateLimit-Remaining`, so your client can throttle before it gets rejected.
## Security notes
- Never embed a key in frontend code. A read-and-write key grants full workspace read/write; a read-only key grants read-only access. Use the narrowest scope that works.
- Store keys in a secret manager, not in `.env` files committed to a repo.
- Keys are scoped to a single workspace, so a leaked key cannot reach your other workspaces.
---
# Privacy by design in Black Ice integrations
> How to connect Black Ice while minimizing data movement, using read-only access, and keeping customer ontology data out of model training.
Black Ice treats ontology data as sensitive operational knowledge: product strategy, market rules, terminology decisions, and brand voice. Integrations should pull only what they need, with the least privilege that can do the job.
## Recommended pattern
For translation platforms, AI agents, internal tools, or reporting systems that only need Black Ice as a source of truth, use a one-directional pull:
1. Keep all ontology edits in Black Ice.
2. Create a dedicated **read-only API key** for the integration.
3. Store the key in your secrets manager.
4. Pull the ontology through the Workspace API or MCP.
5. Keep any downstream copy read-only reference data.
6. Revoke the key when the integration is retired.
This gives the consuming system the context it needs without holding a credential that can modify the workspace.
## Use read-only API keys
Create one key per system under **Integrations → API Keys** and choose **Read only**.
A read-only key can call `GET /functions/v1/query-ontology`, including pagination, locale filtering, and incremental `since` pulls. It cannot call write endpoints. If a read-only key is used against a mutation endpoint, Black Ice returns:
```json
{
"error": "insufficient_scope",
"message": "This API key is read-only. Create a read/write key to modify the ontology."
}
```
Prefer one key per integration (`tms-production`, `ci-readonly`, `analytics-export`) so each one can be rotated or revoked independently.
## Prefer MCP when an AI client only needs context
The Black Ice MCP server is read-only by design. It lets AI clients consult approved terminology, market availability, definitions, and relationships without granting write access to the ontology.
Use MCP when the consuming tool is an assistant, IDE, or agent that needs guidance before it writes. Use the Workspace API when you need bulk export, pagination, scheduled sync, or a service-to-service integration.
## Minimize downstream copies
When your platform stores an internal reference copy, avoid carrying fields it does not need. For most one-way terminology integrations, start with:
- concept ID
- concept name and definition
- class/category
- source term
- target term by locale
- status (`approved`, `pending`, `rejected`, `deprecated`)
- relationships needed by the workflow
- `updated_at` for incremental refresh
Avoid storing teammate names, notes, or internal reasoning unless the consuming workflow truly needs provenance.
## Keep customer data out of model training
Black Ice customer content is not used to train Black Ice models or third-party models. When you connect an AI tool, treat the downstream system the same way: pass ontology context only for the active task, avoid prompt logging where possible, and do not reuse customer ontology data to train your own models unless your customer has separately authorized it.
## GitHub Sync is opt-in
GitHub Sync is off by default. If enabled, it exports ontology files only to a repository selected and controlled by the workspace. Keep it disabled when your privacy policy requires all pulls to happen through the API or MCP.
## Operational checklist
- Use read-only keys for one-way integrations.
- Store keys in a secrets manager, never in frontend code.
- Rotate keys at least annually and after personnel or vendor changes.
- Revoke unused OAuth clients and API keys.
- Use incremental `since` pulls to reduce payload size.
- Subscribe to sub-processor change notices if your review process requires advance notice.
- Request the DPA for the contractual no-training, retention, and transfer commitments.
## Related pages
- [Workspace API access](/docs/integrations/workspace-api-access)
- [Pulling the ontology into your stack](/docs/integrations/ontology-pull-integration)
- [Managing and troubleshooting API keys](/docs/integrations/api-key-management)
- [Security & Trust Center](/legal/security)
- [Privacy Policy](/privacy)
- [Sub-processors](/legal/sub-processors)
---
> Fine-grained tokens **expire**. Note the expiry date — when the token lapses, syncs start failing with a permission error until you generate and save a new one.
### 2. Scope it to the repository and grant Contents: Read and write
Under **Repository access**, choose **Only select repositories** and select the repository you want to sync to. Then under **Permissions → Repository permissions**, add **Contents** and set it to **Read and write**. GitHub adds **Metadata: Read-only** automatically — that is expected.
**"Public repositories (read-only)" will not work** — Black Ice cannot commit with a read-only token.
Click **Generate token** and copy the `github_pat_...` value. GitHub shows it only once.
> Using a classic token instead? It needs the full `repo` scope.
## Setting up GitHub Sync
1. Go to **Settings** in your workspace
2. Open the **GitHub Sync** section
3. Paste the personal access token you just created
4. Specify the repository owner, name, branch, and target path
5. Choose an approval filter — sync all terms, only approved terms, or approved + pending
6. Enable **Auto-sync** to push changes automatically whenever terms are updated
7. Click **Sync now** to verify the connection
## How AI agents consume the ontology
### Direct file access (Claude Code, Cursor, etc.)
If your AI agent runs inside the repo (e.g. Claude Code with a `CLAUDE.md` file), it reads the ontology files directly from disk. No API calls needed.
```
# The agent reads CLAUDE.md first, then navigates the ontology structure
# to find the relevant class, market, and terminology files.
```
If you also want the agent to *query or update* Black Ice live during the same session, connect the [MCP server](/docs/integrations/claude-desktop-mcp) in parallel.
### GitHub API consumption
External systems can fetch ontology files programmatically via the GitHub API:
```bash
# Fetch the agent instructions
curl -H "Authorization: token YOUR_GITHUB_TOKEN" \
https://api.github.com/repos/OWNER/REPO/contents/ontology/CLAUDE.md
# Fetch a specific market profile
curl -H "Authorization: token YOUR_GITHUB_TOKEN" \
https://api.github.com/repos/OWNER/REPO/contents/ontology/markets/de-DE.md
# Fetch all terminology for a locale
curl -H "Authorization: token YOUR_GITHUB_TOKEN" \
https://api.github.com/repos/OWNER/REPO/contents/ontology/terminology/de-DE/
```
### GitHub Actions integration
Trigger downstream workflows whenever the ontology is updated:
```yaml
# .github/workflows/on-ontology-update.yml
on:
push:
paths:
- 'ontology/**'
jobs:
process-ontology:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Process updated ontology
run: |
echo "Ontology updated — trigger localization pipeline"
# Your pipeline logic here
```
## When Markdown files are the right choice
Black Ice exposes a REST API and an MCP server as well — files are not a workaround for a missing API, they are a different delivery model with different strengths:
- **Diff-friendly** — every ontology change creates a readable Git diff, so terminology updates can be reviewed and rolled back like code
- **Repo-native** — agents that already run inside your repository read the ontology with no extra auth, client, or network round-trip
- **Offline-capable** — once cloned, the ontology works without connectivity
- **Prose over payloads** — Markdown market profiles and translation policies read well as LLM context
- **Existing infrastructure** — branch protection, CODEOWNERS, webhooks, and GitHub Actions apply to the ontology for free
And the trade-offs, which is where the API and MCP win:
- Files are a **snapshot**, not live state — they are only as current as the last sync
- GitHub Sync is **one-way**: changes made in the repo do not flow back into Black Ice
- No filtering or querying at request time — you read whole files
## Troubleshooting
**"Sync failed" with a permission error** — the token is missing **Contents: Read and write**, or it is scoped to a different repository. Regenerate it following the steps above.
**Sync worked before and now fails** — the fine-grained token has most likely expired. Generate a new one and save it in Integrations → GitHub.
**Repository or branch not found** — check the owner, repository name, and branch for typos, and confirm the token repository access includes that repo. The branch must already exist.
**Sync succeeds but few or no terms appear** — your approval filter is excluding them. Switch it to "approved + pending" or "all terms" to confirm.
**Private repository in an organisation** — the organisation may need to approve fine-grained tokens. Ask an owner to enable them under the organisation personal access token policy.
## Availability
GitHub Sync is available on the **Builder** tier. See [Plans and Pricing](/docs/getting-started/plans-and-pricing) for details.
## Token expiry at a glance
Once a token is saved, the **GitHub Personal Access Token** field shows when it expires:
- **Expires in N days** — normal state, read from GitHub when the token is saved or used.
- **Expires in N days** (amber) — fewer than 14 days left; generate a replacement soon.
- **Expired** — syncing will fail until you paste a new token.
Fine-grained tokens always expire (90 days by default), so put a reminder in your calendar or pick a longer expiry when you create one.
---
# Black Ice + AI: What Your Ontology Unlocks
> How to feed your Black Ice ontology to Claude, ChatGPT, Gemini, and local models via MCP, the REST API, or GitHub Sync — with a comparison of access paths.
Black Ice governs meaning. AI scales it. These are not two separate tools — they're a stack. Once your ontology lives in Black Ice, every AI model you connect to it stops guessing and starts reasoning from structured truth.
## How models reach your ontology
Before picking a model, pick an access path. There are three, and any model can use at least one of them:
| Path | What it is | Freshness | Tier |
|---|---|---|---|
| **MCP** | Your workspace exposed as tools an MCP client calls directly (Claude Desktop, Claude Code, Cursor) | Live, real time | All plans |
| **API** | REST endpoints (`query-ontology`, `mutate-ontology`) and the Workspace API, called with a scoped key | Live, on demand | All plans |
| **GitHub Sync** | A versioned Markdown bundle pushed to a repo you own | Snapshot per sync | Builder |
A file export is no longer the only way in. Nothing below requires you to paste an ontology into a prompt unless you want to.
→ [Integrations Overview](/docs/integrations/integrations-overview) · [MCP setup](/docs/integrations/claude-desktop-mcp) · [API Reference](/docs/integrations/api-reference) · [GitHub Sync](/docs/integrations/github-sync)
---
## Claude ★ Recommended Integration
### Why Claude is the recommended AI for Black Ice
Claude's extended context window, instruction-following precision, and native support for both MCP and repository workflows make it the natural partner for ontology-fed work. Claude Desktop and Claude Code connect to Black Ice over **MCP**, so they query your live workspace — concepts, terms, market rules, relationships — without any export step. For agents that live in a repo, **GitHub Sync** gives Claude Code a diff-able Markdown bundle it can read offline, review in pull requests, and feed to CI.
> **Recommended setup:** Human in the loop, asking questions or drafting content → **MCP**. Agent running in a repo or CI pipeline → **GitHub Sync**. Many teams run both: MCP for interactive sessions, the bundle as the versioned artifact.
### 01 — Market-Specific Content Generation — No TMS Required
Connect Claude to your workspace over MCP (or point Claude Projects at the GitHub bundle). Claude now knows your approved terms, market availability rules, brand voice per locale, and forbidden expressions — and over MCP it's always current, because it reads at query time. Ask it to write a landing page for Spain. It doesn't translate — it writes, correctly, from first principles. No briefing doc. No terminology spreadsheet.
> **The difference:** Generic Claude writes fluent Spanish. Ontology-fed Claude writes *your* Spanish — for *that* market.
### 02 — Localization QA That Knows Your Product
Run Claude against translated strings with the ontology attached. It flags terminology inconsistencies not against a generic dictionary but against your defined concepts — catching the translator who used "Plan Familiar" when your market DNA specifies "Plan Familia," or who left a feature name untranslated that you've explicitly approved as an anglicism. The MCP `validate_translation` and `check_term` tools do exactly this in one call.
> **The difference:** Rule-based QA checks patterns. Ontology-fed Claude checks meaning.
### 03 — Sprint-Based Delta Localization
Your product shipped a new feature. Three concepts changed. Query the API for what's new, modified, stable, or deprecated. Claude gets only the delta, with full semantic context, and localizes precisely what changed. Nothing more, nothing less. No re-translation of stable strings. No fuzzy-match guesswork.
> **The difference:** Traditional workflows re-translate everything. This one reasons about change.
### 04 — Multi-Project Consistency from a Single Ontology
One workspace, multiple Claude Projects: marketing copy, developer docs, support content, UI strings. All reading from the same semantic source — over MCP they see updates the moment you make them; over GitHub Sync they see them on the next push. Consistency isn't enforced by style guides that get ignored — it's structural.
> **The difference:** Style guides are read once and forgotten. Ontology constraints are active every time Claude runs.
### 05 — Agentic Pipelines with Claude Code
Claude Code can talk to Black Ice two ways: over MCP for live reads and writes, or against the synced repo bundle for a deterministic, reviewable artifact. It applies market rules, generates localized variants, and commits outputs — no UI, no manual handoffs. Three connected layers: Figma (design), GitHub (strings), Black Ice (meaning governance).
> **The difference:** You're not prompting a chatbot. You're running a governed localization agent.
---
## ChatGPT / GPT-4o — Supported Integration
### 01 — Custom GPT Actions against the API
Give a Custom GPT an Action that calls `query-ontology` with a scoped Black Ice API key. The GPT looks terminology up on demand instead of carrying a stale knowledge file, and can write back through `mutate-ontology` if you allow it. This is the closest OpenAI equivalent to the MCP experience, and it works on every plan.
> **Best for:** teams standardised on ChatGPT who want live, governed lookups rather than a snapshot.
### 02 — Knowledge-File GPT for Non-Technical Teams
If nobody wants to configure an Action, upload a Black Ice export as a knowledge file inside a Custom GPT and reference your terminology rules and market definitions in the system prompt. Zero setup, no keys — at the cost of the ontology being a snapshot you have to refresh manually.
> **Best for:** non-technical teams who need governed content generation without any pipeline work.
### 03 — Structured Output in API Pipelines
Use structured/JSON output to generate translation payloads that map directly to your concept IDs. Pull source context from `query-ontology`, hand it to the model, and write results back through `mutate-ontology` or your own store. Useful when output structure matters as much as linguistic quality.
> **Best for:** API-based pipelines where output structure is critical.
---
## Gemini — Supported Integration
### 01 — Large-Document Ontology Ingestion
Gemini's very large context window means you can load an entire Black Ice ontology — concept definitions, market rules, relationship maps, glossaries — in a single prompt. No chunking, no retrieval logic, no RAG overhead. Fetch it fresh from the API at run time rather than pasting a stale copy.
> **Best for:** large enterprise ontologies where context size would be a constraint with other models.
### 02 — Google Workspace Localization Workflows
If your content team lives in Google Docs and Sheets, Gemini's native Workspace integration brings your ontology into existing editorial workflows. An Apps Script call to the Black Ice API can pull the current terminology for a locale into the sheet your reviewers already use.
> **Best for:** teams already embedded in Google Workspace who need governance without workflow disruption.
### 03 — Multimodal Localization QA
Feed screenshots of localized UI alongside your terminology rules and ask Gemini to flag visual string inconsistencies — truncation, untranslated labels, wrong register for the market. Useful for mobile localization QA where the rendered string matters as much as the source string.
> **Best for:** UI and mobile localization QA where visual context matters.
---
## Local Models (Ollama) — Private Deployment
### 01 — Self-Hosted Models Calling the API
A local model doesn't have to work from a static file. If your infrastructure can reach the internet, a small wrapper can call `query-ontology` before each batch so the model always reasons over current terminology, while generation itself never leaves your hardware.
> **Best for:** private inference where the *content* must stay in-house but ontology lookups are acceptable.
### 02 — Air-Gapped Terminology Enforcement
Fully isolated? Export the ontology as Markdown, JSON, or the GitHub bundle and load it into a local model via Ollama — Mistral, LLaMA, Phi, or Qwen all handle structured context reasonably well. Nothing leaves your network. For regulated industries — legal, medical, financial — this is often the only viable route.
> **Best for:** regulated industries or any team where data leaving the building is not an option.
### 03 — High-Volume Batch Localization at Zero API Cost
Running 50,000 strings through a cloud API gets expensive fast. Running them through a local model costs compute, not per-token pricing. Load your ontology once, batch your source strings, run on your own hardware. Quality will be lower than Claude on complex tasks — but for high-volume, lower-complexity sets with strong ontology grounding, the trade-off is often acceptable.
> **Best for:** large-volume, lower-complexity localization where cost per token is a primary constraint.
### 04 — Model Routing: Local for Volume, Claude for Quality
The most pragmatic architecture: route high-volume, stable, low-ambiguity strings to a local model for cost efficiency. Route complex, market-sensitive, brand-critical strings to Claude for quality and nuance. Black Ice is the shared semantic layer across both, reachable by either over the same API.
> **The difference:** The ontology is model-agnostic. The semantic layer doesn't care who's executing — it just enforces the rules.
---
## Integration Comparison
| Capability | Claude ★ | ChatGPT | Gemini | Local (Ollama) |
|---|---|---|---|---|
| Native MCP client | ✓ Desktop, Code, Cursor | ~ client-dependent | ✗ | ~ with a wrapper |
| Calls the Black Ice API | ✓ | ✓ GPT Actions | ✓ via scripts | ✓ if network allowed |
| Reads the GitHub Sync bundle | ✓ Claude Code, Projects | ~ manual upload | ~ manual upload | ✓ local clone |
| Live data without an export step | ✓ MCP | ✓ Actions | ~ scripted fetch | ~ scripted fetch |
| Writes back to the ontology | ✓ MCP + API | ✓ API | ~ API | ~ API |
| Agentic file & repo operations | ✓ Claude Code | ✗ | ✗ | ~ custom tooling |
| Very large ontology in one prompt | ✓ | ~ | ✓ Largest window | ~ model-dependent |
| Multi-market logic in a single prompt | ✓ Excellent | ~ Good | ~ Good | ✗ Struggles |
| Multimodal UI / screenshot QA | ✓ | ✓ | ✓ Strong | ~ limited models |
| Generation stays on-premise | ✗ | ✗ | ✗ | ✓ Full control |
| Zero per-token cost at scale | ✗ | ✗ | ✗ | ✓ |
## Rate limits and freshness
MCP and API calls are capped per workspace per minute — Free 60 reads / 30 writes, Pro 300 / 120, Builder 1,000 / 400 — with `X-RateLimit-*` headers on every response. That's ample for interactive sessions and most pipelines, but a job that resolves terminology for tens of thousands of strings should read the GitHub Sync bundle once instead of querying per string. Live access and bulk access are different tools; use both.
→ [API & MCP rate limits](/docs/integrations/rate-limits)
## Next steps
- [Connect Claude Desktop or Cursor via MCP](/docs/integrations/claude-desktop-mcp)
- [Generate API keys and call the REST endpoints](/docs/integrations/api-reference)
- [Set up GitHub Sync](/docs/integrations/github-sync)
- [Compare all integration paths](/docs/integrations/integrations-overview)
---
# Connect Claude to your workspace (step by step)
> Step-by-step guide with screenshots: add Black Ice as a custom connector in Claude, authorize the workspace over OAuth, and start asking Claude about your terminology.
Connect Claude to your Black Ice workspace in about three minutes. Once connected, Claude consults your ontology live — approved terms, forbidden variants, market availability, voice and tone — without you pasting anything into the chat.
> **Any plan.** The MCP connector is available on Free, Pro, and Builder. Access is read-only (`mcp:read`) and scoped to one workspace per connection.
## Before you start
- A Black Ice account with at least one workspace.
- Claude (Desktop or web) on a plan that allows custom connectors.
- That's it. The OAuth path below needs **no API key**.
---
## Step 1 — Open Connectors in Claude
Click your name in the bottom-left corner, choose **Settings**, then **Connectors** in the sidebar.
## Step 2 — Add a custom connector
Open the **Add** dropdown in the top right and choose **Add custom connector**.
## Step 3 — Paste the Black Ice MCP URL
Give it the name **Black Ice** and paste this URL:
```text
https://mcp.black-ice.ai/mcp
```
Leave the OAuth Client ID and Client Secret fields empty — Black Ice supports Dynamic Client Registration, so Claude registers itself automatically. Save.
## Step 4 — Connect
The connector appears with a **Connect** button and the note "You are not connected to Black Ice yet." Click it.
## Step 5 — Authorize and pick a workspace
A Black Ice authorization page opens in your browser. Sign in if you aren't already, then pick which workspace Claude should read. Click **Allow access**.
> **One workspace per connection.** If you work across several workspaces, add a second custom connector and authorize the other workspace there. You can also switch later — see [Switching the workspace Claude or Cursor uses](/docs/integrations/switch-mcp-workspace).
## Step 6 — Review the tools
Back in Claude, the connector now lists seven read-only tools. Set **Always allow** if you want Claude to use them without asking each time.
| Tool | What it answers |
| --- | --- |
| Check approved term | What is the approved term for this concept in this locale? |
| Validate translation draft | Does this draft use forbidden or non-preferred variants? |
| Check market availability | Is this concept available in that market, and under what conditions? |
| List concepts | What concepts exist, optionally filtered by class? |
| List concept classes | What taxonomy classes does this workspace use? |
| List semantic relationships | What is related to this concept, and how? |
| Get market profile | What is the voice, tone, and culture DNA for this locale? |
## Step 7 — Try it
Open a new conversation and ask something only your ontology can answer:
> _"Using Black Ice, what's the approved Spanish (`es-es`) term for MIDI Editor, and which variants are forbidden?"_
If Claude answers with your approved terminology and flags the forbidden variant, you're connected. For more, jump to the [ready-to-copy prompt library](#ready-to-copy-prompts-for-localization-workflows) below.
---
## Ready-to-copy prompts for localization workflows
Copy any prompt below, swap the `