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.

List Knowledge Items

Retrieve all knowledge items for a mind.

Endpoint: GET /api/v1/sparks/{sparkId}/knowledge

Headers:

Authorization: Bearer minds_your_api_key

Example:

curl -X GET "https://getminds.ai/api/v1/sparks/{sparkId}/knowledge" \
  -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
  }
}

File Upload

Upload documents or images directly to a mind.

Endpoint: POST /api/v1/sparks/{sparkId}/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/sparks/{sparkId}/knowledge" \
  -H "Authorization: Bearer minds_your_api_key" \
  -F "file=@./handbook.pdf" \
  -F "description=Company Employee Handbook 2025"

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/sparks/{sparkId}/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/sparks/{sparkId}/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/sparks/{sparkId}/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/sparks/{sparkId}/knowledge

Content-Type: application/json

Example:

curl -X POST "https://getminds.ai/api/v1/sparks/{sparkId}/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/sparks/{sparkId}/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/sparks/{sparkId}/knowledge/{itemId}/status

{
  "data": {
    "itemId": "660e8400-e29b-41d4-a716-446655440001",
    "sparkId": "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 for legacy items without recorded processing metadata. 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 contains processing failure detail when status is failed, if the worker recorded one.
• data.promptRegenerated reports whether the optional prompt-regeneration step completed. It is present only when recorded by processing.

The endpoint returns 401 for a missing or invalid API key, 403 when the caller cannot access the Mind, and 404 when the knowledge item does not belong to that Mind.

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/sparks/{sparkId}/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/sparks/{sparkId}/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/sparks/{sparkId}/knowledge/enrich

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

Example:

curl -X POST "https://getminds.ai/api/v1/sparks/{sparkId}/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/sparks/{sparkId}/knowledge/{itemId}

Headers:

Authorization: Bearer minds_your_api_key

Example:

curl -X DELETE "https://getminds.ai/api/v1/sparks/{sparkId}/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