Context Library

The Context Library stores reusable knowledge – prompts and files – in your environment, so every AI call can be grounded in your organization’s own rules and reference material instead of ad-hoc instructions written by each user.

A context is a named container that holds two kinds of items:

• Prompts – reusable instruction text, such as a tone-of-voice rule, an editorial standard, or a compliance requirement.
• Files – reference documents, such as a brand guidelines PDF, a product glossary, or a policy handbook.

Contexts live in the environment, not in a single conversation. Once a context is defined, it can be attached to conversations, actions, reviews, and document processing – or applied automatically.

Without the Context Library, every integration has to ship the same instructions in every request: the brand voice, the glossary, the company policy, the legal disclaimer rules. That text is duplicated across your codebase, drifts out of sync between features, and can only be changed by a deployment.

With the Context Library:

• Author once, use everywhere. The same brand-voice context grounds a chat conversation, a “fix grammar” action.
• Update without deploying. Editing a prompt or replacing a file in the library changes the behavior of every call that references it, immediately.
• Ground the AI in real documents. Reference material is attached as files, so the model works from your actual policy or guideline document rather than a paraphrase of it.

Resolution happens per call. When a request references a context, the service expands the reference at invocation time:

• Matching prompts are included of the feature being called.
• Matching files are attached to the request as context for the model.

Because resolution is per call, nothing is copied into the conversation history. A conversation that references legal-policies always uses the current content of that context.

The feature is split into an administrative API for authoring and a client API for consumption:

The client API returns a restricted view: it exposes context and item metadata but not the text of prompts.

GET /v1/contexts returns only the contexts the caller has permission for.

The context id is supplied by you and must be unique within the environment, so you can use stable, meaningful identifiers in your code.

POST /v1/admin/contexts
Content-Type: application/json
Authorization: Bearer <admin-token>

{
  "id": "brand-voice",
  "name": "Brand voice and style",
  "description": "Tone of voice, terminology, and formatting rules for all customer-facing copy.",
  "attributes": {
    "team": "marketing",
    "locale": "en-US"
  }
}

Each prompt is a single reusable instruction. Splitting rules across several prompts keeps them easy to review and lets you attach one rule in isolation when needed.

POST /v1/admin/contexts/brand-voice/prompts
Content-Type: application/json
Authorization: Bearer <admin-token>

{
  "name": "Tone of voice",
  "content": "Write in a confident, plain-spoken tone. Address the reader as \"you\". Avoid superlatives, marketing jargon, and exclamation marks. Never promise outcomes we cannot measure.",
  "attributes": {
    "category": "tone",
    "priority": 1
  }
}

Files can be uploaded directly, or downloaded by the service from a URL you provide. Supported formats are PDF, DOCX, PNG, JPEG, Markdown, HTML, and plain text.

Direct upload:

POST /v1/admin/contexts/brand-voice/files
Content-Type: multipart/form-data
Authorization: Bearer <admin-token>

file: [brand-guidelines.pdf]
attributes: {"language":"en-US","category":"reference"}

Upload from a URL – useful when the source document already lives in the Internet:

POST /v1/admin/contexts/brand-voice/files
Content-Type: application/json
Authorization: Bearer <admin-token>

{
  "url": "https://intranet.example.com/brand/guidelines.pdf",
  "attributes": {
    "category": "reference"
  }
}

A reference is a small object identifying what to resolve. Three shapes are available:

promptId and fileId are mutually exclusive. Every explicit reference requires the ai:contexts:<contextId> scope in the caller’s token; ai:contexts:* and ai:admin satisfy it implicitly.

For custom actions, custom reviews, and document processing, prompt becomes optional once at least one context is attached – the context then drives the call. Either prompt or contexts must be provided.

In conversations, omitting prompt while referencing a context that resolves to a prompt makes the referenced context prompt act as the message prompt. It is not exposed in the stored message content, so your curated instruction text stays out of the conversation transcript.

This is what makes the library a place to put operations, not just background knowledge: a context can encode a complete, reviewed instruction that your application invokes by id.

A support team drafts customer replies in the editor. Replies must follow the refund policy and the brand voice, and neither should be re-typed into the chat by each agent.

Create one context per concern, then reference both in the message:

POST /v1/conversations/support-reply-8842/messages
Content-Type: application/json
Authorization: Bearer <your-token>

{
  "prompt": "Draft a reply to this customer asking for a refund 40 days after purchase.",
  "model": "agent-1",
  "content": [
    {
      "type": "context",
      "id": "refund-policy"
    },
    {
      "type": "context",
      "id": "brand-voice"
    },
    {
      "type": "file",
      "id": "file-XYZ12345"
    }
  ]
}

The refund-policy context contributes the policy PDF plus a prompt explaining how to communicate exceptions; brand-voice contributes the tone rules. The agent’s own uploaded file – the customer’s order confirmation – is attached alongside them in the same content array.

A newsroom runs a house style check before publishing. The style rules are long, change often, and are owned by the editorial team rather than engineering – a perfect fit for a context-driven custom review with no prompt in the request at all:

POST /v1/reviews/custom/calls
Content-Type: application/json
Authorization: Bearer <your-token>

{
  "content": [
    {
      "type": "text",
      "content": "<p data-id=\"p1\">The company said it's product is the best on the market.</p>"
    }
  ],
  "model": "agent-1",
  "contexts": [
    {
      "type": "context",
      "id": "editorial-standards"
    }
  ]
}

Editors maintain editorial-standards through the admin API. Engineering never redeploys to change what the review checks.

A software vendor translates release notes into eight languages. Product names, UI labels, and legal terms must be translated consistently, so a translation-glossary context holds a glossary spreadsheet exported to Markdown plus a prompt with the do-not-translate list.

