# 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)** — find Black Ice in Connectors → Discover/Search, or add it 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).
**Let your assistant spot new terms (optional).** Once an owner or admin turns on candidate suggestions on the Integrations page, with an editor/admin/owner OAuth sign-in or a Suggest only / Read and write key, your assistant can call `suggest_candidates` to add words to the [Candidates review queue](/docs/features/candidate-review-workflow). A terminologist still decides; nothing becomes binding automatically.
## 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.
**Do I need a separate subscription for each MCP connection?**
No. Your plan covers the whole workspace, not individual connections. On every plan, including Free, you can connect as many AI assistants as you like (Claude, Cursor or any other MCP client). On Free, all connections and API keys share 10,000 calls a month; Pro and Builder have no monthly call limit. Teammates invited to a Builder workspace use the owner's plan and don't need their own subscription.
## 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.
**The MCP connector is read-only by default.** An owner or admin can optionally turn on `suggest_candidates`, which only adds unconfirmed entries to the Candidates review queue. It requires a read-and-write key or an editor sign-in, and cannot approve, change or delete governed terminology.
## 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, use the row menu **⋮ → Market overrides**, or its existing override link. 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.
## Classes Manager controls
Edit default translation policy with the inline selector. The concept count opens Concepts filtered to that class. Use the row menu for Edit, Delete, and Market overrides; use the page header for Add Class and Bulk Import.
---
# 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.
## Finding and reviewing concepts
Search matches the concept name or ID, case-insensitively—not descriptions or translated terms. Every search word must occur somewhere in the concept name; IDs match the complete query as a substring. Use Market and Class selectors, then Availability and the target-market Status filter to narrow results. Approval status and availability are separate. Selecting concepts exposes bulk availability/status actions and **Send for Approval**; the general approval action remains in the page menu. Open a concept for source-first market rows and each term's full History.
---
# 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).
## Market-specific labels
Choose a market to inspect its label and availability. Without a target label, the node shows **No label in this market** with a dashed outline. **Source name shown** identifies a source-name fallback used only for reference; it does not mean the target label is approved or the offering is available there.
---
# 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") |
| **Notes** | Internal notes for translators or reviewers |
| **Status** | Pending, Approved, Rejected, or Deprecated; separate from availability |
| **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). Every change is kept as a numbered version in the term's [decision history](/docs/features/decision-history).
## 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
## Approve versus deprecate
Use **Approve** to accept a term. Use **Deprecate** to retire terminology, not to record market unavailability. The dialog asks whether the old spelling should become a forbidden variant (selected by default). An optional replacement is saved as **Pending**, in a separate history entry after deprecation. Source and target terms can be deprecated independently; deprecating the source does not automatically retire target labels. Open **History** on any term row to review all recorded versions.
---
# Decision history
> Every change to a term is kept as a numbered version: what changed, who decided, when and why.
Every term in Black Ice keeps a **decision history**: a permanent, numbered record of each change — what changed, who made the decision, when, and why. It's what turns a glossary into a governed record your AI tools and auditors can trust.
## Opening the history
1. Open a concept.
2. On any source or target term row, click **History**.
3. A timeline opens, newest version first.
The current version number (for example **v3**) appears on the term card next to the approval stamp.
## What each entry shows
| Item | Description |
|------|-------------|
| **Version** | A running number per term (v1, v2, v3…) |
| **What changed** | Created, term changed (old → new), status changed, availability changed, or notes/variants updated |
| **Reasoning** | The "Why this decision?" note, if one was given |
| **Who** | The member who made the change, with their photo |
| **When** | Date and time of the change |
| **Source** | Shown when the change didn't come from a normal edit (see below) |
## Where changes come from
Every path that changes a term is recorded automatically — there's no way to skip it.
| Source label | Meaning |
|--------------|---------|
| *(none)* | Edited directly in the app |
| **Import** | Created or updated by a CSV/Excel or ontology import |
| **Bulk action** | Changed through a bulk action, such as bulk availability |
| **Approval link** | Decided by an external reviewer through an [approval link](/docs/features/approval-workflows) |
| **Partner agency** | Validated by a [partner agency](/docs/features/hiring-a-partner-agency); the note reads "Validated by ()" |
| **API / MCP** | Changed through the Workspace API or an MCP connection |
| **Before history tracking** | A baseline v1 for terms that existed before history was introduced |
## Recording why
When you change a term's value or status, the edit form shows an optional **Why this decision?** field. Whatever you write is saved with that version and shown in the history.
It's optional, but it's what makes the history useful months later. A good note explains the reason, not the change — for example: *"Stays English. The scene says 'mastering', and 'masterizar' for the verb."*
## Who can see it
- All workspace members, including Viewers, can read the history.
- Nobody — not even owners or admins — can edit or delete history entries.
## History vs. activity log
| | Decision history | [Activity log](/docs/features/activity-log) |
|---|---|---|
| Scope | One term | Whole workspace |
| Detail | Old → new value, reasoning, version | One-line summary |
| Retention | Permanent | 90 days |
| External decisions | Included (approval links, partners, API) | In-app changes only |
## Limitations
- History starts from when tracking was introduced. Older terms have a single "Before history tracking" baseline, because earlier values were never stored.
- History entries are kept even if a term is later deleted, so past decisions remain on record.
---
# 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** | Recorded as available in this market; term approval is a separate decision |
| **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.
**Terminology retirement** — Use status **Deprecated** to retire wording. Use availability **Not Available** when the offering is unavailable in that market; these are separate controls.
## Missing labels are not availability
A missing target label does not inherit the source term's availability or approval. Knowledge Graph marks it **No label in this market**, with **Source name shown** when a source name is displayed for reference. This is not an approved untranslated label. In Concepts, the coverage/status filter groups terms that are neither Approved nor Pending as Missing, including absent labels and other statuses.
---
# Candidate review workflow
> Review extracted terms against five tests before they earn a place in the ontology.
# Candidate review workflow
A **candidate** is a word or phrase your pipeline extracted (from UI strings, docs, support tickets) that *might* deserve a place in the ontology. Candidates are **not** part of the ontology: they are never returned by the Read API, the MCP server, or GitHub Sync.
Black Ice holds no model. Extraction runs in **your** pipeline; Black Ice stores the candidates and records the human decision.
```text
Your extraction --> Candidates queue --> Approve --> new concept, source term = Pending
+-> Merge --> added as a synonym (allowed variant)
+-> Reject --> rejection list (suppressed next time)
```
## The five tests
Open a candidate from **Candidates** in the sidebar and mark each test Pass, Unsure or Fail. The answers are saved with the decision.
1. **Unique** — is it already there under another name? This is the primary gate. If you can't articulate a real difference in meaning from an existing concept, merge it as a synonym. The dialog lists similar existing concepts.
2. **Distinct** — does it have a clean boundary with its neighbours?
3. **Necessary** — is it costly to miss? Does a translator guess, a support ticket get filed, legal risk appear, a UI label stop matching docs?
4. **Stable** — is the meaning settled? If not, wait (Needs definition work) or approve as **provisional**.
5. **Recurring** — will it come up again across products, content types or languages?
> A candidate belongs when it is unique, distinct, necessary, stable and recurring. Miss unique or necessary and the entry is almost always noise. The other three can usually be fixed with better definition work.
## Decisions
- **Approve** — creates the concept with its source term as **Pending**, ready for target-term work. Provenance is kept on the concept.
- **Merge as synonym** — adds the word to an existing concept's allowed variants.
- **Needs definition work** — keeps it out of the main queue with a note.
- **Reject** — requires a reason (not unique, not distinct, not necessary, not stable, not recurring, other).
## The rejection list
Rejected words are remembered per workspace and locale. When your pipeline sends the same word again it is **suppressed** — only its counters update. It returns to the queue as **Resurfaced** only when its frequency reaches a multiple (default **3×**) of its frequency at rejection. Change the multiple on the Rejected tab.
## Confidence scores
Candidates are ordered by confidence, then frequency. Confidence orders the queue; it never replaces the tests.
## Acceptance rate
The Candidates page shows acceptance per source for the last 90 days, plus the most common failure. **If fewer than one in five candidates is accepted, your extraction prompt is too permissive** — it is collecting vocabulary instead of concepts.
## Start narrow
Run extraction on one product's UI strings first, tune the prompt against what the terminologist actually accepts, then add sources. Use a distinct `source` label per source so acceptance is tracked separately.
## Sending candidates
Use a **Suggest only** API key (or a **Read and write** key):
```bash
curl -X POST https:///functions/v1/mutate-ontology \
-H "x-api-key: bice_..." -H "Content-Type: application/json" \
-d '{
"candidates": [
{
"term": "Noa Notes",
"locale_code": "en-us",
"source": "Product A UI strings",
"frequency": 14,
"confidence": 0.82,
"class_name": "Feature",
"definition": "AI note-taking assistant for consultations.",
"provenance": [{ "file": "app/strings.json", "key": "notes.title", "url": "https://github.com/acme/app/blob/main/app/strings.json", "snippet": "Open Noa Notes" }]
}
]
}'
```
Up to 500 candidates per request. The response reports `created`, `updated`, `suppressed` (on the rejection list) and `resurfaced`. Only `term` and `locale_code` are required.
You can also import a CSV from the Candidates page with columns `term, locale_code, source, frequency, confidence, provenance_url, definition`.
## Adding a candidate manually
Spotted a term yourself — in a support ticket, a UI string, a review? Click **Add candidate** on the Candidates page. Enter the term and market (defaults to your source market), and optionally a suggested class, a proposed definition, and where you found it. Manual entries are labelled **manual**, so they appear as their own source in acceptance stats. The usual rules apply: words on the rejection list stay hidden, and a word already in the queue has its times-seen count increased instead of being duplicated.
## Doing the definition work
Mark a candidate **Needs definition work** when the idea is right but the definition isn't ready. Later, open it from the Needs definition work tab: the proposed definition and suggested class are editable. Rewrite the definition, re-run the Distinct and Stable tests, then click **Save draft** to keep working later — or go straight to **Approve as new concept**, which creates the concept with the definition as you wrote it.
## Suggest candidates from your AI assistant
If you connect Claude, Cursor or another assistant through the [MCP connector](/docs/integrations/connect-claude-mcp), it can call the `suggest_candidates` tool to send words it spots — for example while reviewing UI strings or support tickets — straight into this queue.
**It is off by default.** A workspace owner or admin turns it on in **Integrations → MCP → Allow AI assistants to suggest candidates**. While it is off, assistants do not see the candidate tool. Other optional writing tools have separate switches; the default connection is read-only.
Black Ice runs no AI of its own. Your assistant (Claude, Cursor, or another MCP client) does the spotting; Black Ice only stores its suggestions in the review queue, and people decide.
- **Who can use it:** a Suggest only or Read and write API key, or a Claude sign-in by an editor, admin or owner. Read-only keys and viewers get a clear refusal.
- **What it sends:** term, market, optional definition, suggested class, a link or note on where it was found, and an optional confidence score. Up to 50 per call.
- **Same rules:** rejected words stay hidden unless their frequency grows by your resurface multiplier; repeats raise "times seen" instead of creating duplicates.
- **Labelled separately:** entries arrive with the source `ai_assistant` (plus the client, when known), so they get their own row in *Acceptance by source*. If fewer than one in five is accepted, tighten the prompt you give the assistant.
- **Nothing becomes binding:** the tool cannot approve, merge, reject or edit anything. Only approved terms are binding.
Example prompt:
```
Read these UI strings and suggest to Black Ice any product-specific terms that
are not already in the ontology. Check with list_concepts first, then call
suggest_candidates with a note saying which file each term came from.
```
## Example: Claude Code suggesting candidates
*Claude Code read a product post and suggested 8 words. They land in the Queue as unconfirmed candidates until a terminologist reviews them.*
1. An owner or admin turns on **Allow AI assistants to suggest candidates** under Integrations → MCP.
2. Connect Claude Code with a Suggest only or Read and write API key, or sign in as an editor, admin or owner.
3. Paste a text and ask: *"Suggest candidates from this text using suggest_candidates."*
The assistant skipped terms that were already approved and flagged wording that differs from approved terms. Those are helpful hints, but only the Queue decides what becomes terminology.
## Audit trail
Candidate decisions (approve, merge, reject) are stored permanently with the five test answers, reason, note, who decided and when — rejected candidates are kept as suppression memory, independent of the 90-day activity log.
Each candidate also records **who proposed it**: the API key (label and prefix, kept even if the key is later revoked), the connected assistant, or the workspace member. You see it at the top of the review dialog. Candidates proposed before this was introduced show "Origin not recorded".
Owners and admins can export every decision with **Export decisions (CSV)** on the Candidates page, or via the `export-audit` endpoint (see [Managing API keys](/docs/integrations/api-key-management)).
> **Note:** replace `` with the endpoint URL shown in **Integrations → API Keys**.
> Screenshots illustrate the workflow and may show an earlier layout or a Read and write key. For candidate-only pipelines choose **Suggest only**; the current controls are in Integrations → MCP and Integrations → API Keys. Other optional writing tools have separate switches.
---
# AI writing tools
> Let Claude, Cursor or any MCP assistant make changes, with a switch per tool and human review for risky changes.
# AI writing tools
The AI connection is **read-only by default**. Owners and admins can turn on individual writing tools in **Integrations → MCP → AI writing tools**. Each tool has its own switch, and all are off until someone turns them on.
| Tool | What it does | How it lands |
|---|---|---|
| `set_concept_definition` | Add or rewrite a concept's definition | Applied directly |
| `propose_translation` | Add a target term for a market | Applied directly as **Pending**, never Approved. Refused if the market already has an approved term |
| `set_market_availability` | Available / planned / not available | **Waits for review** |
| `add_relationship` | Link two concepts with an existing type | **Waits for review** |
| `create_relationship_type` | New type, one-way or two-way (with inverse label) | **Waits for review** |
When any writing tool is on, assistants also get `list_my_proposals` to check the status of their changes.
## Who can use them
Read-and-write API keys, or a Claude sign-in by an editor, admin or owner. Read-only and Suggest only keys, and viewers, cannot use these ontology-writing tools. Suggest only keys can use the separately enabled candidate-suggestion tool.
## Reviewing changes
Open **AI changes** in the sidebar. Each item shows the current value, the proposed value, the assistant's reason and when it was sent. Editors, admins and owners can **Accept** or **Reject** it, with an optional note.
- If the value changed since the assistant proposed it, accepting is refused as **out of date**. Reject it instead.
- Proposals that nobody decides on expire after 30 days.
- Accepted term changes appear in the term's Decision history as **API / MCP**.
Assistants can never approve terms, delete anything, or change approved terminology. Every call counts toward your monthly call limit.
---
# Certification: booking and attendance
> One certification in two sessions: priority invitations, free accounts, booking, attendance, and certificates.
# Certification: booking and attendance
The December 2026 course is **one free certification in two live sessions**, on 3 and 10 December, 18:00–19:30 CET. There are **25 seats in total**, not 25 per session. One booking covers both. It is for localization, language, content, and knowledge professionals, engineers, and program leads working with multilingual AI. The sessions cover knowledge-graph creation and localization pipelines; they are not separate certifications for separate audiences.
## Priority invitations
Existing priority-list subscribers receive a 48-hour window to confirm a seat once invitations are sent. Being on the list is not a confirmed booking. Use **Reserve my seat** in the invitation and the **same email address** the invitation was sent to. During the priority window, a different email cannot claim that priority place. After the window, remaining places open for general booking.
## If you do not have an account
Create a **free Black Ice account** with the invitation email. The booking sign-in screen explains this requirement. Confirm your email, then return to the certification page; the booking destination is preserved and the reservation is attempted after sign-in. A confirmation email and **You're in (both sessions)** on the page confirm a successful booking. An account or email confirmation alone is not proof of a seat: booking can still fail if places are full or booking has closed. Normal sign-in without an explicit booking destination does not display a certification message.
## Booking and cancellation
Reserve once for both sessions. If the course is full, join its waitlist; a waitlist place is not a booked seat. You can cancel your booking from the certification page. Booking closes two hours before Session 1.
## Joining and completion
Confirmation and reminders are sent by email. Each session has its own private joining link; follow the link for the matching date. Attendance is recorded per session. You receive a completion certificate **only if you attend both sessions**; missing either session means no certificate. The certificate has its own verification page. This is a training completion certificate, not a security or compliance certification.
[View the certification and current booking status](/certifications).
---
# 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 codes
Market codes don't depend on upper or lower case: `es-ES`, `ES-es` and `es-es` give the same result. If you ask for a market that isn't set up in your workspace, you get a clear error instead of empty results.
---
# Market definitions
> Define voice, tone, grammar, and cultural conventions for each locale.
## What are market definitions?
Market definitions are structured guidelines attached to each market that describe **how** content should sound there. They go beyond translation rules to capture voice, cultural expectations and brand conventions specific to a region.
Each market's *Market Definitions* box starts with **ten default sections**, each designed to give translators, copywriters and AI tools the context they need. Owners and admins can customise these sections for the whole workspace — see [Customising the template](#customising-the-template).
## The ten default 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 |
Owners and admins can hide, rename, add or reorder these sections. Each section is free-form text: write as little or as much as you need, from a single line to detailed multi-paragraph guidance.
## Customising the template
Every workspace starts with the ten default sections above. Owners and admins can change them for the whole workspace: open **Markets**, then click **Definition template**.
- **Hide** any default section you don't use. Text already written in a hidden section is never deleted. It stays with the market, appears under *Hidden sections with content* when you edit it, and is left out of exports, GitHub Sync and the AI connection until you restore it.
- **Rename** a section heading to match your team's vocabulary.
- **Add your own sections**, with an optional hint for writers, such as *Audience: patients vs professionals*.
- **Reorder** sections with the up and down arrows.
- **Reset to the Black Ice default** at any time. Text already written in markets is kept.
Editors and viewers can see the template but can't change it.
### Step by step
1. Go to **Markets**. The **Definition template** button is at the top right, next to the search box. (It is not inside a market's Edit window, which only uses the template.)
2. Hide, rename, add or reorder sections.
3. Click **Save**. The template now applies to every market in the workspace.
4. Open any market with **Edit**. Its *Market Definitions* box follows the new sections and order.
Custom sections and your order carry through to Markdown and PDF exports, GitHub Sync, the Claude Code bundle, the read API and the AI connection (`get_market_profile` returns them in `definitionSections`).
## Editing market definitions
1. Go to **Markets** in the sidebar.
2. Click **Edit** on the market's row.
3. Write your guidelines in the *Market Definitions* box. It shows one heading per section, in your workspace template's order.
4. Click **Save**.
> Market definitions are workspace-scoped. Each workspace keeps its own definitions per market.
## Download and upload .md
You can draft definitions outside the app and load them in, or take them with you — useful for review in a repo, handing a draft to an agency, or copying one market's structure into another.
In a market's Edit window:
- **Download .md** writes one `## Heading` per section, in your template order. If the market has no definitions yet, you get an empty file with your workspace's headings, ready to fill in.
- **Upload .md** reads a `.md` or `.txt` file back:
- Headings are matched to your sections, including renamed ones. Files that still use the original ten names load too.
- Headings the template doesn't know become extra sections instead of being dropped.
- Text in hidden sections is kept.
- Files saved on Windows load correctly.
- If the market already has text, Black Ice asks before replacing it.
**No text is lost.** If you type or import a heading the template doesn't know, it is kept as an extra section in that market instead of being dropped.
## 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 market, with your template's sections and order.
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.
If your workspace has renamed or hidden these sections, apply the same advice to their equivalents.
---
# 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 **Markets in the sidebar**.
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.
---
# Hiring a partner agency
> Agree fixed per-market prices with a vetted agency, send terms for review, track spend, and see how requests are split when an agency covers only some markets.
# Hiring a partner agency
Black Ice lists vetted language agencies that can validate your target-market terminology. Open **Partners** in the sidebar.
## Who can use it
- Everyone in the workspace can browse the directory and see each agency's prices.
- **Pro and Builder** workspaces can work with agencies. Only **owners and admins** can agree to an agency's prices, set a budget or stop working with an agency. Editors can send terms to agencies already agreed.
## How pricing works
Each agency publishes a **fixed price per approved term for each market** (for example es-es €2.50, de-de €3.00). There are no quotes or email back-and-forth:
- You agree to the prices **once**. They are then fixed for your workspace, even if the agency later changes its public prices.
- You only pay for terms the agency's linguist **approves**. Rejected terms are not counted.
- The agency invoices you directly. Black Ice takes no part in payment and takes no commission; it only counts approved terms so both sides see the same figure.
## How it works
1. **Find an agency.** Filter by market and specialist domain. Each card shows the price per market.
2. **Click Work with this agency** and accept the prices. The agency moves to **My agencies**.
3. **Send for Approval.** From the agency's card in My agencies, or from any Send for Approval window, pick the agency. The window shows the estimated cost if all selected terms are approved.
4. **Track spend.** My agencies shows the agreed prices, what you have spent this month and in total, and a breakdown per month and market. Download it as CSV to check the agency's invoice.
5. **Optional budget.** Set a budget per agency. You get a warning at 80% and when you reach it; sending is never blocked.
6. **Track the result.** Decisions appear on the Approvals page, and each term's history shows **Partner agency — Validated by **.
**Emails:** when you agree to an agency's prices, the agency gets a "New client" email with your workspace name, who accepted, the agreed prices and your budget if set, and you get a copy as your record. If you end or resume the agreement, the agency is told. Budget changes send no email.
Earlier quote requests stay visible as an archive at the bottom of the Partners page.
## For agencies
Agencies can apply at [/partners/apply](/partners/apply). Every application is reviewed by hand. See the [Partner Agency Terms](/legal/partner-terms).
## Requests that cover several markets
When you send terms for more than one market, Black Ice creates **one review link per market** as well as the main link.
- **Market links:** each linguist opens the link for their market. They see only that market's terms, with the source term and definition for context, and can decide only those.
- **Decisions are locked:** once a term is decided, nobody can change it from a market link, not even the person who decided it.
- **Main link = read-only overview:** it shows progress per market, every decision with the reviewer's name and comment, and all the market links to forward. Nobody can approve or reject from it.
- **Reopening:** from the overview, the coordinator can reopen a decision for the **same linguist** (their market link works again for that term) or for a **new linguist** for a second opinion (a new link is created and copied). The earlier decision stays in the term's decision history.
- On the **Approvals** page, expand a request to see progress per market and copy each market link.
Requests with a single market work exactly as before: one link that decides everything.
## When an agency covers only some of your markets
The agency picker shows which selected markets each agency offers. A market the agency doesn't offer is marked **Not offered**. A market it offers that isn't in your agreed prices is marked **No agreed price**. Agencies that cover none of the selected markets can't be chosen, and a link takes you to Partners filtered to those markets.
If you pick an agency that covers only some of the markets, Black Ice **splits the request automatically**:
- terms for the covered markets go to the agency, and only those count towards its spend;
- the remaining terms get a **separate review link with no agency**, which you can share with your own reviewers.
The confirmation screen shows both links.
## Monthly statements (month close)
On the 1st of each month Black Ice closes the previous month for every active agency agreement. You and the agency receive the same statement by email: a statement number, approved terms per market, the agreed price and the total. The agency invoices you directly once a month, using the statement number as the reference. Black Ice does not bill or take payment.
Closed months appear under **Partners → Monthly statements**, where you can download a CSV and mark each one as *Invoice received* or *Paid*. Closed statements never change; a decision reopened later counts in the month it is decided again.
---
# 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. Invite team members and control what each person can do. Access rules are enforced by the backend, not only hidden in the interface.
## Roles
Every workspace has exactly **one Owner**. Everyone else is an Admin, Editor or Viewer.
| Role | In short |
|------|----------|
| **Owner** | Full control, including billing, GitHub Sync and transferring ownership |
| **Admin** | Runs the team and workspace settings, and edits all ontology data |
| **Editor** | Creates and edits ontology data and reviews candidates |
| **Viewer** | Read-only access to the workspace's ontology |
## Who can do what
| Action | Owner | Admin | Editor | Viewer |
|---|:-:|:-:|:-:|:-:|
| View concepts, terms, markets, relationships, activity | Yes | Yes | Yes | Yes |
| Create, edit and delete concepts, terms, classes, relationships | Yes | Yes | Yes | — |
| Import and bulk-edit (CSV/Excel, batch availability) | Yes | Yes | Yes | — |
| Send terms for approval | Yes | Yes | Yes | — |
| Review candidates (approve, merge, reject) | Yes | Yes | Yes | — |
| Create and revoke API keys | Yes | Yes | Yes | — |
| Edit the Market Definition template | Yes | Yes | — | — |
| Allow AI assistants to suggest candidates | Yes | Yes | — | — |
| Invite, remove and change roles of members | Yes | Yes | — | — |
| Documents & Compliance (Pro and Builder) | Yes | Yes | — | — |
| Set up GitHub Sync | Yes | — | — | — |
| Billing and plan changes | Yes | — | — | — |
| Transfer ownership | Yes | — | — | — |
Editors and viewers can still *see* the Market Definition template and the AI suggestions switch; they just can't change them.
## Inviting team members
1. Go to **Settings → Team Management**.
2. Click **Invite Member**.
3. Enter the person's email and pick a role.
4. Click **Send Invite**.
The invitee gets an email with a link to accept. If they don't have a Black Ice account yet, they create one first, using the same email address.
## Invitation lifecycle
- Invitations expire after **7 days**.
- A pending invitation can be **resent**. Resending keeps the same link and gives it a fresh 7 days.
- You can **cancel** a pending invitation at any time.
- If sending the email fails, you see an error straight away instead of a silent failure.
- Once accepted, the person appears in the workspace with their role.
## Changing roles
Owners and Admins can change a member's role at any time from Team Management. The Owner role can't be given this way; use ownership transfer instead.
## Transferring ownership
A workspace has one Owner. To hand it over:
1. Make sure the new owner has **joined** the workspace and is an **Admin**.
2. The current Owner opens **Settings → Team Management** and chooses to transfer ownership to that Admin.
The new owner gets full control. The previous owner becomes an Admin and loses owner-only rights, such as billing and GitHub Sync.
## Plan shown to members
Everyone in a workspace works under the **workspace's plan**, which is the Owner's plan. Invited members see that plan's badge and limits, not their own. Billing pages still show each person's personal plan.
## Removing members
Owners and Admins can remove members. Access ends straight away, and the person gets an email saying they were removed. Their contributions (concepts, terms, approvals, history) stay in the workspace.
## Viewer experience
Viewers see a **View only** banner. Create, edit, delete, import and relationship actions are hidden. Opening a create or import page directly sends them back to the concepts list. The backend refuses viewer changes even if someone gets around the interface.
## Plan limits
Team members are available on the **Builder** plan, with up to **10 members** per workspace.
See also: [Permissions & data visibility](/docs/features/permissions-and-data-visibility), [Approval workflows](/docs/features/approval-workflows), [Candidate review workflow](/docs/features/candidate-review-workflow).
---
# Approval workflows
> Send terms for external review with shareable approval links, per-market links, a read-only full graph view and decision reopening.
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.
Each reviewer decision is also written into the term's permanent [decision history](/docs/features/decision-history), labelled **Approval link** (or **Partner agency** when a hired agency reviewed it), together with the reviewer's comment.
## Requests that cover several markets
When you send terms for more than one market, Black Ice creates **one review link per market** as well as the main link.
- **Market links:** each linguist opens the link for their market. They see only that market's terms, with the source term and definition for context, and can decide only those.
- **Decisions are locked:** once a term is decided, nobody can change it from a market link, not even the person who decided it.
- **Main link = read-only overview:** it shows progress per market, every decision with the reviewer's name and comment, and all the market links to forward. Nobody can approve or reject from it.
- **Reopening:** from the overview, the coordinator can reopen a decision for the **same linguist** (their market link works again for that term) or for a **new linguist** for a second opinion (a new link is created and copied). The earlier decision stays in the term's decision history.
- On the **Approvals** page, expand a request to see progress per market and copy each market link.
Requests with a single market work exactly as before: one link that decides everything.
## View full graph (read-only)
During a review, reviewers can click **View full graph** to see how the concept relates to the rest of the ontology, without a Black Ice account.
- It opens on the concept under review and shows its **direct relationships**. Each line has the relationship name written on it (for example *hasFeature*), read in the direction of the arrow.
- Each card shows the class, availability, the source term and the **target term for the market under review**. A market link shows only its own market. The overview can switch between the request's markets.
- **Show concepts two links away** widens the view, and **Whole network** shows everything around it, laid out in columns by distance.
- Click any card or **Under review** chip to recentre the view.
- The graph is read-only and limited to the concepts linked to the request.
## Managing requests
Use search and the filters beneath it, then expand a multi-market request to inspect its market links. Pending requests can be copied or cancelled from the row controls. Deleting a completed or decided request is a separate, confirmed action that removes the request record; preserve request-level evidence first. Term decision history remains separate. Partner monthly statements are independent billing records; deleting a request does not correct a closed statement.
---
# Partner program for agencies
> How language agencies join the Black Ice partner directory, receive client requests and validate terminology through review links.
# Partner program for agencies
The Black Ice partner program lists vetted language service providers that validate target-market terminology for Black Ice customers. You publish a fixed price per approved term for each market; customers agree to it once in Black Ice and you invoice them directly. You review their terms through Black Ice review links — no account, workspace or new tool needed.
## Emails you receive
- **New client:** when a customer agrees to your prices, with their workspace name, who accepted (name and email, so you know whom to invoice), the agreed prices and their budget if set.
- **Agreement ended / resumed:** when a customer stops or restarts working with you.
- **Review links:** each time the customer sends terms for approval.
## Who it's for
Localization and translation agencies with native linguists in one or more markets. Specialist domains (Legal, Medical, Gaming, Fintech…) and certifications such as ISO 17100 help customers choose you.
## How to apply
1. Open [Become a partner](/partners/apply).
2. Fill in your agency name, website, contact person and the email where you want to receive client requests.
3. List the markets you cover as locale codes separated by commas, for example `es-es, es-mx, fr`. A language code on its own (`fr`) covers all its regions.
4. Set your **price per approved term for each market**, for example `es-es: 2.50, de-de: 3.00`, and the currency. A language code (`es: 2.50`) covers all its regions.
5. Add your specialist domains, certifications, an optional logo URL (https) and a short description.
6. Accept the [Partner Agency Terms](/legal/partner-terms) and submit.
Every application is reviewed by hand. You get an email once your listing is approved.
## Where you appear
- **In the app:** the Partners directory, filtered by market and domain. Agencies covering a customer's own target markets are shown first.
- **On the website:** the public [Our partners](/our-partners) page and the partner section of the landing page.
## Prices and getting paid
- Your listing appears only once you have a price for at least one market.
- A customer (owner or admin, Pro or Builder plan) clicks **Work with this agency** and accepts your prices. From then on those prices are fixed for that customer; if you change your prices, only new customers get the new ones.
- You are paid only for terms you **approve**. Rejected terms are not counted.
- Both you and the customer can rely on the count Black Ice shows: approved terms per market per month x your agreed price. You invoice the customer directly; Black Ice takes no commission.
- To change your prices, email hello@black-ice.ai.
## Validating terminology
When the customer needs terms validated, they send you a review link from Black Ice. On that link you can:
- see each concept, its definition, related concepts and the approved terms in other markets,
- approve, reject or comment on each proposed term.
Your decisions are recorded in the customer's term history as **Partner agency — Validated by **.
## Access and confidentiality
- You never join the customer's workspace. You see only the terms they send for approval.
- Your contact email is never shown publicly; it is only used to forward requests.
- Keep everything you see confidential and use it only for that customer's work. See the [Partner Agency Terms](/legal/partner-terms).
## FAQ
### Does it cost anything to be listed?
No. Listing is free and Black Ice takes no commission.
### Do I need a Black Ice account?
No. Review links work without an account.
### How do I update my profile?
Email hello@black-ice.ai with the changes and we will update your listing.
### Can my listing be removed?
Yes. Black Ice may hide or remove a listing at any time, for example if the profile is no longer accurate.
## Related
- [Hiring a partner agency](/docs/features/hiring-a-partner-agency) — the customer side of the same flow.
## Requests that cover several markets
When you send terms for more than one market, Black Ice creates **one review link per market** as well as the main link.
- **Market links:** each linguist opens the link for their market. They see only that market's terms, with the source term and definition for context, and can decide only those.
- **Decisions are locked:** once a term is decided, nobody can change it from a market link, not even the person who decided it.
- **Main link = read-only overview:** it shows progress per market, every decision with the reviewer's name and comment, and all the market links to forward. Nobody can approve or reject from it.
- **Reopening:** from the overview, the coordinator can reopen a decision for the **same linguist** (their market link works again for that term) or for a **new linguist** for a second opinion (a new link is created and copied). The earlier decision stays in the term's decision history.
- On the **Approvals** page, expand a request to see progress per market and copy each market link.
Requests with a single market work exactly as before: one link that decides everything.
## Context for linguists: the full graph
Every review link has a **View full graph** button: a read-only map of the concept's relationships, with source and target terms for the linguist's market. Linguists can use it to check how a term fits with related concepts before deciding. It gives no access to the client's workspace.
## Partial market coverage
If a client sends markets your agency doesn't offer, Black Ice sends you only the markets in your agreed prices. The rest goes to a separate link the client handles without you.
## Monthly statements (month close)
On the 1st of each month Black Ice closes the previous month for every active agency agreement. You and the agency receive the same statement by email: a statement number, approved terms per market, the agreed price and the total. The agency invoices you directly once a month, using the statement number as the reference. Black Ice does not bill or take payment.
Closed months appear under **Partners → Monthly statements**, where you can download a CSV and mark each one as *Invoice received* or *Paid*. Closed statements never change; a decision reopened later counts in the month it is decided again.
---
# 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. Includes RAG, GraphRAG and vector database (Vector DB) setups.
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 status
- 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.
You can also download the same bundle through the API with `GET /query-ontology?format=markdown-zip`, or fetch a single file with `format=markdown&path=…`. The files are identical to the in-app ZIP and GitHub Sync. Each file carries a version and a "generated at" date, and is a snapshot — the live workspace stays the source of truth. See [API Reference](/docs/integrations/api-reference).
**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**.
### Using the graph with vector databases and GraphRAG
The RDF exports are designed to sit next to a vector index. Embeddings find the right concept by meaning; the graph then supplies the governed answer — approved term per market, forbidden variants, availability and related concepts — so retrieval never relies on similarity alone.
**Pattern 1 — Hybrid GraphRAG (Neo4j, Amazon Neptune, Memgraph, GraphDB)**
1. Load the Turtle file into the graph store (for Neo4j, use the n10s / neosemantics plugin).
2. Embed each concept's definition and its term labels, and store the vector with the concept IRI as its key.
3. At query time, embed the question, find the nearest concept IRIs, then traverse the graph from those IRIs to read the approved `skosxl:prefLabel` for the requested language tag (for example `@es-ES`), `bi:forbiddenVariant`, `bi:availability` and related concepts.
4. Pass only that governed context to the model.
**Pattern 2 — Metadata-enriched embeddings (Qdrant, Weaviate, Pinecone, Milvus, pgvector)**
1. Iterate the nodes in the JSON-LD `@graph`.
2. Embed the definition text (plus source term) of each concept.
3. Store the concept IRI, class, approved terms per locale, forbidden variants, availability per market and related concept IRIs in the vector's payload / metadata.
4. Filter on metadata at query time — for example, only concepts available in `de-DE` — so the model never sees terms that aren't live in that market.
**Framework loaders**
- **LlamaIndex** — load Turtle with an RDF reader, or build a `PropertyGraphIndex` from the triples.
- **LangChain** — use `RdfGraph` to query the Turtle file with SPARQL, alongside any LangChain vector store.
- **rdflib (Python)** / **jsonld.js (JavaScript)** — parse either file directly in your own pipeline.
**Keeping it fresh.** RDF files are snapshots from the Export dialog. Re-export and re-index when terms change, or use MCP / the API for live lookups and keep the vector index for discovery only.
## 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** | JSON from `GET /query-ontology`, plus the AI Agent Bundle as a ZIP (`format=markdown-zip`), a single Markdown file (`format=markdown&path=…`) or a JSON list of files (`format=markdown-files`) |
| **MCP** | JSON answers from the read tools, always live |
RDF/OWL, PDF, CSV and graph images are produced in the app rather than through the API. If you need Markdown on a schedule, pull the bundle ZIP from the API in your pipeline or use GitHub Sync. For the other formats, export from the app and commit the file.
---
## 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 |
| **Scheduled pipeline needing Markdown** | AI Agent Bundle via API (`format=markdown-zip`) or GitHub Sync |
| **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 |
| **Hybrid GraphRAG (Neo4j, Neptune, GraphDB)** | Turtle |
| **Vector databases (Qdrant, Weaviate, Pinecone, pgvector)** | JSON-LD |
| **LlamaIndex / LangChain pipelines** | Turtle or JSON-LD |
| **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** at `/activity`. 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 activity records before the retention window closes if you need a longer audit trail. GitHub Sync preserves ontology snapshots, not the complete activity log.
## 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)
### Four ways to add term candidates
New terms reach the [Candidates review queue](/docs/features/candidate-review-workflow) through your pipeline (`mutate-ontology` with a `candidates` array), a CSV import, the **Add candidate** button, or your AI assistant via the MCP tool `suggest_candidates` (off by default; owners and admins turn it on). All four follow the same rules, and people make every decision.
## 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)
## Current page layout
Integrations includes Overview, API Keys, MCP, Usage & Analytics, and GitHub Sync. Overview links to live connection status, keys, sync controls, and usage. MCP shows setup, individual permissions, connected apps, and limits. API Keys offers Read only, Suggest only, and Read and write. Usage reports workspace-wide API/MCP calls, including calls made automatically by connected clients—not only manually by you. Missing-market warnings refer to markets requested by clients but not configured in the workspace.
---
# 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. Includes RAG, GraphRAG and vector database (Vector DB) setups.
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 |
The same Markdown bundle GitHub Sync writes is also available straight from the API (`GET /query-ontology?format=markdown-zip`), on every plan — useful for pipelines without a repo.
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)
---
**Read-only by default.** The seven governance lookup tools are read-only. Owners and admins can also opt into individual writing tools; see [AI writing tools](/docs/integrations/ai-writing-tools). Definitions apply directly, proposed translations are Pending, and availability/relationship/type proposals wait for review. Assistants cannot approve terms or delete data. Owners and admins can optionally turn on `suggest_candidates`, which lets your assistant propose new terms to the [Candidates review queue](/docs/features/candidate-review-workflow). Black Ice runs no AI of its own. Your assistant (Claude, Cursor, or another MCP client) does the spotting; Black Ice only stores its suggestions in the review queue, and people decide.
## 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. Collect the paginated API snapshot and compare it with your previous snapshot to identify changes. Your pipeline supplies that delta to Claude, 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 | ✗ | ✗ | ✗ | ✓ |
## Vector databases & GraphRAG pipelines
Vector search finds what a question is *about*; it can't tell which term is approved in Germany or which variant is forbidden in Spain. Black Ice supplies that deterministic layer.
- **Hybrid GraphRAG** — load the Turtle export into Neo4j, Neptune or GraphDB, keep embeddings of concept definitions in a vector index, and traverse from the matched concept to its approved term, forbidden variants and market availability before calling the model.
- **Metadata-filtered retrieval** — embed concepts from the JSON-LD export into Qdrant, Weaviate, Pinecone or pgvector, with approved terms and availability per market as metadata, and filter by market at query time.
- **Live check at the end** — whatever the retriever returns, call MCP `check_term` or `validate_translation` on the output to catch drift since the last export.
Your RAG stack decides relevance; Black Ice decides correctness. RDF/OWL exports are available on Pro and Builder.
→ [Export formats: vector databases and GraphRAG](/docs/features/export-formats)
## 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 by default and scoped to one workspace per connection. Eligible editors/admins/owners can use optional tools enabled by workspace settings; see [AI writing tools](/docs/integrations/ai-writing-tools).
## 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 lists seven read-only tools. If a workspace owner or admin has turned on **Allow AI assistants to suggest candidates** (Integrations page), permitted editor/admin/owner connections also see `suggest_candidates` (other enabled writing tools may also appear), which can only send unconfirmed term suggestions to your [Candidates review queue](/docs/features/candidate-review-workflow). It works only if you are an editor, admin or owner, and it can never change approved terminology. 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 candidate suggestions enabled**, and either an eligible OAuth member or a Suggest only / Read and write API key. MCP does not create concepts directly; a person accepts the candidate. See [Candidate review](/docs/features/candidate-review-workflow).
>
> **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.
---
## Suggesting candidates (optional)
If a workspace owner or admin has turned on candidate suggestions, Claude also gets the `suggest_candidates` tool. It can send words it spots in your texts to the Candidates review queue. Nothing is approved until a person reviews it.
See the [Candidate review workflow](/docs/features/candidate-review-workflow) for how suggestions are reviewed.
## 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 Keys**. 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)
## Directory connection and optional tools
In Claude, look for Black Ice in **Connectors → Discover/Search**, connect it, sign in, and select the workspace. No API key is needed for this OAuth path. The custom-connector steps above remain an alternative when needed. The seven read tools are the baseline, not a fixed total: enabled candidate/writing tools appear only for permitted connections. Definitions apply directly; translations are Pending; availability/relationship/type proposals await review. Assistants cannot approve terms or delete data.
---
# 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": {
"x-api-key": "bice_YOUR_KEY_HERE"
}
}
}
}
```
If your workspace has turned on candidate suggestions (off by default) and your connection has permission, the list also includes `suggest_candidates`, which sends unconfirmed term suggestions to your [Candidates review queue](/docs/features/candidate-review-workflow). It needs a Suggest only or Read and write key, or an OAuth sign-in by an editor, admin or owner and never changes approved terminology. Leave it off if you only want read access.
## 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 an API key sent in the `x-api-key` header, 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.
## Directory connection and optional tools
In Claude, look for Black Ice in **Connectors → Discover/Search**, connect it, sign in, and select the workspace. No API key is needed for this OAuth path. The custom-connector steps above remain an alternative when needed. The seven read tools are the baseline, not a fixed total: enabled candidate/writing tools appear only for permitted connections. Definitions apply directly; translations are Pending; availability/relationship/type proposals await review. Assistants cannot approve terms or delete data.
---
# Vector Databases & GraphRAG
> Use your Black Ice ontology in RAG, GraphRAG and vector database (Vector DB) pipelines: Neo4j, Qdrant, Weaviate, Pinecone, pgvector, LlamaIndex and LangChain.
Your RAG stack decides **relevance**. Black Ice decides **correctness**.
Vector search finds text that *looks* similar. It cannot tell whether a term is approved, forbidden or available in a market. Black Ice adds that layer on top of your retrieval pipeline.
## What you need
- Export your ontology as **JSON-LD** or **Turtle** (Pro and Builder plans). See [Export formats](/docs/features/export-formats).
- Optional: an **API key** or an **MCP** connection for live lookups.
## Pattern 1: Graph database plus vector search (GraphRAG)
Best for Neo4j, Amazon Neptune, GraphDB or Memgraph.
1. Load the Turtle export into your graph database (for Neo4j, use the neosemantics plugin).
2. Embed each concept's name and definition and store the vectors in a vector index.
3. At query time, vector search finds the matching concept.
4. Traverse the graph from that concept to get the approved term for the target market, its forbidden variants and whether it is available there.
5. Pass those constraints to the model in the prompt.
## Pattern 2: Vector database with rich metadata
Best for Qdrant, Weaviate, Pinecone or pgvector.
1. Read the `@graph` in the JSON-LD export.
2. Create one record per concept. Embed the name and definition.
3. Save the approved terms per market, forbidden variants and availability as metadata on the record.
4. Filter searches by market, for example only concepts available in `es-ES`.
## Developer tools
- **LlamaIndex**: `RDFReader`, `PropertyGraphIndex`
- **LangChain**: `RdfGraphStore`
- **rdflib** (Python) and **jsonld.js** (JavaScript) to parse the exports directly
## Keeping it up to date
Exports are snapshots. Export again when terms change, or sync with [GitHub Sync](/docs/integrations/github-sync). For final checks, call the MCP tools `check_term` or `validate_translation` before you publish content.
## Related
- [Export formats](/docs/features/export-formats): the RDF structure and the `bi:` namespace
- [Black Ice + AI](/docs/integrations/ai-integrations-overview): every way to connect your AI tools
- [API reference](/docs/integrations/api-reference)
> These setups follow common practice and have not been tested with every tool. Check them against your own stack.
---
# 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. Market codes ignore case; definitions are returned.
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 read-only governance tools, plus individually enabled candidate/writing tools for permitted connections, 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 **Integrations → API Keys**.
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 runs an `initialize` handshake and discovers the tools allowed by the workspace settings and connection permissions.
## 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.
### `suggest_candidates` — send new terms to the review queue
```
Here are our new onboarding strings: . Check which product terms aren't in
Black Ice yet with list_concepts, then suggest them as candidates with a note on
where each one appears.
```
Off by default: an owner or admin must turn on **Allow AI assistants to suggest candidates** on the Integrations page. This tool writes only to the [Candidates review queue](/docs/features/candidate-review-workflow). Your terminologist still runs the five tests and decides. It needs a **Suggest only** or **Read and write** API key, or an OAuth sign-in by an editor/admin/owner; read-only keys and viewers are refused.
## 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. In Claude, search for Black Ice under Connectors → Discover/Search; the directory connection uses OAuth and needs no API key. The custom-connector setup remains an alternative.
- Optional [AI writing tools](/docs/integrations/ai-writing-tools) are available now: definitions and Pending translations apply directly; availability, relationship and type proposals wait for review. Workspace switches and connection permissions apply.
## 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.
## Market codes and definitions
- **Market codes ignore upper and lower case.** `check_term("Melody Generator", "es-ES")` returns the same as `"es-es"`. A market that isn't set up in your workspace returns an error that names it, never fields that are silently empty.
- **Definitions are included.** `list_concepts` and `check_term` return each concept's existing definition so assistants can use it when writing content, and check for one before proposing a new one.
## Directory connection and optional tools
In Claude, look for Black Ice in **Connectors → Discover/Search**, connect it, sign in, and select the workspace. No API key is needed for this OAuth path. The custom-connector steps above remain an alternative when needed. The seven read tools are the baseline, not a fixed total: enabled candidate/writing tools appear only for permitted connections. Definitions apply directly; translations are Pending; availability/relationship/type proposals await review. Assistants cannot approve terms or delete data.
---
# 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 ontology as paginated JSON; follow `pagination.nextOffset` or `_links.next` until complete
- **Download** the AI Agent Bundle — the same Markdown files as the in-app ZIP and GitHub Sync — as a ZIP, one file at a time, or as a JSON list
- **Write** in batches: create, update, delete, or upsert concepts, terms, relationships, classes, and market constraints
- **Sync** terminology from external systems (TMS, PIM, CMS) without leaving your tool of choice
## Endpoints
| Method | Endpoint | Purpose |
|---|---|---|
| `GET` | `/functions/v1/query-ontology` | Export the full workspace ontology (JSON by default) |
| `GET` | `/functions/v1/query-ontology?format=markdown-zip` | AI Agent Bundle as a ZIP |
| `GET` | `/functions/v1/query-ontology?format=markdown&path=…` | One bundle file as plain Markdown |
| `GET` | `/functions/v1/query-ontology?format=markdown-files` | All bundle files as JSON `{ path, content }` |
| `POST` | `/functions/v1/mutate-ontology` | Apply a batch of write operations |
Base URL: `https://`
## Authentication
Every request must include the header `x-api-key: bice_xxxxxxxx`. Generate a key from **Integrations → API Keys** in the app. Keys are scoped to a single workspace.
### Key scopes
Each key has one of three scopes: **Read only**, **Suggest only**, or **Read and write**:
- **Read only** — may query the ontology and export audit history. Use this for one-directional integrations that pull the ontology as reference data (a TMS, CMS, or RAG pipeline that never writes back).
- **Suggest only** — may query and submit candidates; cannot mutate ontology records or export audit history.
- **Read and write** — may query, submit candidates, mutate ontology records, and export audit history.
A read-only key used against `POST /mutate-ontology` returns **403** with `"code": "insufficient_scope"`. Choose the scope in **Integrations → API Keys** when generating the key; it cannot be changed afterwards (create a new key with the desired scope and revoke the old one).
### Submitting term candidates
`POST /functions/v1/mutate-ontology` also accepts a `candidates` array instead of `operations`. Candidates go to the [review queue](/docs/features/candidate-review-workflow), never directly into the ontology.
| Field | Required | Notes |
|---|---|---|
| `term` | yes | 1–200 characters |
| `locale_code` | yes | e.g. `en-us` |
| `definition` | no | up to 2,000 characters |
| `class_name` | no | linked if it matches an existing class |
| `source` | no | label for acceptance-by-source stats (default `api`) |
| `frequency`, `confidence` | no | confidence only orders the queue |
| `provenance` | no | object or array, e.g. `{ "url": "...", "note": "..." }` |
Up to **500** per request; requires a **Suggest only** or **Read and write** key. The response returns `created`, `updated` (repeats), `suppressed` (on the rejection list), `resurfaced` and per-item `errors`. AI assistants can do the same through the MCP tool `suggest_candidates` (50 per call), once an owner or admin turns it on — it is off by default.
## Tier & limits
- Available on **all plans**, including Free — per-plan quotas (concepts, markets, members) apply as normal
- **Reads per workspace/minute:** Free 60, Pro 300, Builder 1,000
- **Write requests per workspace/minute:** Free 30, Pro 120, Builder 400; 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:///functions/v1/query-ontology"
```
## Markdown bundle
Add `format` to the read endpoint to get the AI Agent Bundle instead of JSON. Options: `locale` (one market), `approved_only=true` (approved target terms only), and `path` (for `format=markdown`, e.g. `markets/es-es.md`; unknown paths return 404 with the list of available paths).
```bash
curl --header "x-api-key: bice_YOUR_KEY_HERE" -o black-ice-ontology.zip \
"https:///functions/v1/query-ontology?format=markdown-zip"
```
Every file starts with the bundle version and generation time, and notes that it is a snapshot — the live workspace is the source of truth. Responses carry `ETag`, `X-Bundle-Version` and `X-Generated-At`; send `If-None-Match` to get `304 Not Modified` when nothing changed, or use `HEAD` to read just the version. Each request counts as one API call.
> Need Markdown? Use `format=markdown-zip` — don't rebuild the bundle from the JSON response. In JSON, each market's guidelines are in `definitions` (with saved section order and custom sections); `cultureDna` is an older name for the same value.
> For AI assistants, prefer the live MCP connection. Use the ZIP or GitHub Sync for pipelines.
## Full reference
The complete reference covers every entity (concept, term, relationship, relationship_type, class, market_constraint, market), 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.
## Market codes
Market codes don't depend on upper or lower case: `es-ES`, `ES-es` and `es-es` give the same result. If you ask for a market that isn't set up in your workspace, you get a clear error instead of empty results.
> **Note:** replace `` with the endpoint URL shown in **Integrations → API Keys**.
## Audit export and candidate origin
`GET /functions/v1/export-audit` exports `type=activity|candidates` in `format=json|csv`, with optional `from`, `to`, `cursor`, and `limit` (maximum 1000). Follow JSON `next_cursor` or the CSV `X-Next-Cursor` header. Read only and Read and write API keys may export; Suggest only may not. Signed-in owners/admins can export through Activity and Candidates. Activity retention is 90 days; candidate decisions and server-recorded origin are independent. The server preserves the proposing API key ID, prefix and label or OAuth client; user-supplied source labels cannot forge that identity. Legacy candidates may have no recorded origin. Black Ice has no service accounts: use one workspace key per pipeline.
## Snapshots and audit records
The JSON read endpoint is paginated (default 1000 concepts; maximum 5000 per page). Follow `_links.next` or `pagination.nextOffset` until complete. `since` filters concept timestamps only, not all ontology changes or deletions; use periodic full reads for reliable synchronization. Ontology snapshots and activity/candidate audit exports are separate outputs. GitHub Sync is not a complete activity audit export.
---
# 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 the MCP tool `suggest_candidates` (optional review-queue suggestions) 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.
The cap is shared by every connection in the workspace — all MCP clients and API keys draw from the same 10,000 calls. It is not counted per connection, and you never need a separate subscription per connection.
| 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.
- **Suggest only** — reads and sends candidates for human review, but cannot mutate ontology records or export audit history.
- **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://`
## 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.
## Submitting term candidates
`POST /functions/v1/mutate-ontology` also accepts a `candidates` array instead of `operations`. Candidates go to the [review queue](/docs/features/candidate-review-workflow), never directly into the ontology. Required fields: `term` and `locale_code`; optional: `definition`, `class_name`, `source`, `frequency`, `confidence`, `provenance`. Up to **500** per request with a **Suggest only** or **Read and write** key. The response returns `created`, `updated`, `suppressed`, `resurfaced` and per-item `errors`. See the [API reference](/docs/integrations/api-reference) for the full table.
## Rate limits
Limits are per workspace, per minute, and depend on the workspace plan:
| Plan | Read requests/min | Write requests/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. It can also hand out the Markdown bundle as a ZIP (`format=markdown-zip`) for pipelines that want files without a GitHub repo.
- **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.
**Rule of thumb:** use MCP when an assistant needs live answers, and the bundle ZIP or GitHub Sync for pipelines. A downloaded ZIP is a snapshot — use its version (`ETag`) to re-download only when something changed.
## 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).
> **Note:** replace `` with the endpoint URL shown in **Integrations → API Keys**.
## Audit export and candidate origin
`GET /functions/v1/export-audit` exports `type=activity|candidates` in `format=json|csv`, with optional `from`, `to`, `cursor`, and `limit` (maximum 1000). Follow JSON `next_cursor` or the CSV `X-Next-Cursor` header. Read only and Read and write API keys may export; Suggest only may not. Signed-in owners/admins can export through Activity and Candidates. Activity retention is 90 days; candidate decisions and server-recorded origin are independent. The server preserves the proposing API key ID, prefix and label or OAuth client; user-supplied source labels cannot forge that identity. Legacy candidates may have no recorded origin. Black Ice has no service accounts: use one workspace key per pipeline.
---
# 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://`
```bash
curl "https:///functions/v1/query-ontology?limit=1000" \
-H "x-api-key: bice_xxxxxxxxxxxxxxxx"
```
### Node.js
```js
const res = await fetch(
"https:///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:///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 whose own `updated_at` is at or after that moment are selected. This is not a complete change feed for every entity: do not assume term-only, relationship, market, or deletion changes are captured. Use periodic full paginated snapshots (or versioned Markdown bundles) when you need complete synchronization:
```
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`, `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.
## Pulling Markdown instead of JSON
If your system or agent prefers readable files over JSON, the same endpoint returns the AI Agent Bundle — `CLAUDE.md`, classes, markets, terminology and relationships — with the same read-only key:
```bash
curl --header "x-api-key: $BLACK_ICE_API_KEY" -o black-ice-ontology.zip \
"https:///functions/v1/query-ontology?format=markdown-zip"
```
Use `format=markdown&path=markets/es-es.md` for one file, or `format=markdown-files` for a JSON list. To avoid working from a stale copy, store the `ETag` from each download and send it back as `If-None-Match` on the next run: you get `304 Not Modified` when nothing has changed, and a fresh bundle when it has. `locale` and `approved_only=true` work here too.
## 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 default** and supports OAuth without an API key. Eligible members can use optional candidate/writing tools only when the workspace enables them. For a strictly read-only integration, use a read-only API key or keep every writing switch off; see [AI writing tools](/docs/integrations/ai-writing-tools). 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)
> **Note:** replace `` with the endpoint URL shown in **Integrations → API Keys**.
---
# 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"` |
| **Suggest candidates only** | ✅ | Only `{"candidates": [...]}` (and MCP `suggest_candidates`). Any `operations` request or MCP writing tool returns `403 insufficient_scope` |
| **Read and write** | ✅ | ✅ |
Use **Suggest candidates only** for extraction pipelines: they can feed the review queue but can never change approved terminology. Suggest-only keys cannot export audit history.
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, Suggest 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
Use **Revoke** beside the key and confirm. 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` | Scope does not allow this action | Use Suggest only for candidates; Read and write for ontology mutations. Suggest only cannot export audit history. |
| `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.
- Black Ice has no service accounts. A workspace API key is the intended identity for a pipeline; create one key per pipeline so its actions can be traced and revoked individually.
## Exporting audit history
Owners and admins can download the activity log (**Activity → Export CSV**) and all candidate decisions (**Candidates → Export decisions**). Pipelines can archive the same data before the 90-day activity log window closes:
```bash
curl -H "x-api-key: bice_..." \
"https:///functions/v1/export-audit?type=activity&from=2026-11-01&format=csv"
```
`type` is `activity` or `candidates`; optional `from`, `to` (ISO dates), `format=json|csv`, `limit` (max 1000). When more rows exist the response includes `X-Next-Cursor` — pass it back as `cursor`. Read-only and read-and-write keys can export; suggest-only keys get `403`.
## When someone leaves the workspace
API keys belong to the workspace, not to the person who created them. If the creator is removed from the workspace or deletes their Black Ice account, the key keeps working, and owners and admins can still see, regenerate or revoke it. Each key shows who created it ("Created by a former member" once they have left). If the person who left had a copy of the key, regenerate it.
> **Note:** replace `` with the endpoint URL shown in **Integrations → API Keys**.
---
# 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 concept-update `since` pulls, and can export audit history through `export-audit`. 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 default. Its lookup tools consult terminology, availability, definitions, and relationships. Optional candidate and writing tools require workspace opt-in and eligible connection permissions.
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.
MCP is read-only by default. Candidate suggestions and each ontology-writing tool have separate switches. For a strictly one-directional connection, use a read-only key or leave all writing switches off. Suggest only keys may read and submit candidates, but cannot mutate ontology records or export audit history. See [AI writing tools](/docs/integrations/ai-writing-tools) for direct versus reviewed changes.
## 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. Includes RAG, GraphRAG and vector database (Vector DB) setups.
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 |
The same Markdown bundle GitHub Sync writes is also available straight from the API (`GET /query-ontology?format=markdown-zip`), on every plan — useful for pipelines without a repo.
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)
---
**Read-only by default.** The seven governance lookup tools are read-only. Owners and admins can also opt into individual writing tools; see [AI writing tools](/docs/integrations/ai-writing-tools). Definitions apply directly, proposed translations are Pending, and availability/relationship/type proposals wait for review. Assistants cannot approve terms or delete data. Owners and admins can optionally turn on `suggest_candidates`, which lets your assistant propose new terms to the [Candidates review queue](/docs/features/candidate-review-workflow). Black Ice runs no AI of its own. Your assistant (Claude, Cursor, or another MCP client) does the spotting; Black Ice only stores its suggestions in the review queue, and people decide.
## 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. Collect the paginated API snapshot and compare it with your previous snapshot to identify changes. Your pipeline supplies that delta to Claude, 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 | ✗ | ✗ | ✗ | ✓ |
## Vector databases & GraphRAG pipelines
Vector search finds what a question is *about*; it can't tell which term is approved in Germany or which variant is forbidden in Spain. Black Ice supplies that deterministic layer.
- **Hybrid GraphRAG** — load the Turtle export into Neo4j, Neptune or GraphDB, keep embeddings of concept definitions in a vector index, and traverse from the matched concept to its approved term, forbidden variants and market availability before calling the model.
- **Metadata-filtered retrieval** — embed concepts from the JSON-LD export into Qdrant, Weaviate, Pinecone or pgvector, with approved terms and availability per market as metadata, and filter by market at query time.
- **Live check at the end** — whatever the retriever returns, call MCP `check_term` or `validate_translation` on the output to catch drift since the last export.
Your RAG stack decides relevance; Black Ice decides correctness. RDF/OWL exports are available on Pro and Builder.
→ [Export formats: vector databases and GraphRAG](/docs/features/export-formats)
## 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 by default and scoped to one workspace per connection. Eligible editors/admins/owners can use optional tools enabled by workspace settings; see [AI writing tools](/docs/integrations/ai-writing-tools).
## 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 lists seven read-only tools. If a workspace owner or admin has turned on **Allow AI assistants to suggest candidates** (Integrations page), permitted editor/admin/owner connections also see `suggest_candidates` (other enabled writing tools may also appear), which can only send unconfirmed term suggestions to your [Candidates review queue](/docs/features/candidate-review-workflow). It works only if you are an editor, admin or owner, and it can never change approved terminology. 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 `