Knowledge API

Add knowledge to your minds via three methods: File, Keyword, or Link. Knowledge is processed, embedded, and automatically retrieved during conversations.

Note: List, add, and delete are available via the v1 API. Knowledge enrichment via keyword search is also supported through the same add endpoint.

Knowledge list and item-status responses are private (Cache-Control: private, no-store). GET /api/v1/minds/{mindId}/knowledge/{itemId}/status returns authoritative mindId and itemId, public processing fields, embedding/pattern counts, and readyForRetrieval. Worker diagnostics and arbitrary stored metadata are omitted; failed processing uses the generic message Knowledge processing failed. Malformed recorded states become unknown. For legacy items without processing metadata, stored embeddings imply completed; otherwise the status is unknown. Missing or blocked credentials return 401, inaccessible Minds or items return 404, and unexpected storage failures return a generic 500.

List Knowledge Items

Retrieve one page of knowledge items for a Mind.

Use limit (1–100, default 100) and offset (non-negative integer, default 0). Items are ordered by createdAt descending, then ID descending. data.total counts all items; data.pagination contains limit, offset and hasMore. While hasMore is true, request the next page with offset + items.length. Pages are not a snapshot: additions or deletions between requests can shift offsets. Invalid or repeated pagination values return 400.

Endpoint: GET /api/v1/minds/{mindId}/knowledge

Headers:

Authorization: Bearer minds_your_api_key

Example:

curl -X GET "https://getminds.ai/api/v1/minds/{mindId}/knowledge?limit=100&offset=0" \
  -H "Authorization: Bearer minds_your_api_key"

Response:

{
  "success": true,
  "data": {
    "items": [
      {
        "id": "660e8400-e29b-41d4-a716-446655440001",
        "description": "Company Employee Handbook 2025",
        "link": null,
        "filePath": "portfolio/user-id/1234567890_handbook.pdf",
        "isWatched": false,
        "createdAt": "2025-12-10T12:00:00.000Z",
        "updatedAt": "2025-12-10T12:00:00.000Z"
      }
    ],
    "total": 1,
    "pagination": { "limit": 100, "offset": 0, "hasMore": false }
  }
}

File Upload

Upload documents or images directly to a mind.

Endpoint: POST /api/v1/minds/{mindId}/knowledge

Content-Type: multipart/form-data

Supported formats:

• Documents: PDF, DOCX, DOC, TXT, MD, RTF, CSV, JSON, XML
• Images: JPG, JPEG, PNG, GIF, WEBP

Example:

curl -X POST "https://getminds.ai/api/v1/minds/{mindId}/knowledge" \
  -H "Authorization: Bearer minds_your_api_key" \
  -F "file=@./handbook.pdf" \
  -F "description=Company Employee Handbook 2025"

Workspace upload URLs require file access independently of Mind-edit access: use an upload you own, a chat-file URL with a valid signature, or a context file shared through the uploader’s Study. Otherwise the request returns 403 Upload access denied. Knowing an object path does not grant access.

API and MCP clients that already have a public, signed, or Minds workspace upload URL can submit the same file as JSON. The server applies SSRF protection and the same 50MB limit before queuing the canonical ingestion workflow:

{
  "file": {
    "name": "handbook.pdf",
    "url": "https://files.example.com/signed/handbook.pdf",
    "type": "application/pdf"
  },
  "description": "Company Employee Handbook 2025",
  "regeneratePrompt": false
}

Response: 202 Accepted

{
  "success": true,
  "data": {
    "id": "660e8400-e29b-41d4-a716-446655440001",
    "description": "Company Employee Handbook 2025",
    "filePath": "portfolio/user-id/1234567890_handbook.pdf",
    "createdAt": "2025-12-10T12:00:00.000Z",
    "processing": { "status": "queued", "regeneratePrompt": false },
    "statusUrl": "/api/v1/minds/{mindId}/knowledge/660e8400-e29b-41d4-a716-446655440001/status"
  }
}

Keyword Search

Add knowledge by searching the web for keywords. Searches Exa and YouTube, extracts content, and adds it to the mind's knowledge base.

Endpoint: POST /api/v1/minds/{mindId}/knowledge

Content-Type: application/json

Send a JSON body with a keywords array (instead of link/file) to trigger web search enrichment.

Example:

curl -X POST "https://getminds.ai/api/v1/minds/{mindId}/knowledge" \
  -H "Authorization: Bearer minds_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"keywords": ["solar panel efficiency", "photovoltaic trends"]}'

Response: 202 Accepted

{
  "success": true,
  "data": {
    "sparkId": "660e8400-e29b-41d4-a716-446655440000",
    "keywords": ["solar panel efficiency", "photovoltaic trends"],
    "queued": true,
    "regeneratePrompt": true,
    "message": "Knowledge enrichment queued with 2 keyword(s)."
  }
}

Note: This is asynchronous. Processing runs in background and may take several minutes.

Link

Add knowledge from a URL. Supports web pages, YouTube videos, and research papers.

Endpoint: POST /api/v1/minds/{mindId}/knowledge

Content-Type: application/json

Example:

curl -X POST "https://getminds.ai/api/v1/minds/{mindId}/knowledge" \
  -H "Authorization: Bearer minds_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"link": "https://example.com/article", "description": "Industry trends article"}'

