Knowcap API Reference

Authentication

Every API request authenticates via the x-api-key header (or Authorization: Bearer ... for raw user tokens). All keys are prefixed kc_live_.

Getting Your API Key

Sign in at app.knowcap.ai
Navigate to Settings → API Keys
Pick the organization the key should bill to (you can own keys for any org you're owner or admin of)
Generate the key and copy it immediately — the full key is shown once and never again

🏢 Keys are pinned to one organization

Each API key is bound to a specific org. That org's api_credits_balance pays for every call made with the key, regardless of which project's data the call references. If you work across multiple orgs, create one key per org and switch which key your client uses.

You can change which org a key bills to without rotating credentials — see Move Key Org.

Example Request

curl https://app.knowcap.ai/api/projects \
  -H "x-api-key: kc_live_YOUR_KEY"

Rate Limits & Credits

A runaway loop hits one of three guard-rails: per-minute rate cap, daily rate cap, or empty credit balance. All three are scoped to the API key's organization.

Per-tier rate limits

Plan	Per minute	Per day
Free	10	100
Pro	60	5,000
Business	120	15,000

Some routes count for more than one request because they're more expensive on the server side:

Route	Cost
POST `/api/chats/:id/messages`	5
POST `/api/chats/:id/generate-title`	5
POST `/api/chats/project/:id/suggested-questions`	5
POST `/api/artifacts/generate`	5
GET `/api/sources/:id/transcriptions`	2
GET `/api/sources/:id/visuals`	2
GET `/api/projects/:id/search`	2
everything else	1

Response on 429

When you hit a limit you receive:

429 Too Many Requests

{
  "error": "Rate limit: 120 requests per minute",
  "retry_after_seconds": 42,
  "plan": "business"
}

A Retry-After header is also set. Back off with exponential delay and resume.

Read-credit gate (402)

Every successful GET debits a sub-cent fee from the key's org credit pool (default 0.1¢ per call, batched). When the balance hits zero, every subsequent GET returns:

402 Payment Required

{
  "success": false,
  "error": "Insufficient API credits...",
  "code": "INSUFFICIENT_ORG_API_CREDITS",
  "balance_cents": 0
}

POST endpoints that drive LLM calls (chat send, artifact generate) have their own token-based debit on top of this and may return 402 even when the read pool isn't exhausted.

🛑 Per-key kill switch

You can pause a leaked or runaway key without deleting it via PATCH /api/users/api-keys/:id/disable. Disabled keys return 401 immediately on the next call. Re-enable with PATCH .../enable. See the API Keys section.

GET /api/users/me

Returns the currently authenticated user's profile, including account details and subscription status.

Request

curl https://app.knowcap.ai/api/users/me \
  -H "x-api-key: YOUR_API_KEY"

Response · 200

{
  "id": "usr_a1b2c3d4",
  "email": "you@example.com",
  "name": "Jane Doe",
  "plan": "pro",
  "createdAt": "2026-01-15T08:30:00Z"
}

GET /api/projects

Retrieve a list of all projects belonging to the authenticated user. Each project contains one or more sources.

Request

curl https://app.knowcap.ai/api/projects \
  -H "x-api-key: YOUR_API_KEY"

Response · 200

[
  {
    "id": "prj_x9k2m1",
    "name": "Product Research",
    "sourceCount": 12,
    "createdAt": "2026-02-01T10:00:00Z",
    "updatedAt": "2026-03-20T14:30:00Z"
  }
]

GET /api/sources/project/{id}

List all sources within a specific project. Sources can be text entries, ingested URLs, uploaded files, or recordings.

Path Parameters

Name	Type	Description
id required	string	The project ID

Request

curl https://app.knowcap.ai/api/sources/project/prj_x9k2m1 \
  -H "x-api-key: YOUR_API_KEY"

Response · 200

[
  {
    "id": "src_f3g7h2",
    "type": "url",
    "title": "Market Analysis Report",
    "url": "https://example.com/report",
    "tags": ["research", "Q1"],
    "status": "completed",
    "createdAt": "2026-02-05T09:15:00Z"
  }
]

GET /api/sources/{id}/transcriptions

Retrieve transcript chunks for a specific source. Returns an array of text segments with timestamps (when available) from audio/video sources, or full text content for text-based sources.

Path Parameters

Name	Type	Description
id required	string	The source ID

Request

curl https://app.knowcap.ai/api/sources/src_f3g7h2/transcriptions \
  -H "x-api-key: YOUR_API_KEY"

Response · 200

{
  "sourceId": "src_f3g7h2",
  "chunks": [
    {
      "index": 0,
      "text": "The market grew 23% year over year...",
      "startTime": 0.0,
      "endTime": 4.5
    },
    {
      "index": 1,
      "text": "Key drivers include AI adoption...",
      "startTime": 4.5,
      "endTime": 9.2
    }
  ]
}

POST /api/sources/text

Create a new text source within a project. The text content will be processed and made searchable within your knowledge base.

Request Body

Field	Type	Description
projectId required	string	Target project ID
title required	string	Display title for the source
content required	string	The text content to ingest
tags	string[]	Optional tags for organization

Request

curl -X POST https://app.knowcap.ai/api/sources/text \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "projectId": "prj_x9k2m1",
    "title": "Meeting Notes — March 2026",
    "content": "Discussed Q1 targets and product roadmap...",
    "tags": ["meetings", "Q1"]
  }'

