openapi: 3.2.0 info: title: Minds Public Knowledge API version: v1 description: 'OpenAPI 3.1.0 spec for the Minds public API (https://getminds.ai/api/v1 / https://api.getminds.ai/v1). Generate a typed TypeScript client by running an OpenAPI generator (e.g. `openapi-typescript`) against `/_openapi.json`. Auth: send `Authorization: Bearer minds_…_key`; create keys in Settings → API Keys.' servers: - url: https://api.getminds.ai description: Production (api subdomain) - url: https://getminds.ai description: Production (apex) security: - ApiKeyAuth: [] tags: - name: Knowledge paths: /api/v1/minds/{mindId}/knowledge/{itemId}: delete: parameters: - in: path name: mindId required: true description: Mind UUID. schema: type: string format: uuid - in: path name: itemId required: true description: Knowledge item UUID (from the list or add response). schema: type: string format: uuid responses: '204': description: Item, patterns, embeddings, and stored file removed. Empty body. '400': description: 'Invalid path parameter: `Mind ID is required`, `Invalid Mind ID format`, `Knowledge item ID is required`, or `Invalid knowledge item ID format`.' '401': description: Missing or invalid API key (`Unauthorized`). '404': description: '`Mind not found or access denied` (Mind missing or caller lacks edit rights) or `Knowledge item not found` (item does not belong to this Mind).' '500': description: '`Failed to delete knowledge item` (the item record could not be removed).' operationId: deleteMindKnowledgeItem summary: Delete a knowledge item description: 'Permanently remove a knowledge item from a Mind together with its thinking patterns, its retrieval embeddings, and (for uploads) the stored file. The item record is deleted last; if a dependent cleanup step fails it is logged and the deletion still succeeds, so a 204 means the item is gone from the Mind and will no longer be retrieved in chat. This cannot be undone. The Mind system prompt is not regenerated by this call. Access: you must be able to edit the Mind (owner, direct collaborator, or member of the team the Mind is shared with); other Minds answer 404 `Mind not found or access denied`.' tags: - Knowledge security: - ApiKeyAuth: [] put: parameters: - in: path name: mindId required: true description: Mind UUID. schema: type: string format: uuid - in: path name: itemId required: true description: Knowledge item UUID (from the list or add response). schema: type: string format: uuid responses: '200': description: Updated item. This response omits `processing` and `statusUrl`; fetch the list or status endpoint for those. content: application/json: schema: type: object required: - success - data properties: success: type: boolean const: true data: $ref: '#/components/schemas/KnowledgeItem' examples: updated: summary: Renamed file item value: 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' '400': description: 'Validation error: `Mind ID is required`, `Invalid Mind ID format`, `Knowledge item ID is required`, `Invalid knowledge item ID format`, `Description must not be empty`, or `No valid fields to update. Updatable fields: description`.' '401': description: Missing or invalid API key (`Unauthorized`). '404': description: '`Mind not found or access denied` (Mind missing or caller lacks edit rights) or `Knowledge item not found` (item does not belong to this Mind).' '500': description: '`Failed to update knowledge item`.' operationId: updateMindKnowledgeItem summary: Update a knowledge item description: 'Rename the `description` of an existing knowledge item. `description` is the only updatable field: a body without a string `description` is rejected with 400 `No valid fields to update. Updatable fields: description`, and a blank/whitespace-only value is rejected with 400 `Description must not be empty`. The value is trimmed before saving. Changing the description does not re-run ingestion; use `DELETE` + `POST` to replace the underlying content. Access: you must be able to edit the Mind (owner, direct collaborator, or member of the team the Mind is shared with); other Minds answer 404 `Mind not found or access denied`.' tags: - Knowledge security: - ApiKeyAuth: [] requestBody: required: true content: application/json: schema: type: object required: - description properties: description: type: string minLength: 1 description: New description. Trimmed; must not be empty. examples: rename: summary: Rename an item value: description: Updated handbook description /api/v1/minds/{mindId}/knowledge/{itemId}/status: get: parameters: - in: path name: mindId required: true schema: type: string format: uuid - in: path name: itemId required: true schema: type: string format: uuid responses: '200': description: Processing state, embedding/pattern counts, and readyForRetrieval. '401': description: Missing or invalid API key. '403': description: Caller cannot access this Mind. '404': description: Knowledge item not found. operationId: getMindKnowledgeItemStatus summary: Get knowledge ingestion status description: Returns the durable processing state and retrieval readiness for one Mind knowledge item. tags: - Knowledge security: - ApiKeyAuth: [] /api/v1/minds/{mindId}/knowledge/enrich: post: parameters: - in: path name: mindId required: true description: Mind UUID. schema: type: string format: uuid responses: '202': description: Enrichment queued (identical to the keyword-mode response of `addMindKnowledge`). content: application/json: schema: type: object required: - success - data properties: success: type: boolean const: true data: $ref: '#/components/schemas/KnowledgeEnrichmentAccepted' '400': description: 'Validation error, in check order: `Mind ID is required`, `Invalid Mind ID format`, `keywords array is required and must not be empty` (missing/empty array or non-JSON body), then from the forwarded handler `At least one valid keyword is required` (every entry blank or non-string).' '401': description: Missing or invalid API key (`Unauthorized`). '404': description: '`Mind not found or access denied`: the Mind does not exist or the caller lacks edit rights.' '500': description: Internal server error. operationId: enrichMindKnowledge summary: Enrich a Mind from keyword web search (alias) description: 'Convenience alias for the keyword-search mode of `POST /v1/minds/{mindId}/knowledge` (`addMindKnowledge`): it validates that `keywords` is a non-empty array and then forwards the same request to that endpoint, so behaviour, limits, and the 202 response are identical. Use it when you want an endpoint that only accepts keyword enrichment; use the main endpoint if you also add links or files. Send `Content-Type: application/json` with `keywords` (and optionally `regeneratePrompt`, default `true`) and nothing else: because the request is forwarded verbatim, a body that also contains `file` is treated as a remote-file upload by the target handler. Keywords are trimmed, de-duplicated, and capped at 15 (extra keywords are silently dropped). The search runs in the background; poll `GET /v1/minds/{mindId}/training` for progress. Access: you must be able to edit the Mind (owner, direct collaborator, or member of the team the Mind is shared with); other Minds answer 404 `Mind not found or access denied`.' tags: - Knowledge security: - ApiKeyAuth: [] requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/AddKnowledgeKeywordsRequest' examples: keywords: summary: Two search topics value: keywords: - solar study efficiency - photovoltaic trends noPromptRegeneration: summary: Keep the current system prompt value: keywords: - battery storage economics regeneratePrompt: false /api/v1/minds/{mindId}/knowledge: get: parameters: - in: path name: mindId required: true description: Mind UUID. schema: type: string format: uuid responses: '200': description: Knowledge items ordered by `createdAt` descending. content: application/json: schema: type: object required: - success - data properties: success: type: boolean const: true data: type: object required: - items - total properties: items: type: array items: $ref: '#/components/schemas/KnowledgeItem' total: type: integer description: Number of items returned (no pagination, so always equals `items.length`). examples: list: summary: One file item and one link item value: 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 processing: status: completed regeneratePrompt: false statusUrl: /api/v1/minds/550e8400-e29b-41d4-a716-446655440000/knowledge/660e8400-e29b-41d4-a716-446655440001/status createdAt: '2025-12-10T12:00:00.000Z' updatedAt: '2025-12-10T12:05:00.000Z' - id: 660e8400-e29b-41d4-a716-446655440002 description: Industry trends article link: https://example.com/article filePath: null isWatched: true processing: status: queued regeneratePrompt: false statusUrl: /api/v1/minds/550e8400-e29b-41d4-a716-446655440000/knowledge/660e8400-e29b-41d4-a716-446655440002/status createdAt: '2025-12-09T12:00:00.000Z' updatedAt: '2025-12-09T12:00:00.000Z' total: 2 '400': description: 'Invalid Mind ID: `Mind ID is required` or `Invalid Mind ID format` (not a UUID).' '401': description: Missing or invalid API key (`Unauthorized`). '404': description: '`Mind not found or access denied`: the Mind does not exist or the caller is not its owner, a direct collaborator, or a member of the team it is shared with.' '500': description: Internal server error. operationId: listMindKnowledge summary: List knowledge items of a Mind description: 'Return every knowledge item (uploaded file, link, or auto-collected source) attached to a Mind, newest first. There are no query parameters and no pagination: the full list is returned in one response and `total` equals `items.length`. Each item carries its durable background `processing` state (absent for legacy items ingested before processing metadata was recorded) and a `statusUrl` you can poll for embedding/pattern counts and `readyForRetrieval`. Use it after adding knowledge to find item IDs for `PUT`/`DELETE`, or to audit what a Mind was trained on. Access: you must be able to edit the Mind (owner, direct collaborator, or member of the team the Mind is shared with); any other Mind, including public ones, answers 404 `Mind not found or access denied`.' tags: - Knowledge security: - ApiKeyAuth: [] post: parameters: - in: path name: mindId required: true description: Mind UUID. schema: type: string format: uuid responses: '202': description: Accepted for background processing. File and link modes return the created item (`KnowledgeItemAccepted`); keyword mode returns the queued enrichment job (`KnowledgeEnrichmentAccepted`). content: application/json: schema: type: object required: - success - data properties: success: type: boolean const: true data: oneOf: - $ref: '#/components/schemas/KnowledgeItemAccepted' - $ref: '#/components/schemas/KnowledgeEnrichmentAccepted' examples: file: summary: File accepted value: success: true data: id: 660e8400-e29b-41d4-a716-446655440001 filePath: portfolio/user-id/1234567890_handbook.pdf description: Company Employee Handbook 2025 createdAt: '2025-12-10T12:00:00.000Z' processing: status: queued regeneratePrompt: false statusUrl: /api/v1/minds/550e8400-e29b-41d4-a716-446655440000/knowledge/660e8400-e29b-41d4-a716-446655440001/status link: summary: Link accepted value: success: true data: id: 660e8400-e29b-41d4-a716-446655440002 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/550e8400-e29b-41d4-a716-446655440000/knowledge/660e8400-e29b-41d4-a716-446655440002/status keywords: summary: Enrichment queued value: success: true data: mindId: 550e8400-e29b-41d4-a716-446655440000 keywords: - solar study efficiency - photovoltaic trends queued: true regeneratePrompt: true message: Knowledge enrichment queued with 2 keyword(s). Web search and content processing will run in background. '400': description: 'Validation error. Path: `Mind ID is required`, `Invalid Mind ID format`. Multipart: `No form data provided`, `Description is required`, `No file provided`, `File too large: {name} ({size}MB). Maximum size is 50MB.`. Remote file: `file.name, file.url, and description are required`, `File URL is not a safe or fetchable public/workspace upload URL`, `Could not fetch file URL (HTTP {status})`, `File exceeds the 50MB knowledge upload limit`. Keywords: `Keywords array must not be empty`, `At least one valid keyword is required`. Link: `Link and description are required (or provide keywords array for web search)`, or the SDK-shape hint `Use { link, description } not { type: ''link'', url }. …` when the body carries `url` instead of `link`.' '401': description: Missing or invalid API key (`Unauthorized`). '404': description: '`Mind not found or access denied`: the Mind does not exist or the caller is not its owner, a direct collaborator, or a member of the team it is shared with.' '415': description: '`Unsupported Content-Type. Use application/json for links or multipart/form-data for files`.' '500': description: 'Storage or database failure: `Failed to upload {filename}: {reason}`, `Failed to create portfolio item`, or `Internal server error`.' operationId: addMindKnowledge summary: Add knowledge to a Mind description: 'Attach new knowledge to a Mind. Pick the input by content type and body shape: (1) `multipart/form-data` with a `file` part uploads a document or image (max 50 MB); (2) JSON `{ file: { name, url, type? }, description }` ingests a file the server fetches itself from a public URL or a Minds workspace upload URL (SSRF-protected, 20 s fetch timeout, same 50 MB limit); (3) JSON `{ link, description }` ingests a web page, YouTube video, or paper URL; (4) JSON `{ keywords: [...] }` runs a web search per keyword and adds what it finds. JSON bodies are dispatched in the order `file`, then `keywords`, then link, so send exactly one shape. Modes 1-3 create one knowledge item, return it with `processing.status: queued` and a `statusUrl`; poll that URL (or `GET .../knowledge/{itemId}/status`) until `readyForRetrieval` is true before relying on the content, especially with `sourcePolicy: knowledge_only`. Mode 4 queues a Mind-level enrichment job instead (no item is returned; keywords are trimmed, de-duplicated, and capped at 15); track it via `GET /v1/minds/{mindId}/training`. `regeneratePrompt` (rebuild the system prompt after ingestion succeeds) defaults to `false` for files and links and `true` for keywords. Access: you must be able to edit the Mind (owner, direct collaborator, or member of the team the Mind is shared with); other Minds answer 404 `Mind not found or access denied`.' tags: - Knowledge security: - ApiKeyAuth: [] requestBody: required: true content: application/json: schema: oneOf: - $ref: '#/components/schemas/AddKnowledgeLinkRequest' - $ref: '#/components/schemas/AddKnowledgeRemoteFileRequest' - $ref: '#/components/schemas/AddKnowledgeKeywordsRequest' examples: link: summary: Add a URL value: link: https://example.com/article description: Industry trends article remoteFile: summary: Ingest a file from a signed URL value: file: name: handbook.pdf url: https://files.example.com/signed/handbook.pdf type: application/pdf description: Company Employee Handbook 2025 regeneratePrompt: false keywords: summary: Enrich via keyword web search value: keywords: - solar study efficiency - photovoltaic trends regeneratePrompt: true multipart/form-data: schema: type: object required: - file - description properties: file: type: string format: binary description: Document (PDF, DOCX, DOC, TXT, MD, RTF, CSV, JSON, XML) or image (JPG, JPEG, PNG, GIF, WEBP). Max 50 MB. The part must carry a filename. description: type: string description: Description of the content. Required; whitespace-only is rejected. regeneratePrompt: type: string enum: - 'true' - 'false' default: 'false' description: Send the literal string `true` to regenerate the Mind system prompt after ingestion succeeds; any other value means false. encoding: file: contentType: application/pdf, application/vnd.openxmlformats-officedocument.wordprocessingml.document, application/msword, text/plain, text/markdown, text/rtf, text/csv, application/json, application/xml, image/jpeg, image/png, image/gif, image/webp /api/v1/minds/{mindId}/knowledge/patterns: get: parameters: - in: path name: mindId required: true description: Mind UUID. schema: type: string format: uuid responses: '200': description: Patterns grouped by framework. `frameworks` is empty when no patterns have been extracted yet. content: application/json: schema: type: object required: - success - data properties: success: type: boolean const: true data: type: object required: - mindId - mindName - totalPatterns - frameworks properties: mindId: type: string format: uuid mindName: type: string totalPatterns: type: integer description: Total stored patterns for the Mind, including any whose aspect matches no framework. frameworks: type: array items: $ref: '#/components/schemas/KnowledgePatternFramework' examples: privileged: summary: Owner view with provenance value: success: true data: mindId: 550e8400-e29b-41d4-a716-446655440000 mindName: Marketing Expert totalPatterns: 3 frameworks: - id: ocean name: Big Five (OCEAN) totalOccurrences: 3 aspects: - id: ocean-O name: Openness to Experience description: Imagination, curiosity, and openness to new ideas. occurrences: 3 subAspects: - id: ocean-O-1 name: Fantasy description: Rich imaginative life. occurrences: 2 evidence: - mind: Prefers bold campaign concepts over incremental tweaks. portfolioItemId: 660e8400-e29b-41d4-a716-446655440001 createdAt: '2025-12-10T12:05:00.000Z' - id: (none) name: (General) description: '' occurrences: 1 evidence: - mind: Explores adjacent markets before committing budget. portfolioItemId: null createdAt: '2025-12-10T12:05:00.000Z' '400': description: 'Invalid Mind ID: `Mind ID is required` or `Invalid Mind ID format` (not a UUID).' '401': description: Missing or invalid API key (`Unauthorized`). '403': description: '`Access denied to this Mind`: the Mind is not public and the caller is not its owner, a direct collaborator, a member of the team it is shared with, or a member of a private Audience containing it.' '404': description: '`Mind not found`.' '500': description: Internal server error. operationId: getMindKnowledgePatterns summary: Get thinking patterns grouped by framework description: 'Return the thinking patterns extracted from a Mind''s knowledge, grouped by psychological/behavioural framework (for example Big Five, DISC, Holland Codes), then by aspect and sub-aspect, each with occurrence counts and the supporting evidence quotes. Frameworks, aspects, and sub-aspects with zero occurrences are omitted, and every level is sorted by occurrences descending. Use it to explain *why* a Mind answers the way it does, to audit training coverage, or to build profile visualisations. Access: the Mind''s owner, direct collaborators, members of the team it is shared with, and members of a private Audience containing it (Audience owner, Audience member, or member of the team the Audience is shared with) see full evidence including `portfolioItemId` and `createdAt`; anyone else may read only public Minds and receives evidence quotes without those provenance fields. Any other Mind answers 403 `Access denied to this Mind`.' tags: - Knowledge security: - ApiKeyAuth: [] components: schemas: AddKnowledgeRemoteFileRequest: type: object title: Remote or workspace file required: - file - description properties: file: type: object required: - name - url properties: name: type: string description: Filename including extension; used to derive the storage name and content type. url: type: string format: uri description: Public/signed HTTPS URL, or a Minds workspace upload URL (read directly from storage). Private-network and unsafe URLs are rejected. type: type: string description: MIME type hint. Falls back to the fetched response `Content-Type`. description: type: string description: Description of the content. regeneratePrompt: type: boolean default: false description: Regenerate the Mind system prompt once ingestion succeeds. KnowledgePatternAspect: type: object required: - id - name - description - occurrences - subAspects properties: id: type: string description: Framework aspect ID (e.g. `ocean-O`). name: type: string description: type: string occurrences: type: integer description: Number of patterns matched to this aspect (sum of its sub-aspects). subAspects: type: array description: Sub-aspects with at least one occurrence, sorted by occurrences descending. items: $ref: '#/components/schemas/KnowledgePatternSubAspect' KnowledgeItem: type: object description: A knowledge source attached to a Mind. Exactly one of `link` or `filePath` is set for user-added items; auto-collected sources can also be link-based. required: - id - description - link - filePath - isWatched - createdAt - updatedAt properties: id: type: string format: uuid description: type: string description: Human-readable description supplied when the item was added. link: type: - string - 'null' format: uri description: Source URL for link-based items; null for uploaded files. filePath: type: - string - 'null' description: Storage path of the uploaded file (`portfolio/{userId}/{timestamp}_{name}`); null for link-based items. isWatched: type: boolean description: True when a link item is watched for weekly content changes (managed in the product UI; links only). processing: $ref: '#/components/schemas/KnowledgeItemProcessing' description: Absent for legacy items without recorded processing metadata. statusUrl: type: string description: Relative path of `GET /api/v1/minds/{mindId}/knowledge/{itemId}/status` for this item. createdAt: type: string format: date-time updatedAt: type: string format: date-time KnowledgePatternSubAspect: type: object required: - id - name - description - occurrences - evidence properties: id: type: string description: Framework sub-aspect ID, or `(none)` for patterns filed directly under the aspect. name: type: string description: Sub-aspect name, or `(General)` for patterns without a sub-aspect. description: type: string description: Framework definition; empty string when unknown. occurrences: type: integer description: Number of patterns matched to this sub-aspect. evidence: type: array items: $ref: '#/components/schemas/KnowledgePatternEvidence' AddKnowledgeKeywordsRequest: type: object title: Keyword web search required: - keywords properties: keywords: type: array minItems: 1 maxItems: 15 items: type: string description: Search topics. Trimmed, de-duplicated, and capped at 15 (extras are silently dropped). Must contain at least one non-empty string. regeneratePrompt: type: boolean default: true description: Regenerate the Mind system prompt after the collected content is processed. KnowledgeItemAccepted: type: object title: Knowledge item accepted description: Created item for file and link modes. `filePath` is present for uploads, `link` for URLs; `isWatched`/`updatedAt` are not included here (see the list endpoint). required: - id - description - createdAt - processing - statusUrl properties: id: type: string format: uuid description: type: string link: type: string format: uri description: Present for link mode only. filePath: type: string description: 'Present for file modes only: `portfolio/{userId}/{timestamp}_{sanitizedName}`.' createdAt: type: string format: date-time processing: $ref: '#/components/schemas/KnowledgeItemProcessing' description: 'Always `{ status: "queued", regeneratePrompt }` at creation.' statusUrl: type: string description: Relative path of `GET /api/v1/minds/{mindId}/knowledge/{itemId}/status`; poll until `readyForRetrieval` is true. KnowledgeItemProcessing: type: object description: Durable background-processing state recorded on the item. `status` is the ingestion lifecycle; poll the item `statusUrl` for embedding/pattern counts and the `readyForRetrieval` gate. Workers may add further keys (for example `error` or `promptRegenerated`). required: - status properties: status: type: string enum: - queued - running - completed - failed description: Ingestion lifecycle state. regeneratePrompt: type: boolean description: Whether the Mind system prompt is regenerated once embeddings and patterns finish successfully. error: type: string description: Failure detail when `status` is `failed`, if the worker recorded one. promptRegenerated: type: boolean description: Whether the optional prompt-regeneration step completed. Present only when recorded. additionalProperties: true KnowledgePatternEvidence: type: object required: - mind properties: mind: type: string description: The extracted pattern text (citation/quote) supporting this sub-aspect. portfolioItemId: type: - string - 'null' format: uuid description: Knowledge item the pattern was extracted from. Present only for privileged callers; null for patterns without a source item. createdAt: type: string format: date-time description: When the pattern was extracted. Present only for privileged callers. AddKnowledgeLinkRequest: type: object title: Link required: - link - description properties: link: type: string format: uri description: URL of a web page, YouTube video, or research paper. Note the field is `link`, not `url`. description: type: string description: Description of the content. regeneratePrompt: type: boolean default: false description: Regenerate the Mind system prompt once ingestion succeeds. KnowledgePatternFramework: type: object required: - id - name - totalOccurrences - aspects properties: id: type: string description: Framework ID (e.g. `ocean`, `disc`, `riasec`). name: type: string description: Framework display name (e.g. `Big Five (OCEAN)`). totalOccurrences: type: integer description: Sum of aspect occurrences within this framework. aspects: type: array description: Aspects with at least one occurrence, sorted by occurrences descending. items: $ref: '#/components/schemas/KnowledgePatternAspect' KnowledgeEnrichmentAccepted: type: object title: Keyword enrichment accepted required: - mindId - keywords - queued - regeneratePrompt - message properties: mindId: type: string format: uuid keywords: type: array items: type: string description: Normalised keywords actually queued (trimmed, de-duplicated, max 15). queued: type: boolean const: true regeneratePrompt: type: boolean message: type: string example: Knowledge enrichment queued with 2 keyword(s). Web search and content processing will run in background. securitySchemes: ApiKeyAuth: type: http scheme: bearer bearerFormat: API Key description: 'Personal API key. Format: `Bearer minds_…_key`. Create one at https://getminds.ai/settings/api-keys.'