Response: 202 Accepted

{
  "success": true,
  "data": {
    "id": "660e8400-e29b-41d4-a716-446655440001",
    "link": "https://example.com/article",
    "description": "Industry trends article",
    "createdAt": "2025-12-10T12:00:00.000Z",
    "processing": { "status": "queued", "regeneratePrompt": false },
    "statusUrl": "/api/v1/minds/{mindId}/knowledge/660e8400-e29b-41d4-a716-446655440001/status"
  }
}

Supported link types:

• Web pages (content extracted via scraping)
• YouTube videos (transcripts extracted automatically)
• Research papers (arxiv, etc.)

Processing Status

File and link uploads are accepted durably and processed by the background worker. Poll the returned statusUrl before using sourcePolicy: "knowledge_only".

Endpoint: GET /api/v1/minds/{mindId}/knowledge/{itemId}/status

{
  "data": {
    "itemId": "660e8400-e29b-41d4-a716-446655440001",
    "mindId": "550e8400-e29b-41d4-a716-446655440000",
    "description": "Company Employee Handbook 2025",
    "status": "completed",
    "readyForRetrieval": true,
    "embeddings": 12,
    "patterns": 5,
    "promptRegenerated": true,
    "updatedAt": "2026-08-05T15:30:00.000Z"
  }
}

Statuses are queued, running, completed, failed, or unknown. Invalid recorded states are unknown; legacy items without processing metadata use completed when embeddings exist, otherwise unknown. A completed item is retrieval-ready only when it has at least one embedding.

The readiness fields have distinct meanings:

• data.status is the durable background-processing state.
• data.readyForRetrieval is true only when processing completed and at least one embedding exists. Use this as the chat readiness gate.
• data.embeddings is the number of stored retrieval embeddings for this item.
• data.patterns is the number of thinking-pattern rows extracted from this item. It can be 0 even when retrieval is ready.
• data.error is the generic message Knowledge processing failed when status is failed; internal worker diagnostics are omitted.
• data.promptRegenerated reports whether the optional prompt-regeneration step completed. It is present only when recorded by processing.

The endpoint returns 401 for missing, invalid, or blocked credentials, and 404 when the Mind is inaccessible or the knowledge item does not belong to it. Unexpected storage failures return a generic 500.

Watch (Auto-Update)

Link-based knowledge items can be "watched" to automatically check for content updates on a weekly cycle. When changes are detected, knowledge is reprocessed and re-embedded.

Watch is managed through the product UI. Watch status is visible when listing knowledge items via the API (isWatched field).

Note: Watch is only available for link-based knowledge, not files or keyword searches.

Update Knowledge Item

Update the description of an existing knowledge item.

Endpoint: PUT /api/v1/minds/{mindId}/knowledge/{itemId}

Headers:

Authorization: Bearer minds_your_api_key
Content-Type: application/json

Request Body:

{
  "description": "Updated description for this knowledge item"
}

Example:

curl -X PUT "https://getminds.ai/api/v1/minds/{mindId}/knowledge/{itemId}" \
  -H "Authorization: Bearer minds_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"description": "Updated handbook description"}'

Response:

{
  "success": true,
  "data": {
    "id": "660e8400-e29b-41d4-a716-446655440001",
    "description": "Updated handbook description",
    "link": null,
    "filePath": "portfolio/user-id/1234567890_handbook.pdf",
    "isWatched": false,
    "createdAt": "2025-12-10T12:00:00.000Z",
    "updatedAt": "2025-12-15T08:30:00.000Z"
  }
}

Error Responses

400 Bad Request - No valid fields to update or empty description

401 Unauthorized - Invalid or missing API key

404 Not Found - Knowledge item or mind not found

Enrich via Keywords (Convenience)

Convenience alias for keyword-based knowledge enrichment.

Endpoint: POST /api/v1/minds/{mindId}/knowledge/enrich

This is equivalent to POST /api/v1/minds/{mindId}/knowledge with a keywords body. See Keyword Search for full details.

Example:

curl -X POST "https://getminds.ai/api/v1/minds/{mindId}/knowledge/enrich" \
  -H "Authorization: Bearer minds_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"keywords": ["solar panel efficiency", "photovoltaic trends"]}'

Delete Knowledge Item

Permanently delete a knowledge item and all associated data (embeddings, patterns, files).

Endpoint: DELETE /api/v1/minds/{mindId}/knowledge/{itemId}

Headers:

Authorization: Bearer minds_your_api_key

Example:

curl -X DELETE "https://getminds.ai/api/v1/minds/{mindId}/knowledge/{itemId}" \
  -H "Authorization: Bearer minds_your_api_key"

Response: 204 No Content (empty body on success)

What Gets Deleted

• The knowledge item record
• All associated vector embeddings
• All associated patterns
• Uploaded file from storage (if file-based)

Warning: This action cannot be undone.

How Processing Works

1. Upload - Content is stored and API returns success
2. Extraction - Background processing extracts text (scraping, transcripts, OCR, vision)
3. Embedding - Content is converted to vector embeddings
4. Retrieval - During chat, relevant knowledge is automatically retrieved by semantic search

Errors

Next Steps

• Chat with your mind
• Create minds
• API errors and limits