Response · 201

{
  "id": "src_n4p8q1",
  "type": "text",
  "title": "Meeting Notes — March 2026",
  "status": "processing",
  "createdAt": "2026-03-31T12:00:00Z"
}

POST /api/sources/url

Ingest a URL as a source. Knowcap will fetch the page content, extract text, and process it into your knowledge base. Supports articles, documentation pages, blog posts, and more.

Request Body

Field	Type	Description
projectId required	string	Target project ID
url required	string	The URL to ingest
tags	string[]	Optional tags for organization

Request

curl -X POST https://app.knowcap.ai/api/sources/url \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "projectId": "prj_x9k2m1",
    "url": "https://example.com/interesting-article",
    "tags": ["research"]
  }'

Response · 201

{
  "id": "src_r7t2w5",
  "type": "url",
  "url": "https://example.com/interesting-article",
  "status": "processing",
  "createdAt": "2026-03-31T12:05:00Z"
}

GET /api/users/api-keys

List the caller's keys. Returns each key's prefix (first 12 chars), name, the org it bills to, last-used timestamp, and whether it's currently disabled. Full key values are never returned after creation.

Response · 200

{
  "apiKeys": [
    {
      "id": "d127cbdd-...",
      "name": "MCP Knowcap Key",
      "key_prefix": "kc_live_kXum",
      "org_id": "b7f0489c-...",
      "org_name": "Knowcap",
      "last_used_at": "2026-05-06T15:08:25Z",
      "disabled_at": null,
      "created_at": "2026-04-26T22:29:43Z"
    }
  ]
}

POST /api/users/api-keys

Create a new API key pinned to a specific organization. The full key is returned once in plainKey — store it immediately, you can't fetch it again. To pick the org, call GET /api/users/api-key-orgs for the list of orgs you can target.

Request Body

Field	Type	Description
name	string	Human-readable label (e.g. "MCP Knowcap")
org_id	uuid	Org to bill. You must be owner or admin of it. Defaults to your primary owned org if omitted.

Request

curl -X POST https://app.knowcap.ai/api/users/api-keys \
  -H "x-api-key: kc_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "MCP Knowcap",
    "org_id": "b7f0489c-..."
  }'

Response · 201

{
  "success": true,
  "apiKey": {
    "id": "...",
    "name": "MCP Knowcap",
    "key_prefix": "kc_live_aBcD",
    "org_id": "b7f0489c-...",
    "plainKey": "kc_live_aBcD..."
  }
}

PATCH /api/users/api-keys/{id}/org

Move an existing key to a different org without rotating credentials. Requires owner or admin membership on the new org. The key string itself does not change — same secret, new biller.

Request

