# Knolo — Developer documentation (full text)

> Knolo is the no-code AI operating system that turns your knowledge into assistants, agents, workflows, and internal tools.

This file concatenates Knolo's developer documentation for LLM ingestion. The canonical HTML versions are linked above each section.

---

Source: https://www.knolo.io/docs/connectors

# Knolo Connector (MCP): connect Cursor, Claude, and ChatGPT to your Space

A **Knolo Connector** is a per-Space remote [Model Context Protocol](https://modelcontextprotocol.io) (MCP) server. It lets external AI clients — Cursor, Claude, ChatGPT, and any MCP-capable agent — search your Space's knowledge, read its Minds, ask its Assistants, and run its Agents through one authenticated endpoint. A Connector has full **read** access to the whole Space; a single **Allow writes** switch decides whether it can also make changes.

If you just want to read and write your knowledge base over plain HTTP instead, use the [Knolo CMS API](/docs/cms-api).

## What is a Knolo Connector?

A Connector turns a Knolo Space into a backend for someone else's agent. Where the [CMS API](/docs/cms-api) is a REST surface for data, a Connector speaks MCP — the open protocol that AI clients use to discover and call **tools**, read **resources**, and load **prompts**. One Connector always belongs to exactly one Space.

- **Tools** let a client take actions: search knowledge, ask an Assistant, run an Agent.
- **Resources** expose your Minds and files as read-only context the client can pull in.
- **Prompts** expose your Knolo Skills as reusable starting instructions.

## How it works

1. A Space owner or editor creates a Connector in **Space Settings → Connectors**. Knolo shows a secret key (prefix `knc_`) exactly once.
2. You add the Connector's **endpoint URL** and key to your MCP client.
3. The client connects over MCP **Streamable HTTP** and discovers the tools, resources, and prompts the **Connector Policy** allows.
4. Every paid action (asking an Assistant, running an Agent) is billed to the Space's wallet and attributed to the Connector.

The endpoint is stateless: conversation memory for `ask_assistant` is anchored to a stable thread per Connector (optionally per `conversationId`), so follow-up questions keep context.

## Before you start

- You need a Knolo Space and the **owner** or **editor** role.
- Decide whether the Connector may make changes. Read access covers the whole Space; writes and Agent runs are off until you turn on **Allow writes**.
- Have your MCP client ready (Cursor, Claude Desktop, ChatGPT, or your own agent).

## Create a connector

1. Open **Space Settings → Connectors**.
2. Copy the **MCP endpoint URL** shown at the top of the section. It looks like:

```text
https://europe-west3-knowledgio-v3.cloudfunctions.net/mcp
```

3. Click **Create connector**, give it a label (e.g. "Cursor"), and set its policy:
   - **Allow writes** — off by default. When off, the Connector has full read access to the whole Space (all Minds, all Assistants) but cannot change anything. When on, it can also `write_file`, `upload_file`, use the Assistant's write/integration tools, and run any Agent (`run_agent`).
   - **Credit ceiling** — an optional spend cap for this Connector.
4. Copy the generated key (prefix `knc_`) immediately. You will not be able to see it again.

   Read access is always Space-wide: every Mind is searchable and any Assistant can be asked. There are no per-Mind, per-Assistant, or per-Agent allowlists.

## Connect your client

Authenticate with the key as a Bearer token: `Authorization: Bearer knc_your_key`.

### Cursor

Add the server to an `mcp.json` file. Cursor reads two locations, and where you put the file decides the scope:

- **Project-bound** — `.cursor/mcp.json` at the project root. The Connector is available only inside that project and is shared with anyone who has the repo. Best for a team that should all reach the same Space.
- **Global** — `~/.cursor/mcp.json`. The Connector is available in every project for just your machine. Best for a personal key you do not want to commit.

Either way the contents are the same (Cursor Settings → MCP → Add new server writes the same JSON):

```json
{
  "mcpServers": {
    "knolo": {
      "url": "https://europe-west3-knowledgio-v3.cloudfunctions.net/mcp",
      "headers": {
        "Authorization": "Bearer knc_your_key"
      }
    }
  }
}
```

> **Heads up:** a project-bound `.cursor/mcp.json` is normally committed to git, so the `knc_` key would be exposed to everyone with repo access. If you commit it, either add `.cursor/mcp.json` to `.gitignore` or keep the key in the global `~/.cursor/mcp.json` instead. Because each Connector can be revoked independently, use a dedicated Connector for a shared project so you can rotate it without affecting anyone else.

### Claude Desktop

Add a remote MCP server in **Settings → Connectors** (or your `claude_desktop_config.json`) pointing at the same URL with the same `Authorization` header. For clients that only support local (stdio) servers, bridge to the remote endpoint with a tool such as `mcp-remote`.

### ChatGPT and other agents

Any MCP-capable client works: provide the endpoint URL and the `Authorization: Bearer knc_your_key` header. The client will list the tools and resources your policy permits.

### Verify the connection

After connecting, your client lists the tools your policy permits, led by `ask_assistant`. The simplest test is to just talk to the Assistant: "Ask my Knolo assistant to summarize our refund policy." (Direct helpers like `search_knowledge` exist too, but `ask_assistant` is the main way in.)

## Tools

**`ask_assistant` is the primary interface.** For almost everything — answering questions, finding or summarizing knowledge, and (when writes are on) creating or editing files and getting work done — call `ask_assistant`. The Assistant has the Space's full knowledge and tools: it does the task and replies, and you can then read any file it created. The other tools are narrow helpers, not the default path. If a client ever reports it "has no tool" for a request, the answer is almost always to route that request through `ask_assistant`.

Read tools are always available; write/agent tools appear only when **Allow writes** is on.

| Tool | Available | Purpose |
| --- | --- | --- |
| `ask_assistant` | Always | **Start here.** Ask any Space Assistant in natural language to answer, search, or (with writes) author/edit files and do work. Pass a stable `conversationId` to keep memory across calls. |
| `search_knowledge` | Always | Quick read-only lookup returning raw passages. For real questions, prefer `ask_assistant`. |
| `list_minds` | Always | List the Space's Minds. |
| `run_agent` | When writes are allowed | Start a named Space Agent asynchronously; returns a `runId`. |
| `get_run` | When writes are allowed | Poll an Agent run by `runId` for status and output. |
| `write_file` | When writes are allowed | Persist **verbatim text the client already holds**. Prefer `ask_assistant` to author content. |
| `upload_file` | When writes are allowed | Upload **local file bytes** (PDF, image, spreadsheet, …) the client is holding. Only for explicit uploads — not for "create a file". |

When writes are disabled (the default), only a safe read-only subset of the Assistant's own tools is available inside `ask_assistant` — no file writes, agent calls, or integration actions. Agents are gated by the same switch because they can write and call integrations.

### Creating files: prefer the Assistant

To put content into a Mind, the default is to **ask the Assistant to create it**. The Assistant has the Space's knowledge and data, writes the file, and replies; the client then just reads the finished file (via `search_knowledge` or the `knolo://minds/...` resources). Reserve the direct file tools for these specific cases:

- `write_file` — the client already holds the exact verbatim text and explicitly wants it stored as-is.
- `upload_file` — the client is holding **local file bytes** (a PDF, image, spreadsheet, large document) that must be uploaded. This is the one thing the Assistant cannot do for you. Steps:
  1. Call `upload_file` with the `mindId`, `filename` (with extension), and optional `contentType`. It returns a short-lived `upload.url`.
  2. `PUT` the raw file bytes to that URL, sending the exact `Content-Type` header it returns.
  3. The file is parsed and indexed automatically once the upload finishes — there is no follow-up call.

## Resources

Connectors expose read-only MCP resources for the whole Space:

- `knolo://minds` — a JSON index of the Space's Minds.
- `knolo://minds/{mindId}/{fileId}` — the contents of a file inside a Mind. Binary files return a download pointer instead of bytes.

## Prompts (Knolo Skills)

Your Space's available **Knolo Skills** are exposed as MCP prompts. Selecting one returns the Skill's blueprint as a starting instruction your client can adopt. Skills are read-only context here; they do not unlock extra tools on the Connector.

## The Connector Policy

The **Connector Policy** is the set of governance rules attached to a Connector: whether writes are allowed and an optional credit ceiling. Read access always spans the whole Space.

- **Read-only by default.** A new Connector can search all Minds and ask any Assistant, but cannot change anything until **Allow writes** is on.
- **Writes are all-or-nothing.** Turning on **Allow writes** unlocks file writes/uploads, the Assistant's write and integration tools, and Agent runs together.
- **Edit anytime.** Toggle a Connector's writes, disable it, or revoke it from **Space Settings → Connectors**. Revoking invalidates the key immediately.

## Billing and limits

- Connector work is billed to the Space's Billing Account, attributed to the Connector.
- A pre-flight balance check blocks new paid turns when the wallet is empty.
- An optional per-Connector **credit ceiling** caps how much a single Connector can spend.
- `search_knowledge`, `list_minds`, and resource reads are lightweight; `ask_assistant` and `run_agent` consume credits like normal Assistant and Agent runs.

## Security

- Keys are shown once and stored only as a SHA-256 hash — Knolo cannot recover a lost key. Create a new one if you lose it.
- Each Connector is **bound to the member who created it**. If that member leaves the Space (loses participation), the Connector key stops working automatically — a credential never outlives its owner's access.
- Use a separate Connector per client so you can revoke one without affecting others.
- Keep `Allow writes` off unless a client genuinely needs to write back.
- Disable or revoke a Connector the moment a client no longer needs access.

## Troubleshooting

- **401 Unauthorized** — the key is missing, malformed, disabled, or revoked. Confirm the `Authorization: Bearer knc_...` header and that the Connector is enabled.
- **`ask_assistant` says there are no assistants** — the Space itself has no assistants yet. Create one in the Space first.
- **"Out of credits"** — top up the Space's Billing Account, or raise the Connector's credit ceiling.
- **`run_agent` / write tools not visible** — they only appear when `Allow writes` is on.

## FAQ

### What is the difference between a Connector and the CMS API?
The [CMS API](/docs/cms-api) is a REST interface for reading and writing Minds and entries over HTTP. A Connector is an MCP server that lets AI clients call tools, read resources, and load prompts — including delegating to your Assistants and Agents.

### Which clients can connect?
Any MCP-capable client, including Cursor, Claude Desktop, ChatGPT, and custom agents built on the MCP SDK.

### Is a Connector read-only?
Yes by default — it can read the whole Space but not change anything. Writes, Agent execution, and integration actions turn on together via the per-Connector **Allow writes** switch.

### How do I revoke access?
Open Space Settings → Connectors and revoke the Connector. Its key stops working immediately. A Connector also stops working automatically if the member who created it leaves the Space.

### What happens to a Connector when its creator leaves the space?
It is disabled automatically. Each Connector is bound to its creator, and its key is rejected once that member is no longer a participant of the Space. If they rejoin, the key works again; to keep access permanently, have a current member recreate the Connector.

## Related

- [Knolo CMS API](/docs/cms-api) — REST access to Minds and entries.
- [Documentation overview](/docs) — Spaces, Minds, Assistants, Agents, Triggers.
- [Model Context Protocol](https://modelcontextprotocol.io) — the open standard Connectors implement.

---

Source: https://www.knolo.io/docs/cms-api

# Knolo CMS API: read and write your Minds over REST

The **Knolo CMS API** is a REST interface for a single Space's knowledge. Use it to list and search **Minds** (knowledge bases), read and write their **entries** (files and table rows), and manage Minds programmatically — authenticated with a Space-scoped API key. It is the headless way to use Knolo as a content backend for your own website or service.

If instead you want an AI client like Cursor, Claude, or ChatGPT to use your Space through tools and prompts, use the [Knolo Connector (MCP)](/docs/connectors).

## Base URL

```text
https://api.knolo.io
```

All CMS endpoints are under the `/cms` path, e.g. `https://api.knolo.io/cms/minds`.

- **Interactive reference (Swagger UI):** [https://api.knolo.io/cms/docs](https://api.knolo.io/cms/docs)
- **OpenAPI document (JSON):** [https://api.knolo.io/cms/api-json](https://api.knolo.io/cms/api-json)

## Authentication

Every request must send a Space-scoped API key (prefix `kn_`) as a Bearer token:

```text
Authorization: Bearer kn_your_key
```

Create and revoke keys in **Space Settings → API Access**. A key is shown once and grants access to exactly one Space. Missing or invalid keys return `401`.

## Minds and entries

A **Mind** is a knowledge base. There are two kinds:

- **Document minds** (`dataType: "default"`) hold files — text, Markdown, PDFs, images, and data files. Indexable document minds are chunked and searchable.
- **Table minds** (`dataType: "table"`) hold structured rows validated against a schema.

An **entry** is one item in a Mind: a file in a document mind, or a row in a table mind.

## Quick start

List your Minds:

```bash
curl https://api.knolo.io/cms/minds \
  -H "Authorization: Bearer kn_your_key"
```

Create a text file in a document mind:

```bash
curl -X POST https://api.knolo.io/cms/minds/MIND_ID/entries \
  -H "Authorization: Bearer kn_your_key" \
  -H "Content-Type: application/json" \
  -d '{ "filename": "notes.md", "content": "# Meeting notes\nShip the API." }'
```

## Endpoints

### Minds

| Method | Path | Description |
| --- | --- | --- |
| GET | `/cms/minds` | List Minds in the Space. Query: `limit` (max 100), `offset`. |
| GET | `/cms/minds/{mindId}` | Get one Mind's metadata. |
| POST | `/cms/minds` | Create a Mind. Body: `name`, optional `description`, `indexable`, `dataType`, `schema`, `folderId`. |
| PATCH | `/cms/minds/{mindId}` | Update `name`, `description`, `indexable`, `schema`, or `folderId`. |
| DELETE | `/cms/minds/{mindId}` | Delete a Mind and all of its entries. |

### Entries

| Method | Path | Description |
| --- | --- | --- |
| GET | `/cms/minds/{mindId}/entries` | List or query entries. Query: `limit`, `offset`; table minds also accept `filters`, `sortBy`, `sortDirection`. |
| GET | `/cms/minds/{mindId}/entries/{entryId}` | Get one entry's metadata (and `structuredData` for table rows). |
| GET | `/cms/minds/{mindId}/entries/{entryId}/download` | Get file content (text) or a `downloadUrl` (binary/media). |
| POST | `/cms/minds/{mindId}/entries` | Create an entry (see below). |
| PATCH | `/cms/minds/{mindId}/entries/{entryId}` | Update an entry (see below). |
| DELETE | `/cms/minds/{mindId}/entries/{entryId}` | Delete a file or table row. |

## Creating entries

The request body depends on the Mind's kind.

**Table mind** — provide `data`, a row object matching the Mind's schema:

```bash
curl -X POST https://api.knolo.io/cms/minds/MIND_ID/entries \
  -H "Authorization: Bearer kn_your_key" \
  -H "Content-Type: application/json" \
  -d '{ "data": { "title": "Refund policy", "status": "published" } }'
```

**Document mind, text** — provide `filename` and `content`:

```json
{ "filename": "policy.md", "content": "Our refund policy..." }
```

**Document mind, binary upload** — provide `filename` and `contentBase64` (base64-encoded bytes, max 20 MB) for PDFs, images, or spreadsheets:

```json
{ "filename": "report.pdf", "contentBase64": "JVBERi0xLjc..." }
```

## Updating entries

**Table mind** — provide `updates`, a partial row object:

```json
{ "updates": { "status": "archived" } }
```

**Document mind** — provide `content` (with an optional `operation` of `replace`, `append`, or `prepend`) and/or a new `name` to rename:

```json
{ "content": "\n\nAddendum: effective today.", "operation": "append" }
```

## Querying table minds

Pass `filters` as a JSON-encoded array of conditions, plus `sortBy` and `sortDirection`:

```bash
curl -G https://api.knolo.io/cms/minds/MIND_ID/entries \
  -H "Authorization: Bearer kn_your_key" \
  --data-urlencode 'filters=[{"field":"status","op":"==","value":"published"}]' \
  --data-urlencode 'sortBy=createdAt' \
  --data-urlencode 'sortDirection=desc' \
  --data-urlencode 'limit=50'
```

## Pagination

List endpoints accept `limit` and `offset` and return `total` and `hasMore`:

```json
{ "minds": [], "total": 42, "limit": 50, "offset": 0, "hasMore": false }
```

`limit` is capped at 100. Page by increasing `offset` until `hasMore` is `false`.

## Errors

Errors return a JSON body with a `message` and a stable `code`:

```json
{ "error": { "message": "Mind not found", "code": "not_found" } }
```

| HTTP status | Code | Meaning |
| --- | --- | --- |
| 400 | `invalid_argument` | Missing or malformed parameters. |
| 401 | `unauthenticated` | Missing or invalid API key. |
| 404 | `not_found` | The Mind or entry does not exist. |
| 413 | `payload_too_large` | Upload exceeds 20 MB, or storage quota reached. |
| 500 | `internal` | Unexpected server error. |

## Limits

- Maximum `limit` per list request: **100**.
- Maximum binary upload (`contentBase64`, decoded): **20 MB**.
- A key is scoped to one Space; there is no cross-Space access.

## FAQ

### How do I authenticate with the Knolo CMS API?
Send your Space API key (prefix `kn_`) as a Bearer token in the `Authorization` header. Create keys in Space Settings → API Access.

### What is the difference between a document mind and a table mind?
Document minds hold files (text, PDFs, images, data files) and can be indexed for search. Table minds hold structured rows validated against a schema and support filtering and sorting.

### How do I upload a PDF or image?
POST to `/cms/minds/{mindId}/entries` with `filename` and `contentBase64` (base64-encoded file bytes, up to 20 MB).

### Where is the interactive API reference?
The Swagger UI is at https://api.knolo.io/cms/docs and the raw OpenAPI document is at https://api.knolo.io/cms/api-json.

## Related

- [Knolo Connector (MCP)](/docs/connectors) — connect AI clients to your Space.
- [Documentation overview](/docs) — Spaces, Minds, Assistants, Agents, Triggers.
- [Interactive API reference](https://api.knolo.io/cms/docs) — try requests in Swagger UI.