The glossary is attached to the built-in translate system action:

POST /v1/actions/system/translate/calls
Content-Type: application/json
Authorization: Bearer <your-token>

{
  "content": [
    {
      "type": "text",
      "content": "<p>The new Track Changes sidebar groups suggestions by author.</p>"
    }
  ],
  "args": {
    "language": "German"
  },
  "contexts": [
    {
      "type": "context",
      "id": "translation-glossary"
    }
  ]
}

System actions accept contexts the same way custom ones do, so you get organization-specific behavior without giving up the tuned system prompts.

Some rules should never be optional. A regulated financial services company must apply its disclosure rules to every AI-generated word, regardless of which feature produced it and whether the client remembered to ask.

Set autoApply on the context and it is injected into matching calls without the caller passing its id:

PATCH /v1/admin/contexts/brand-voice
Content-Type: application/json
Authorization: Bearer <admin-token>

{
  "autoApply": {
    "features": [ "conversations" ]
  }
}

Because auto-applied prompts and files consume part of the model’s context window on every call, keep globally applied contexts short and reserve large reference documents for contexts that are referenced explicitly.

A context can be connected to an MCP server instead of – or in addition to – holding uploaded files. MCP (Model Context Protocol) is the open standard that internal systems increasingly speak: knowledge bases and wikis, product and pricing catalogs, help-desk and ticketing tools, document management systems. Where such a server exists, the context can serve the material it publishes rather than copies of it.

The business case is staleness. An uploaded file is a copy, so the moment the original changes the context is out of date and someone has to remember to upload the new version – which means the AI keeps answering from last quarter’s price list or a superseded policy. An MCP-connected context has nothing to keep in sync: the documents it offers are the documents the MCP server publishes, read at the moment of the call.

A support organization answers customer questions in the editor. The product documentation lives in the company wiki, which is updated several times a week by the product team – who will never remember to notify anyone that an AI context needs refreshing.

The company’s wiki already exposes an MCP server, so an administrator connects the context to it once by name:

POST /v1/admin/contexts
Content-Type: application/json
Authorization: Bearer <admin-token>

{
  "id": "product-knowledge-base",
  "name": "Product knowledge base",
  "description": "Live product documentation served from the internal wiki.",
  "mcpServerId": "internal-wiki"
}

From that point on, every document the MCP server publishes is available to the context. Nobody uploads anything, and nothing goes stale.

For the people writing the integration, nothing changes. An MCP-connected context is referenced exactly like any other:

POST /v1/conversations/support-reply-8842/messages
Content-Type: application/json
Authorization: Bearer <your-token>

{
  "prompt": "Does our current plan allow exporting comments to PDF?",
  "model": "agent-1",
  "content": [
    {
      "type": "context",
      "id": "product-knowledge-base"
    }
  ]
}

That is the practical payoff: the source of truth can move from a PDF to a wiki to a different vendor’s MCP server, and the application code keeps referencing product-knowledge-base.

A whole knowledge base is a lot of material to put behind a single question. When the relevant document is known – for example an onboarding flow that always explains the latest release – reference just that one, which keeps answers focused and costs down:

POST /v1/conversations/onboarding-114/messages
Content-Type: application/json
Authorization: Bearer <your-token>

{
  "prompt": "Summarize what changed for administrators in the latest release.",
  "model": "agent-1",
  "content": [
    {
      "type": "context",
      "id": "product-knowledge-base",
      "fileId": "wiki%3A%2F%2Fspaces%2Fproduct%2Fpages%2Frelease-notes"
    }
  ]
}

To find out what an MCP-connected context currently offers – for instance to build a document picker – list its files. Items coming from the MCP server are marked with "source": "mcp", and their id is the address the MCP server uses for that document rather than a generated file id, so treat it as an opaque string:

GET /v1/admin/contexts/product-knowledge-base/files
Authorization: Bearer <admin-token>

{
  "items": [
    {
      "id": "wiki%3A%2F%2Fspaces%2Fproduct%2Fpages%2Frelease-notes",
      "name": "Release notes",
      "mediaType": "text/markdown",
      "source": "mcp",
      "createdAt": "2026-07-20T09:12:44.000Z",
      "updatedAt": "2026-07-29T16:03:10.000Z"
    }
  ]
}

• Which MCP servers may be used is a service-level decision. The servers CKEditor AI may reach, and the credentials it uses, are configured once when the service is deployed. Administrators then connect contexts to those approved servers by name; they cannot point a context at an arbitrary URL. Naming a server that is not available is rejected outright.
• Available on-premises. MCP connectivity is part of the on-premises version. See MCP support for how servers are configured, including OAuth for systems where each user signs in individually.
• Uploaded files and MCP documents can coexist. An MCP-connected context still holds prompts and uploaded files of its own – useful for pairing a stable policy PDF and a house-style prompt with a live catalog.
• Disconnecting is reversible. Setting mcpServerId to null in an update detaches the MCP server and leaves the context’s own prompts and uploaded files untouched.

Authoring requires ai:admin. Consumption is granted per context, by exact id or pattern:

{
  "auth": {
    "ai": {
      "permissions": [
        "ai:conversations:read",
        "ai:conversations:write",
        "ai:models:agent",
        "ai:contexts:brand-voice",
        "ai:contexts:team-marketing-*"
      ]
    }
  }
}

See Context Library permissions for the full pattern syntax.

For complete endpoint documentation, request/response schemas, and error codes, see:

• Context API Reference – Listing and reading the contexts a caller may use.
• Context Admin API Reference – Managing contexts, prompts, and files.