curl -X PATCH https://app.knowcap.ai/api/users/api-keys/d127cbdd-.../org \
  -H "x-api-key: kc_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "org_id": "d9196fb2-..." }'

PATCH /api/users/api-keys/{id}/disable

Soft-revoke a key. authenticateApiKey rejects the key on the next call — the kill switch is effectively instant. Use .../enable with the same id to bring it back. Pass an optional reason for audit.

Disable

curl -X PATCH https://app.knowcap.ai/api/users/api-keys/{id}/disable \
  -H "x-api-key: kc_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "reason": "leaked in repo" }'

Re-enable

curl -X PATCH https://app.knowcap.ai/api/users/api-keys/{id}/enable \
  -H "x-api-key: kc_live_..."

GET /api/users/api-keys/{id}/usage

Per-key usage roll-up: 24-hour and 30-day call counts plus total bytes-out. Powered by the api_key_usage_summary view — every kc_live_ request inserts an audit row used to compute these.

Response · 200

{
  "usage": {
    "api_key_id": "d127cbdd-...",
    "name": "MCP Knowcap",
    "key_prefix": "kc_live_kXum",
    "calls_24h": 42,
    "bytes_out_24h": 3934558,
    "calls_30d": 1207,
    "bytes_out_30d": 128403211,
    "last_used_at": "2026-05-06T15:08:25Z",
    "disabled_at": null
  }
}

GET /api/projects/{id}/search

Unified search across a project's transcripts, memories, and artifacts in one round trip. Transcript hits are scored by RAG similarity; memory and artifact hits use case-insensitive substring match. Each hit carries the source id and (when available) start_time for direct deep-linking into a meeting.

Query Parameters

Name	Type	Description
q required	string	Plain-text query (1–500 chars)
kinds	string	Comma-separated subset of `transcript,memory,artifact`. Default: all three
limit	int	Max hits per kind (1–50). Default 10

Request

curl "https://app.knowcap.ai/api/projects/{id}/search?q=invoice&limit=5" \
  -H "x-api-key: kc_live_..."

Response · 200

{
  "project_id": "b58a4c12-...",
  "query": "invoice",
  "kinds": ["transcript", "memory", "artifact"],
  "total": 7,
  "hits": [
    {
      "kind": "memory",
      "memory_id": "...",
      "memory_category": "task",
      "source_id": "...",
      "source_name": "Q1 invoice review",
      "snippet": "Send invoice to Acme by EOW...",
      "start_time": 126,
      "score": null
    }
  ]
}

GET /api/projects/{id}/memories

Auto-extracted memories — open tasks, risks, decisions, facts, and people — with source-level permalinks. Each memory carries category, summary, structured fields specific to its category (e.g. tasks have title/status/assignee/deadline), and the underlying source's start_time when extracted from a recording.

Query Parameters

Name	Type	Description
category	string[]	Filter by category. Repeat the param for OR: `?category=task&category=decision`
status	string	Comma-separated review statuses. Default: `pending,confirmed,edited`. Available: `pending,confirmed,edited,rejected,auto_rejected`
source	string	`chat` or `recording`
sourceId	uuid	Restrict to memories tied to one source
limit	int	1–200, default 50
offset	int	Pagination offset. Default 0

GET /api/sources/{id}/visuals

Visual frames extracted from a recording (Vision/screen-share JPEGs). Each frame has a public Supabase Storage URL, the AI-generated caption, and the start_time so you can deep-link directly into the meeting at that moment.

Query Parameters

Name	Type	Description
startTime	number	Window start in seconds (inclusive)
endTime	number	Window end in seconds (inclusive)
limit	int	1–500, default 200

Request

curl "https://app.knowcap.ai/api/sources/{id}/visuals?startTime=60&endTime=180" \
  -H "x-api-key: kc_live_..."

Response · 200

{
  "source_id": "...",
  "project_id": "...",
  "total": 12,
  "visuals": [
    {
      "id": "...",
      "start_time": 63.2,
      "end_time": 68.0,
      "frame_url": "https://....supabase.co/storage/.../frame.jpg",
      "caption": "[Screen: Plan & Billing settings, Current Balance 5,000]",
      "type": "visual"
    }
  ]
}

