REST and MCP API

Prerequisites

• knowmind account on Business API or Enterprise (for personal API tokens and 60+ requests per minute)
• API token of the form kmt_… (see: Create an API token)
• TLS-capable HTTP client in your language of choice

Steps

1. 1

   Endpoint and authentication

   All requests go to https://knowmind.de. Authentication is via the Authorization: Bearer kmt_… header.

   textcopy

   REST:  https://knowmind.de/api/v1/...
   MCP:   https://knowmind.de/api/mcp/v1
   Auth:  Authorization: Bearer kmt_…

   Outcome: curl -H "Authorization: Bearer kmt_…" https://knowmind.de/api/health returns a success message.

2. 2

   REST example: search and store

   curl:

   bashcopy

   # Search
   curl -X POST https://knowmind.de/api/v1/memory/recall \
     -H "Authorization: Bearer kmt_…" \
     -H "Content-Type: application/json" \
     -d '{
       "query": "Who is the onboarding contact?",
       "k": 5,
       "hops": 2,
       "use_graph": true
     }'
   
   # Create a memory
   curl -X POST https://knowmind.de/api/v1/memory/entries \
     -H "Authorization: Bearer kmt_…" \
     -H "Content-Type: application/json" \
     -d '{
       "memory_type": "semantic",
       "title": "QM training mandatory",
       "content": "All service staff complete the QM training annually.",
       "tags": ["qm", "training"],
       "source": "internal-handbook"
     }'

   TypeScript (Node 20+):

   tscopy

   const TOKEN = process.env.KNOWMIND_TOKEN!;
   const BASE = "https://knowmind.de/api/v1";
   
   async function recall(query: string, k = 5) {
     const r = await fetch(`${BASE}/memory/recall`, {
       method: "POST",
       headers: {
         Authorization: `Bearer ${TOKEN}`,
         "Content-Type": "application/json",
       },
       body: JSON.stringify({ query, k, hops: 2, use_graph: true }),
     });
     if (!r.ok) throw new Error(`recall failed: ${r.status}`);
     return r.json();
   }
   
   const hits = await recall("Who drafted the Müller contract?");
   console.log(hits);

   Python:

   pythoncopy

   import os, requests
   
   TOKEN = os.environ["KNOWMIND_TOKEN"]
   BASE = "https://knowmind.de/api/v1"
   HEADERS = {"Authorization": f"Bearer {TOKEN}", "Content-Type": "application/json"}
   
   def recall(query: str, k: int = 5) -> dict:
       r = requests.post(
           f"{BASE}/memory/recall",
           headers=HEADERS,
           json={"query": query, "k": k, "hops": 2, "use_graph": True},
           timeout=10,
       )
       r.raise_for_status()
       return r.json()
   
   print(recall("GDPR training mandatory?"))

3. 3

   MCP example: JSON-RPC 2.0

   MCP calls are JSON-RPC 2.0 requests against /api/mcp/v1. By default the response is a single JSON object. If you need Streamable HTTP (for native custom connectors), set Accept: text/event-stream.

   bashcopy

   # List tools
   curl -X POST https://knowmind.de/api/mcp/v1 \
     -H "Authorization: Bearer kmt_…" \
     -H "Content-Type: application/json" \
     -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'
   
   # Call recall
   curl -X POST https://knowmind.de/api/mcp/v1 \
     -H "Authorization: Bearer kmt_…" \
     -H "Content-Type: application/json" \
     -d '{
       "jsonrpc": "2.0",
       "id": 2,
       "method": "tools/call",
       "params": {
         "name": "knowmind.recall",
         "arguments": { "query": "When is the next quarterly report due?", "k": 5 }
       }
     }'

   Outcome: The response is a JSON-RPC response object with result (success) or error (failure).

4. 4

   Respect rate limits

   Business API plan: 60 requests per minute. Enterprise: 600. Excess returns HTTP 429 with a Retry-After header in seconds.

   Build a backoff mechanism in your client that reads Retry-After, waits the specified seconds (with jitter) and retries up to three times.

Verify the result

Troubleshooting