PATCH /api/sources/{id}

Update metadata for an existing source. Use this to modify tags, title, or other mutable properties. Only provided fields will be updated.

Path Parameters

Name	Type	Description
id required	string	The source ID

Request Body

Field	Type	Description
title	string	New display title
tags	string[]	Replace tags array

Request

curl -X PATCH https://app.knowcap.ai/api/sources/src_f3g7h2 \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Updated Report Title",
    "tags": ["research", "updated", "Q1"]
  }'

Response · 200

{
  "id": "src_f3g7h2",
  "type": "url",
  "title": "Updated Report Title",
  "tags": ["research", "updated", "Q1"],
  "updatedAt": "2026-03-31T12:10:00Z"
}

MCP — Model Context Protocol

Knowcap ships an MCP server (Knowcap-V2/knowcap-mcp) that exposes the API as MCP tools, resources, and slash prompts. Wire it into Claude Code, Claude Desktop, or any other MCP-aware client and the model can read/write Knowcap directly without you copying keys around.

Claude Code setup

Install npm install -g @knowcap-v2/knowcap-mcp (or run from a local clone)
Open ~/.claude.json and add the server config below
Restart Claude Code or run /mcp to reconnect

~/.claude.json (snippet)

{
  "mcpServers": {
    "knowcap": {
      "type": "stdio",
      "command": "node",
      "args": ["/path/to/knowcap-mcp/dist/index.js"],
      "env": {
        "KNOWCAP_API_KEY": "kc_live_...",
        "KNOWCAP_API_URL": "https://app.knowcap.ai",
        "KNOWCAP_APP_URL": "https://app.knowcap.ai"
      }
    }
  }
}

Working across multiple orgs? Create one key per org and run multiple MCP servers (one per Knowcap account context) — see Authentication.

MCP Tool Reference

25 tools across projects, sources, memories, artifacts, chats, speakers, plus three meta-tools added in v1.1 for digest, search, and visual frames.

Projects & users

Tool	What it does
`get_me`	Current user the API key belongs to
`list_projects`	Every project the user can access
`get_project`	Single project by id
`digest_project` ⚡	One-shot bundle: open tasks/risks/decisions/facts + recent sources/artifacts/chats with permalinks
`search_project` ⚡	Unified RAG + ilike across transcripts, memories, artifacts

Sources

Tool	What it does
`list_sources`	Sources in a project (meetings, recordings, documents)
`get_source`	Source metadata + signed file_url
`get_source_transcriptions`	Transcript with clickable `[mm:ss]` permalinks; supports startTime/endTime windowing
`get_source_visuals` ⚡	Visual frames (JPEG URLs + AI captions + timestamps)

Memories

Tool	What it does
`search_memories`	Filter by category, status, source kind/id; permalinks included
`get_memory`	Single memory by id (list-and-filter under the hood)
`update_memory_review`	Confirm / reject / edit a pending auto-extracted memory

Artifacts

Tool	What it does
`list_artifacts`	Project artifacts (notes, summaries, docs)
`get_artifact`	Full artifact body
`create_artifact`	Create a new artifact from raw content
`update_artifact`	Patch title / content / type
`generate_artifact`	Ask Knowcap AI to write the artifact (token-billed)

Chats

Tool	What it does
`list_chats` / `get_chat`	Project's chat threads
`create_chat`	New thread (no message)
`list_chat_messages`	Message history
`send_chat_message`	Post a user message; backend runs the agentic chat pipeline (token-billed, weight 5)

Speakers

Tool	What it does
`list_speakers`	Roster across all of a project's recordings
`get_speaker`	Single speaker (list-and-filter)

Slash prompts

Pre-built workflows the MCP exposes to models:

/knowcap-meeting-debrief — full debrief of a meeting source
/knowcap-open-tasks — every unresolved task across a project
/knowcap-decision-log — confirmed decisions only
/knowcap-risks-watch — open risks ranked by severity
/knowcap-people-brief — speaker timeline + memories per person

⚡ marks tools added in v1.1.