{"openapi":"3.1.0","components":{"securitySchemes":{"bearerAuth":{"scheme":"bearer","type":"http"}},"schemas":{"ErrorResponse":{"type":"object","properties":{"error":{"type":"string","description":"Error message","example":"Invalid request parameters"},"details":{"type":"string","description":"Additional error details","example":"Query must be at least 1 character long"}},"required":["error"]},"FilterPredicate":{"anyOf":[{"type":"object","properties":{"field":{"type":"string","minLength":1,"pattern":"^[a-zA-Z0-9_.-]+$","description":"Metadata key to evaluate, matched literally. A period is part of the key name, not a path into nested metadata."},"operator":{"type":"string","enum":["eq","neq"],"description":"Compare the field for equality or inequality"},"value":{"type":"string","description":"String value to compare against"},"caseSensitive":{"default":true,"description":"Whether string comparison preserves letter case","type":"boolean"}},"required":["field","operator","value"],"additionalProperties":false},{"type":"object","properties":{"field":{"type":"string","minLength":1,"pattern":"^[a-zA-Z0-9_.-]+$","description":"Metadata key to evaluate, matched literally. A period is part of the key name, not a path into nested metadata."},"operator":{"type":"string","enum":["eq","neq"],"description":"Compare the field for equality or inequality"},"value":{"anyOf":[{"type":"number"},{"type":"boolean"}],"description":"Numeric or boolean value to compare against"}},"required":["field","operator","value"],"additionalProperties":false},{"type":"object","properties":{"field":{"type":"string","minLength":1,"pattern":"^[a-zA-Z0-9_.-]+$","description":"Metadata key to evaluate, matched literally. A period is part of the key name, not a path into nested metadata."},"operator":{"type":"string","enum":["gt","gte","lt","lte"],"description":"Numeric comparison to apply"},"value":{"type":"number","description":"Numeric value to compare against"}},"required":["field","operator","value"],"additionalProperties":false},{"type":"object","properties":{"field":{"type":"string","minLength":1,"pattern":"^[a-zA-Z0-9_.-]+$","description":"Metadata key to evaluate, matched literally. A period is part of the key name, not a path into nested metadata."},"operator":{"type":"string","enum":["contains","notContains"],"description":"Require or exclude a substring match"},"value":{"type":"string","description":"Substring to look for"},"caseSensitive":{"default":true,"description":"Whether substring matching preserves letter case","type":"boolean"}},"required":["field","operator","value"],"additionalProperties":false},{"type":"object","properties":{"field":{"type":"string","minLength":1,"pattern":"^[a-zA-Z0-9_.-]+$","description":"Metadata key to evaluate, matched literally. A period is part of the key name, not a path into nested metadata."},"operator":{"type":"string","enum":["arrayContains","arrayNotContains"],"description":"Require or exclude an exact array member"},"value":{"type":"string","description":"Array member to look for"}},"required":["field","operator","value"],"additionalProperties":false}]},"FilterExpression":{"description":"A type-safe metadata filter predicate or nested and/or expression. The API validates up to 5 levels of nesting.","anyOf":[{"$ref":"#/components/schemas/FilterPredicate"},{"type":"object","properties":{"operator":{"type":"string","const":"and","description":"Require every nested filter expression to match"},"operands":{"type":"array","minItems":1,"maxItems":200,"items":{"$ref":"#/components/schemas/FilterExpression"},"description":"Filter expressions combined with logical AND"}},"required":["operator","operands"],"additionalProperties":false},{"type":"object","properties":{"operator":{"type":"string","const":"or","description":"Require at least one nested filter expression to match"},"operands":{"type":"array","minItems":1,"maxItems":200,"items":{"$ref":"#/components/schemas/FilterExpression"},"description":"Filter expressions combined with logical OR"}},"required":["operator","operands"],"additionalProperties":false}]},"ValidationErrorResponse":{"type":"object","description":"Body returned when request input fails schema validation","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"array","description":"Validation issues","items":{"type":"object","properties":{"message":{"type":"string"},"path":{"type":"array","items":{"oneOf":[{"type":"string"},{"type":"number"}]}}},"required":["message"]}},"data":{"description":"The input that failed validation"}},"required":["success","error"]}}},"info":{"title":"supermemory API","description":"The Memory API for the AI era. OpenAPI operations include x-codeSamples for the official TypeScript and Python SDKs (Mintlify-compatible).","version":"5.0.0"},"security":[{"bearerAuth":[]}],"servers":[{"description":"Production Server","url":"https://api.supermemory.ai"}],"tags":[{"name":"Ingest","description":"Ingest documents, files, URLs, conversations, and other content"},{"name":"Recall (Search)","description":"Semantic recall across your content — supports memories, hybrid, and documents modes"},{"name":"Profiles","description":"Maintained static, dynamic, and custom-bucket profiles scoped by namespace"},{"name":"Content Management","description":"List, get, update, and delete content and memories"},{"name":"Namespaces","description":"List and manage isolated namespaces and their settings"},{"name":"Organization","description":"Read and update organization-wide settings"}],"paths":{"/ns/{namespace}/document":{"post":{"operationId":"postNsByNamespaceDocument","description":"Turn text or a supported URL into searchable, evolving memory. Supply a new ID to create a document, or reuse an existing ID to append new information while preserving its history.","responses":{"200":{"content":{"application/json":{"schema":{"type":"object","required":["id","status"],"properties":{"id":{"type":"string","description":"Unique identifier of the document"},"status":{"type":"string","description":"Status of the document"}},"additionalProperties":false}}},"description":"Document accepted for processing"},"400":{"description":"Invalid request parameters","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/ErrorResponse"},{"$ref":"#/components/schemas/ValidationErrorResponse"}]}}}},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Unauthorized"},"402":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Insufficient processing credits"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Namespace write access denied"},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Namespace merge or filepath conflict"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Server error"}},"summary":"Add document","tags":["Ingest"],"parameters":[{"in":"path","name":"namespace","schema":{"type":"string","maxLength":100,"pattern":"^[a-zA-Z0-9_:-]+$","example":"user_alex"},"required":true,"description":"The isolated namespace. This can be an ID for your user, a project ID, or any other identifier you wish to use to scope documents."},{"in":"query","name":"taskType","schema":{"type":"string","enum":["memory","superrag"]},"description":"Processing pipeline. \"memory\" builds durable learned context; \"superrag\" optimizes the document for retrieval without generating memories."},{"in":"query","name":"dreaming","schema":{"type":"string","enum":["dynamic","instant"]},"description":"Processing mode. \"dynamic\" (default) groups related documents so memories form from coherent context. \"instant\" processes each document independently right away and bills one extra operation per document."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"content":{"type":"string","description":"The content to process. This may be plaintext or a URL to supported rich content.","example":"Supermemory turns unstructured content into evolving memory."},"id":{"description":"An optional caller-defined document ID","type":"string","minLength":1,"maxLength":255,"example":"my-doc-123"},"supportingContext":{"description":"Context used to guide memory extraction within this namespace. Max 1500 characters.","example":"Focus on product decisions, dates, and owners.","type":"string","maxLength":1500},"metadata":{"description":"Arbitrary metadata attached to the document and derived data","example":{"source":"api-docs"},"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"anyOf":[{"type":"string"},{"type":"number"},{"type":"boolean"},{"type":"array","items":{"type":"string"}}]}},"group":{"description":"Metadata values that isolate related context within the namespace","type":"object","propertyNames":{"type":"string"},"additionalProperties":{"anyOf":[{"type":"string"},{"type":"number"},{"type":"boolean"},{"type":"array","items":{"type":"string"}}]}},"date":{"description":"When the source content is from, in ISO 8601 format","example":"2026-01-15","type":"string"}},"required":["content"],"additionalProperties":false}}}},"x-codeSamples":[{"lang":"bash","label":"cURL","source":"curl -X POST \"https://api.supermemory.ai/ns/user_123/document?dreaming=instant\" \\\n  -H \"Authorization: Bearer $SUPERMEMORY_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"content\": \"Sarah is being promoted to VP of Product.\",\n    \"id\": \"chat_session_1\",\n    \"metadata\": { \"type\": \"conversation\" }\n  }'"}]},"delete":{"operationId":"deleteNsByNamespaceDocument","description":"Permanently remove documents and their derived knowledge by document ID or caller-defined ID. Each requested ID is handled independently so successful deletions are preserved when another ID fails.","responses":{"200":{"content":{"application/json":{"schema":{"type":"object","properties":{"deletedCount":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"Number of documents successfully deleted"},"errors":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":1,"maxLength":255,"example":"my-doc-123","description":"The requested document identifier"},"error":{"type":"string","minLength":1,"description":"Why this document could not be deleted"}},"required":["id","error"],"additionalProperties":false},"description":"Per-document failures; successful deletions are not rolled back"}},"required":["deletedCount","errors"],"additionalProperties":false}}},"description":"Document deletion completed"},"400":{"description":"Invalid delete request","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/ErrorResponse"},{"$ref":"#/components/schemas/ValidationErrorResponse"}]}}}},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Unauthorized"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Write access required for this namespace"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Internal server error"}},"summary":"Delete documents","tags":["Content Management"],"parameters":[{"in":"path","name":"namespace","schema":{"type":"string","maxLength":100,"pattern":"^[a-zA-Z0-9_:-]+$","example":"user_alex"},"required":true,"description":"The isolated namespace. This can be an ID for your user, a project ID, or any other identifier you wish to use to scope documents."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"ids":{"minItems":1,"maxItems":100,"type":"array","items":{"type":"string","minLength":1,"maxLength":255,"example":"my-doc-123","description":"A document ID or caller-defined ID"},"description":"Document identifiers to permanently delete from this namespace","example":["my-doc-123"]}},"required":["ids"],"additionalProperties":false}}}}}},"/ns/{namespace}/document/batch":{"post":{"operationId":"postNsByNamespaceDocumentBatch","description":"Build a knowledge base efficiently by ingesting up to 600 text or URL documents at once. Existing caller-defined IDs append new information using the same semantics as single-document ingestion.","responses":{"200":{"content":{"application/json":{"schema":{"type":"object","required":["results","failed","success"],"properties":{"results":{"type":"array","items":{"type":"object","required":["id","status"],"properties":{"id":{"type":"string","description":"Unique identifier of the document (empty string for failed items)"},"status":{"type":"string","description":"Status of the document (e.g. 'done', 'queued', 'error')"},"error":{"type":"string","description":"Error message when status is 'error'"},"details":{"type":"string","description":"Additional error details when status is 'error'"},"url":{"type":"string","description":"URL of the failed item, when it had one. Only present on failed items, where it may be the only way to tell which input the error belongs to (the id falls back to 'unknown' when the input had neither an id nor a customId)."}},"additionalProperties":false},"description":"Array of results for each document in the batch"},"failed":{"type":"number","description":"Count of documents that failed to add"},"success":{"type":"number","description":"Count of documents successfully added"}},"additionalProperties":false}}},"description":"Batch accepted for processing"},"400":{"description":"Invalid request parameters","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/ErrorResponse"},{"$ref":"#/components/schemas/ValidationErrorResponse"}]}}}},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Unauthorized"},"402":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Insufficient processing credits"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Namespace write access denied"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Server error"}},"summary":"Batch add documents","tags":["Ingest"],"parameters":[{"in":"path","name":"namespace","schema":{"type":"string","maxLength":100,"pattern":"^[a-zA-Z0-9_:-]+$","example":"user_alex"},"required":true,"description":"The isolated namespace. This can be an ID for your user, a project ID, or any other identifier you wish to use to scope documents."},{"in":"query","name":"taskType","schema":{"type":"string","enum":["memory","superrag"]},"description":"Processing pipeline. \"memory\" builds durable learned context; \"superrag\" optimizes the document for retrieval without generating memories."},{"in":"query","name":"dreaming","schema":{"type":"string","enum":["dynamic","instant"]},"description":"Processing mode. \"dynamic\" (default) groups related documents so memories form from coherent context. \"instant\" processes each document independently right away and bills one extra operation per document."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"documents":{"minItems":1,"maxItems":600,"type":"array","items":{"type":"object","properties":{"content":{"type":"string","description":"The content to process. This may be plaintext or a URL to supported rich content.","example":"Supermemory turns unstructured content into evolving memory."},"id":{"description":"An optional caller-defined document ID","type":"string","minLength":1,"maxLength":255,"example":"my-doc-123"},"supportingContext":{"description":"Context used to guide memory extraction within this namespace. Max 1500 characters.","example":"Focus on product decisions, dates, and owners.","type":"string","maxLength":1500},"metadata":{"description":"Arbitrary metadata attached to the document and derived data","example":{"source":"api-docs"},"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"anyOf":[{"type":"string"},{"type":"number"},{"type":"boolean"},{"type":"array","items":{"type":"string"}}]}},"group":{"description":"Metadata values that isolate related context within the namespace","type":"object","propertyNames":{"type":"string"},"additionalProperties":{"anyOf":[{"type":"string"},{"type":"number"},{"type":"boolean"},{"type":"array","items":{"type":"string"}}]}},"date":{"description":"When the source content is from, in ISO 8601 format","example":"2026-01-15","type":"string"}},"required":["content"],"additionalProperties":false},"description":"Documents to ingest or append in one request"}},"required":["documents"],"additionalProperties":false}}}},"x-codeSamples":[{"lang":"bash","label":"cURL","source":"curl -X POST \"https://api.supermemory.ai/ns/user_123/document/batch?dreaming=instant\" \\\n  -H \"Authorization: Bearer $SUPERMEMORY_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"documents\": [\n      { \"content\": \"Q3 roadmap notes\", \"id\": \"doc_roadmap\" },\n      { \"content\": \"Gift policy for VP promotions\", \"id\": \"doc_gifts\" }\n    ]\n  }'"}]}},"/ns/{namespace}/document/{id}":{"get":{"operationId":"getNsByNamespaceDocumentById","description":"Retrieve a document's canonical content, metadata, and processing state by document ID or caller-defined ID. Optionally attach its source chunks, derived memories, or both in the same response.","responses":{"200":{"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","description":"Stable document identifier","example":"doc_xyz789"},"title":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Extracted or caller-provided document title","example":"API Rate Limiting Policy"},"type":{"type":"string","description":"Detected source or content type","example":"text"},"summary":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Generated summary of the document, when available"},"content":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Canonical extracted text used for processing and recall","example":"Our API rate limits are 100 req/min on free and 1000 on pro."},"metadata":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{},"description":"Caller metadata with internal fields removed","example":{"source":"api-docs"}},"system":{"type":"object","properties":{"status":{"type":"string","description":"Current extraction and memory-processing status"},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$","description":"ISO 8601 timestamp when the document was created"},"updatedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$","description":"ISO 8601 timestamp of the latest document update"}},"required":["status","createdAt","updatedAt"],"description":"Processing status, lifecycle timestamps, and storage path maintained by Supermemory"},"chunks":{"description":"Ordered document chunks; included only when requested","type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Stable chunk identifier"},"position":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Zero-based order within the document"},"content":{"type":"string","description":"Chunk text used for retrieval"},"type":{"type":"string","description":"Chunk content type"},"metadata":{"anyOf":[{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},{"type":"null"}],"description":"Chunk metadata, when available"},"system":{"type":"object","properties":{"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$","description":"ISO 8601 timestamp when the chunk was created"}},"required":["createdAt"],"description":"Lifecycle timestamps maintained by Supermemory"}},"required":["id","position","content","type","metadata","system"],"description":"A chunk of source content belonging to a document"}},"memories":{"description":"Memories derived from the document; included only when requested","type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Stable memory identifier"},"memory":{"type":"string","description":"Learned fact or context extracted from the document"},"metadata":{"anyOf":[{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},{"type":"null"}],"description":"Memory metadata, including temporal context when available"},"isStatic":{"type":"boolean","description":"Whether the memory belongs to the stable profile section"},"isInference":{"type":"boolean","description":"Whether the memory was inferred rather than explicitly stated"},"isLatest":{"type":"boolean","description":"Whether this is the newest version in its memory chain"},"isForgotten":{"type":"boolean","description":"Whether this memory has been excluded from normal recall"},"version":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Version number within the memory chain"},"system":{"type":"object","properties":{"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$","description":"ISO 8601 timestamp when this memory version was created"},"updatedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$","description":"ISO 8601 timestamp of the latest update to this version"}},"required":["createdAt","updatedAt"],"description":"Lifecycle timestamps maintained by Supermemory"}},"required":["id","memory","metadata","isStatic","isInference","isLatest","isForgotten","version","system"],"description":"A memory formed from documents in this namespace"}}},"required":["id","title","type","summary","content","metadata","system"],"description":"Namespace-scoped document. Attachment keys are omitted unless requested and are empty arrays when requested without results."}}},"description":"Document retrieved successfully"},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/ErrorResponse"},{"$ref":"#/components/schemas/ValidationErrorResponse"}]}}}},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Unauthorized"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Namespace access denied"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Document not found"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Internal server error"}},"summary":"Get document","tags":["Content Management"],"parameters":[{"in":"path","name":"namespace","schema":{"type":"string","maxLength":100,"pattern":"^[a-zA-Z0-9_:-]+$","example":"user_alex"},"required":true,"description":"The isolated namespace. This can be an ID for your user, a project ID, or any other identifier you wish to use to scope documents."},{"in":"path","name":"id","schema":{"type":"string","minLength":1,"maxLength":255,"example":"my-doc-123"},"required":true,"description":"The public document ID"},{"in":"query","name":"attach","schema":{"type":"array","items":{"type":"string","enum":["chunks","memories"]}},"description":"Child resources to include. Repeat the parameter to attach chunks, memories, or both."}],"x-codeSamples":[{"lang":"bash","label":"cURL","source":"curl \"https://api.supermemory.ai/ns/project_123/document/doc_abc123?attach=chunks&attach=memories\" \\\n  -H \"Authorization: Bearer $SUPERMEMORY_API_KEY\""}]},"patch":{"operationId":"patchNsByNamespaceDocumentById","description":"Refresh an existing document without changing its stable ID. Supplied content replaces the canonical content and is reprocessed; omitted fields remain unchanged.","responses":{"200":{"content":{"application/json":{"schema":{"type":"object","required":["id","status"],"properties":{"id":{"type":"string","description":"Unique identifier of the document"},"status":{"type":"string","description":"Status of the document"}},"additionalProperties":false}}},"description":"Document updated successfully"},"400":{"description":"Invalid request parameters","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/ErrorResponse"},{"$ref":"#/components/schemas/ValidationErrorResponse"}]}}}},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Unauthorized"},"402":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Insufficient processing credits"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Namespace write access denied"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Document not found in this namespace"},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Namespace merge or filepath conflict"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Server error"}},"summary":"Update document","tags":["Ingest"],"parameters":[{"in":"path","name":"namespace","schema":{"type":"string","maxLength":100,"pattern":"^[a-zA-Z0-9_:-]+$","example":"user_alex"},"required":true,"description":"The isolated namespace. This can be an ID for your user, a project ID, or any other identifier you wish to use to scope documents."},{"in":"path","name":"id","schema":{"type":"string","minLength":1,"maxLength":255,"example":"my-doc-123"},"required":true,"description":"The public document ID"},{"in":"query","name":"taskType","schema":{"type":"string","enum":["memory","superrag"]},"description":"Processing pipeline. \"memory\" builds durable learned context; \"superrag\" optimizes the document for retrieval without generating memories."},{"in":"query","name":"dreaming","schema":{"type":"string","enum":["dynamic","instant"]},"description":"Processing mode. \"dynamic\" (default) groups related documents so memories form from coherent context. \"instant\" processes each document independently right away and bills one extra operation per document."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"content":{"type":"string","description":"The content to process. This may be plaintext or a URL to supported rich content.","example":"Supermemory turns unstructured content into evolving memory."},"supportingContext":{"description":"Context used to guide memory extraction within this namespace. Max 1500 characters.","example":"Focus on product decisions, dates, and owners.","type":"string","maxLength":1500},"metadata":{"description":"Arbitrary metadata attached to the document and derived data","example":{"source":"api-docs"},"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"anyOf":[{"type":"string"},{"type":"number"},{"type":"boolean"},{"type":"array","items":{"type":"string"}}]}},"group":{"description":"Metadata values that isolate related context within the namespace","type":"object","propertyNames":{"type":"string"},"additionalProperties":{"anyOf":[{"type":"string"},{"type":"number"},{"type":"boolean"},{"type":"array","items":{"type":"string"}}]}},"date":{"description":"When the source content is from, in ISO 8601 format","example":"2026-01-15","type":"string"}},"additionalProperties":false}}}},"x-codeSamples":[{"lang":"bash","label":"cURL","source":"curl -X PATCH \"https://api.supermemory.ai/ns/user_123/document/chat_session_1\" \\\n  -H \"Authorization: Bearer $SUPERMEMORY_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"content\": \"Updated notes — Sarah is now VP of Product.\",\n    \"metadata\": { \"type\": \"conversation\" }\n  }'"}]}},"/ns/{namespace}/document/file":{"post":{"operationId":"postNsByNamespaceDocumentFile","description":"Transform an uploaded file into searchable knowledge and learned memory. The response returns as soon as ingestion is safely queued while extraction and memory formation continue asynchronously.","responses":{"200":{"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"Document identifier to poll or retrieve"},"status":{"type":"string","const":"processing","description":"Confirms the file was accepted for asynchronous processing"}},"required":["id","status"],"additionalProperties":false}}},"description":"File accepted for processing"},"400":{"description":"Invalid file request","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/ErrorResponse"},{"$ref":"#/components/schemas/ValidationErrorResponse"}]}}}},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Unauthorized"},"402":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Insufficient balance or document quota"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Write access required for this namespace"},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Filepath conflict or namespace merge prevents the update"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Internal server error"}},"summary":"Upload file","tags":["Ingest"],"parameters":[{"in":"path","name":"namespace","schema":{"type":"string","maxLength":100,"pattern":"^[a-zA-Z0-9_:-]+$","example":"user_alex"},"required":true,"description":"The isolated namespace. This can be an ID for your user, a project ID, or any other identifier you wish to use to scope documents."},{"in":"query","name":"taskType","schema":{"type":"string","enum":["memory","superrag"]},"description":"Processing pipeline. \"memory\" builds durable learned context; \"superrag\" optimizes the document for retrieval without generating memories."},{"in":"query","name":"dreaming","schema":{"type":"string","enum":["dynamic","instant"]},"description":"Processing mode. \"dynamic\" (default) groups related documents so memories form from coherent context. \"instant\" processes each document independently right away and bills one extra operation per document."},{"in":"query","name":"fileType","schema":{"type":"string","enum":["text","pdf","image","video","audio"]},"description":"Explicit source type used when automatic inference is insufficient"},{"in":"query","name":"mimeType","schema":{"type":"string","pattern":"^[^\\s/]+\\/[^\\s/]+$"},"description":"Explicit MIME type used when upload metadata is insufficient"}],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"file":{"description":"File contents to upload","format":"binary","type":"string"},"supportingContext":{"description":"Context used to guide memory extraction within this namespace. Max 1500 characters.","example":"Focus on product decisions, dates, and owners.","type":"string","maxLength":1500},"metadata":{"description":"JSON-encoded metadata to attach to the document and its derived memories","type":"string"},"group":{"description":"JSON-encoded metadata used to keep related context isolated during processing and recall","type":"string"},"date":{"description":"When the source content is from, in ISO 8601 format","example":"2026-01-15","type":"string"}},"required":["file"],"additionalProperties":false}}}}}},"/ns/{namespace}/document/file/{id}":{"post":{"operationId":"postNsByNamespaceDocumentFileById","description":"Replace an existing document with a new file while keeping its stable document ID. Content and caller metadata are overwritten, then the document is reprocessed asynchronously.","responses":{"200":{"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"Document identifier to poll or retrieve"},"status":{"type":"string","const":"processing","description":"Confirms the file was accepted for asynchronous processing"}},"required":["id","status"],"additionalProperties":false}}},"description":"Replacement accepted for processing"},"400":{"description":"Invalid file request","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/ErrorResponse"},{"$ref":"#/components/schemas/ValidationErrorResponse"}]}}}},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Unauthorized"},"402":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Insufficient balance or document quota"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Write access required for this namespace"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Document not found in this namespace"},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Filepath conflict or namespace merge prevents the update"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Internal server error"}},"summary":"Replace document with file","tags":["Ingest"],"parameters":[{"in":"path","name":"namespace","schema":{"type":"string","maxLength":100,"pattern":"^[a-zA-Z0-9_:-]+$","example":"user_alex"},"required":true,"description":"The isolated namespace. This can be an ID for your user, a project ID, or any other identifier you wish to use to scope documents."},{"in":"path","name":"id","schema":{"type":"string","minLength":1,"maxLength":255,"example":"my-doc-123"},"required":true,"description":"The public document ID"},{"in":"query","name":"taskType","schema":{"type":"string","enum":["memory","superrag"]},"description":"Processing pipeline. \"memory\" builds durable learned context; \"superrag\" optimizes the document for retrieval without generating memories."},{"in":"query","name":"dreaming","schema":{"type":"string","enum":["dynamic","instant"]},"description":"Processing mode. \"dynamic\" (default) groups related documents so memories form from coherent context. \"instant\" processes each document independently right away and bills one extra operation per document."},{"in":"query","name":"fileType","schema":{"type":"string","enum":["text","pdf","image","video","audio"]},"description":"Explicit source type used when automatic inference is insufficient"},{"in":"query","name":"mimeType","schema":{"type":"string","pattern":"^[^\\s/]+\\/[^\\s/]+$"},"description":"Explicit MIME type used when upload metadata is insufficient"}],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"file":{"description":"File contents to upload","format":"binary","type":"string"},"supportingContext":{"description":"Context used to guide memory extraction within this namespace. Max 1500 characters.","example":"Focus on product decisions, dates, and owners.","type":"string","maxLength":1500},"metadata":{"description":"JSON-encoded metadata to attach to the document and its derived memories","type":"string"},"group":{"description":"JSON-encoded metadata used to keep related context isolated during processing and recall","type":"string"},"date":{"description":"When the source content is from, in ISO 8601 format","example":"2026-01-15","type":"string"}},"required":["file"],"additionalProperties":false}}}}},"patch":{"operationId":"patchNsByNamespaceDocumentFileById","description":"Refresh only the file-backed fields you provide. Supplying a file replaces the canonical content; omitted metadata and processing context remain unchanged.","responses":{"200":{"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"Document identifier to poll or retrieve"},"status":{"type":"string","const":"processing","description":"Confirms the file was accepted for asynchronous processing"}},"required":["id","status"],"additionalProperties":false}}},"description":"Update accepted for processing"},"400":{"description":"Invalid file request","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/ErrorResponse"},{"$ref":"#/components/schemas/ValidationErrorResponse"}]}}}},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Unauthorized"},"402":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Insufficient balance or document quota"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Write access required for this namespace"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Document not found in this namespace"},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Filepath conflict or namespace merge prevents the update"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Internal server error"}},"summary":"Partially update document file","tags":["Ingest"],"parameters":[{"in":"path","name":"namespace","schema":{"type":"string","maxLength":100,"pattern":"^[a-zA-Z0-9_:-]+$","example":"user_alex"},"required":true,"description":"The isolated namespace. This can be an ID for your user, a project ID, or any other identifier you wish to use to scope documents."},{"in":"path","name":"id","schema":{"type":"string","minLength":1,"maxLength":255,"example":"my-doc-123"},"required":true,"description":"The public document ID"},{"in":"query","name":"taskType","schema":{"type":"string","enum":["memory","superrag"]},"description":"Processing pipeline. \"memory\" builds durable learned context; \"superrag\" optimizes the document for retrieval without generating memories."},{"in":"query","name":"dreaming","schema":{"type":"string","enum":["dynamic","instant"]},"description":"Processing mode. \"dynamic\" (default) groups related documents so memories form from coherent context. \"instant\" processes each document independently right away and bills one extra operation per document."},{"in":"query","name":"fileType","schema":{"type":"string","enum":["text","pdf","image","video","audio"]},"description":"Explicit source type used when automatic inference is insufficient"},{"in":"query","name":"mimeType","schema":{"type":"string","pattern":"^[^\\s/]+\\/[^\\s/]+$"},"description":"Explicit MIME type used when upload metadata is insufficient"}],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"file":{"description":"File contents to upload","format":"binary","type":"string"},"supportingContext":{"description":"Context used to guide memory extraction within this namespace. Max 1500 characters.","example":"Focus on product decisions, dates, and owners.","type":"string","maxLength":1500},"metadata":{"description":"JSON-encoded metadata to attach to the document and its derived memories","type":"string"},"group":{"description":"JSON-encoded metadata used to keep related context isolated during processing and recall","type":"string"},"date":{"description":"When the source content is from, in ISO 8601 format","example":"2026-01-15","type":"string"}},"additionalProperties":false}}}}}},"/ns/{namespace}/search":{"post":{"operationId":"postNsByNamespaceSearch","description":"Recall the most relevant learned context and source passages from a namespace. Hybrid search combines memories with document chunks by default, with optional query rewriting, reranking, and supporting context attachments.","responses":{"200":{"content":{"application/json":{"schema":{"type":"object","properties":{"results":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Stable identifier for the matching result","example":"mem_abc123"},"memory":{"description":"Learned fact or context returned by memory search (only present for memory results)","example":"The user prefers detailed API responses over minimal ones.","type":"string"},"chunk":{"description":"Source passage returned by chunk search (only present for chunk results from hybrid search)","example":"This is a chunk of content from a document...","type":"string"},"metadata":{"anyOf":[{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},{"type":"null"}],"description":"Public metadata attached to the result","example":{"source":"conversation","confidence":0.9}},"similarity":{"type":"number","description":"Normalized relevance score used to rank the result, from 0 to 1","example":0.89},"isLatest":{"type":"boolean","description":"Whether the memory is its latest version; false for recalled forgotten memories"},"system":{"type":"object","properties":{"updatedAt":{"type":"string","description":"ISO 8601 timestamp of the latest result update"},"createdAt":{"description":"ISO 8601 timestamp when the result was first created","type":"string"}},"required":["updatedAt"],"description":"Lifecycle and filesystem details for the result"},"included":{"description":"Requested supporting context for the result","type":"object","properties":{"related":{"description":"Memory relationships attached when requested","type":"object","properties":{"parents":{"type":"array","items":{"type":"object","properties":{"relation":{"type":"string","enum":["updates","extends","derives"],"description":"How this memory is connected to the matched memory"},"version":{"description":"Version number within the related memory's history","anyOf":[{"type":"number"},{"type":"null"}]},"memory":{"type":"string","description":"Related learned fact or context"},"metadata":{"description":"Public metadata associated with the related memory","anyOf":[{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},{"type":"null"}]},"system":{"type":"object","properties":{"updatedAt":{"type":"string","description":"ISO 8601 timestamp of the related memory's latest update"}},"required":["updatedAt"],"description":"Lifecycle details for the related memory"}},"required":["relation","memory","system"]},"description":"Earlier memories this result updates or derives from"},"children":{"type":"array","items":{"type":"object","properties":{"relation":{"type":"string","enum":["updates","extends","derives"],"description":"How this memory is connected to the matched memory"},"version":{"description":"Version number within the related memory's history","anyOf":[{"type":"number"},{"type":"null"}]},"memory":{"type":"string","description":"Related learned fact or context"},"metadata":{"description":"Public metadata associated with the related memory","anyOf":[{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},{"type":"null"}]},"system":{"type":"object","properties":{"updatedAt":{"type":"string","description":"ISO 8601 timestamp of the related memory's latest update"}},"required":["updatedAt"],"description":"Lifecycle details for the related memory"}},"required":["relation","memory","system"]},"description":"Newer memories that update or extend this result"},"siblings":{"type":"array","items":{"type":"object","properties":{"relation":{"type":"string","enum":["updates","extends","derives"],"description":"How this memory is connected to the matched memory"},"version":{"description":"Version number within the related memory's history","anyOf":[{"type":"number"},{"type":"null"}]},"memory":{"type":"string","description":"Related learned fact or context"},"metadata":{"description":"Public metadata associated with the related memory","anyOf":[{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},{"type":"null"}]},"system":{"type":"object","properties":{"updatedAt":{"type":"string","description":"ISO 8601 timestamp of the related memory's latest update"}},"required":["updatedAt"],"description":"Lifecycle details for the related memory"}},"required":["relation","memory","system"]},"description":"Other memories derived from related context"}},"required":["parents","children","siblings"]},"document":{"description":"Source document attached when requested and available","type":"object","properties":{"id":{"type":"string","description":"Source document identifier"},"title":{"description":"Source document title","anyOf":[{"type":"string"},{"type":"null"}]},"type":{"description":"Detected source or content type","anyOf":[{"type":"string"},{"type":"null"}]},"metadata":{"description":"Public metadata attached to the source document","anyOf":[{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},{"type":"null"}]},"summary":{"description":"Generated summary of the source document","anyOf":[{"type":"string"},{"type":"null"}]},"createdAt":{"type":"string","description":"ISO 8601 timestamp when the source document was created"},"updatedAt":{"type":"string","description":"ISO 8601 timestamp of the source document's latest update"}},"required":["id","createdAt","updatedAt"]}}}},"required":["id","metadata","similarity","isLatest","system"]},"description":"Ranked memories and source chunks matching the query"},"searchTime":{"type":"number","description":"Server-side search duration in milliseconds"}},"required":["results","searchTime"]}}},"description":"Search results"},"400":{"description":"Invalid request parameters","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/ErrorResponse"},{"$ref":"#/components/schemas/ValidationErrorResponse"}]}}}},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Unauthorized"},"402":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Search quota or credits exhausted"},"403":{"description":"The API key cannot access this endpoint or namespace","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Server error"}},"summary":"Search memories","tags":["Recall (Search)"],"parameters":[{"in":"path","name":"namespace","schema":{"type":"string","maxLength":100,"pattern":"^[a-zA-Z0-9_:-]+$","example":"user_alex"},"required":true,"description":"The isolated namespace to search. This can be an ID for your user, a project ID, or any other identifier you wish to use to scope memories."},{"in":"query","name":"limit","schema":{"default":10,"example":10,"type":"integer","minimum":1,"maximum":100},"description":"Maximum number of results to return"},{"in":"query","name":"searchMode","schema":{"default":"hybrid","example":"hybrid","type":"string","enum":["hybrid","memories","chunks"]},"description":"Search surface. \"hybrid\" combines learned memories with source chunks, \"memories\" returns learned context, and \"chunks\" returns source passages."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"query":{"type":"string","minLength":1,"description":"Natural-language question, topic, or phrase to retrieve relevant context for. Replaces the v4 `q` field.","example":"what are the API rate limits"},"filter":{"description":"Type-safe metadata conditions applied before ranking results. Replaces the v4 `filters` field and unifies both legacy filter formats into one expression type.","example":{"field":"source","operator":"eq","value":"api-docs"},"$ref":"#/components/schemas/FilterExpression"},"attach":{"default":{"documents":false,"related":false,"forgotten":false},"description":"Optional context to include alongside each matching result","type":"object","properties":{"documents":{"default":false,"description":"Attach the source document for each result when one is available","type":"boolean"},"related":{"default":false,"description":"Attach parent, child, and sibling memories that explain how each memory evolved","type":"boolean"},"forgotten":{"default":false,"description":"Allow forgotten memories to participate in recall","type":"boolean"}},"additionalProperties":false},"threshold":{"default":0.3,"description":"Minimum relevance score from 0 to 1. Raise it for precision (fewer, accurate results) or lower it for broader recall (more results).","example":0.5,"type":"number","minimum":0,"maximum":1},"rerank":{"default":"none","description":"Post-retrieval ranking. \"order\" improves result ordering; \"aggregate\" also combines overlapping context into cleaner answers. This is helpful if you want to ensure the most relevant results are returned.","example":"order","type":"string","enum":["none","order","aggregate"]},"rewriteQuery":{"default":false,"description":"Expand and clarify the query before retrieval to improve recall for conversational or underspecified prompts. This increases the latency by about 400ms.","example":false,"type":"boolean"}},"required":["query"],"additionalProperties":false}}}},"x-codeSamples":[{"lang":"bash","label":"cURL","source":"curl -X POST \"https://api.supermemory.ai/ns/user_123/search?searchMode=hybrid&limit=5\" \\\n  -H \"Authorization: Bearer $SUPERMEMORY_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"query\": \"gift ideas for a VP promotion after a Tokyo offsite\",\n    \"filter\": {\n      \"operator\": \"and\",\n      \"operands\": [\n        { \"field\": \"category\", \"operator\": \"eq\", \"value\": \"work\" },\n        { \"field\": \"importance\", \"operator\": \"gte\", \"value\": 0.8 }\n      ]\n    },\n    \"attach\": { \"related\": true }\n  }'"}]}},"/ns/{namespace}/profile":{"post":{"operationId":"postNsByNamespaceProfile","description":"Read a continuously maintained understanding of the subject represented by this namespace. Stable facts, evolving context, and selected custom buckets are returned together without requiring a search query.","responses":{"200":{"content":{"application/json":{"schema":{"type":"object","properties":{"profile":{"type":"object","properties":{"static":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Memory ID, or an aggregated_-prefixed ID for a summary synthesized from several memories"},"memory":{"type":"string","description":"Memory text"}},"required":["id","memory"]},"description":"Durable facts that define the subject and rarely change, such as identity or long-term preferences"},"dynamic":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Memory ID, or an aggregated_-prefixed ID for a summary synthesized from several memories"},"memory":{"type":"string","description":"Memory text"}},"required":["id","memory"]},"description":"Recent or evolving context, such as current goals, projects, and active interests"},"buckets":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Memory ID, or an aggregated_-prefixed ID for a summary synthesized from several memories"},"memory":{"type":"string","description":"Memory text"}},"required":["id","memory"]}},"description":"Custom profile sections keyed by bucket name, with the memories currently assigned to each bucket"}},"required":["static","dynamic","buckets"],"description":"Continuously maintained understanding of the subject represented by this namespace"}},"required":["profile"]}},"text/markdown":{"schema":{"type":"string"}}},"description":"Namespace profile. Send `Accept: text/markdown` to receive it as a markdown document instead of JSON."},"400":{"description":"Invalid request parameters","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/ErrorResponse"},{"$ref":"#/components/schemas/ValidationErrorResponse"}]}}}},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Unauthorized"},"403":{"description":"The API key cannot access this endpoint or namespace","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Server error"}},"summary":"Get profile","tags":["Profiles"],"parameters":[{"in":"path","name":"namespace","schema":{"type":"string","maxLength":100,"pattern":"^[a-zA-Z0-9_:-]+$","example":"user_alex"},"required":true,"description":"The isolated namespace to search. This can be an ID for your user, a project ID, or any other identifier you wish to use to scope memories."}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"filter":{"description":"Type-safe metadata conditions that limit which memories contribute to the profile","$ref":"#/components/schemas/FilterExpression"},"buckets":{"description":"Custom buckets to return. Omit to return every effective bucket.","example":["interests","goals"],"maxItems":50,"type":"array","items":{"type":"string","minLength":1,"maxLength":64,"pattern":"^[a-z0-9][a-z0-9_-]*$","description":"Stable slug for the bucket, stored on each memory"}}},"additionalProperties":false}}}},"x-codeSamples":[{"lang":"bash","label":"cURL","source":"curl -X POST \"https://api.supermemory.ai/ns/user_123/profile\" \\\n  -H \"Authorization: Bearer $SUPERMEMORY_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"filter\": {\n      \"field\": \"region\",\n      \"operator\": \"eq\",\n      \"value\": \"us-west\"\n    }\n  }'"}]}},"/ns/{namespace}/profile/buckets":{"get":{"operationId":"getNsByNamespaceProfileBuckets","description":"Inspect the profile taxonomy active in this namespace. The response combines organization-wide buckets with namespace-owned additions as a concise name-to-description map.","responses":{"200":{"content":{"application/json":{"schema":{"type":"object","properties":{"buckets":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"string"},"description":"Effective bucket definitions keyed by name. Includes organization buckets and namespace-owned additions."}},"required":["buckets"]}}},"description":"Effective namespace profile bucket definitions"},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/ErrorResponse"},{"$ref":"#/components/schemas/ValidationErrorResponse"}]}}}},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Unauthorized"},"403":{"description":"The API key cannot access this endpoint or namespace","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"summary":"Get profile buckets","tags":["Profiles"],"parameters":[{"in":"path","name":"namespace","schema":{"type":"string","maxLength":100,"pattern":"^[a-zA-Z0-9_:-]+$","example":"user_alex"},"required":true,"description":"The isolated namespace to search. This can be an ID for your user, a project ID, or any other identifier you wish to use to scope memories."}],"x-codeSamples":[{"lang":"bash","label":"cURL","source":"curl \"https://api.supermemory.ai/ns/user_123/profile/buckets\" \\\n  -H \"Authorization: Bearer $SUPERMEMORY_API_KEY\""},{"lang":"typescript","label":"TypeScript SDK","source":"import Supermemory from \"supermemory\";\n\nconst client = new Supermemory({\n  apiKey: process.env.SUPERMEMORY_API_KEY,\n});\n\nconst res = await fetch(\"https://api.supermemory.ai/ns/user_123/profile/buckets\", {\n  headers: {\n    Authorization: `Bearer ${process.env.SUPERMEMORY_API_KEY}`,\n  },\n});\nconst data = await res.json();\nconsole.log(data);"}]},"put":{"operationId":"putNsByNamespaceProfileBuckets","description":"Teach Supermemory new ways to organize this namespace's profile, or refine how existing namespace-owned buckets are classified. Omitted buckets remain unchanged and organization-wide buckets stay protected.","responses":{"200":{"content":{"application/json":{"schema":{"type":"object","properties":{"buckets":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"string"},"description":"Effective bucket definitions keyed by name. Includes organization buckets and namespace-owned additions."}},"required":["buckets"]}}},"description":"Updated effective namespace profile bucket definitions"},"400":{"description":"Invalid profile bucket definitions","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/ErrorResponse"},{"$ref":"#/components/schemas/ValidationErrorResponse"}]}}}},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Unauthorized"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Namespace write access required"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Namespace not found"},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"An organization-level bucket cannot be changed"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Internal server error"}},"summary":"Add or update profile buckets","tags":["Profiles"],"parameters":[{"in":"path","name":"namespace","schema":{"type":"string","maxLength":100,"pattern":"^[a-zA-Z0-9_:-]+$","example":"user_alex"},"required":true,"description":"The isolated namespace to search. This can be an ID for your user, a project ID, or any other identifier you wish to use to scope memories."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"buckets":{"type":"object","propertyNames":{"type":"string","minLength":1,"maxLength":64,"pattern":"^[a-z0-9][a-z0-9_-]*$","description":"Stable slug for the bucket, stored on each memory"},"additionalProperties":{"type":"string","maxLength":2000},"description":"Namespace-owned bucket names mapped to descriptions that guide memory classification. Existing names are updated; new names are added.","example":{"interests":"Topics the subject actively follows"}}},"required":["buckets"],"additionalProperties":false}}}}},"delete":{"operationId":"deleteNsByNamespaceProfileBuckets","description":"Remove profile categories created specifically for this namespace. Unknown names are safely ignored, while organization-wide buckets remain protected.","responses":{"200":{"content":{"application/json":{"schema":{"type":"object","properties":{"buckets":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"string"},"description":"Effective bucket definitions keyed by name. Includes organization buckets and namespace-owned additions."}},"required":["buckets"]}}},"description":"Updated effective namespace profile bucket definitions"},"400":{"description":"Invalid profile bucket names","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/ErrorResponse"},{"$ref":"#/components/schemas/ValidationErrorResponse"}]}}}},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Unauthorized"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Namespace write access required"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Namespace not found"},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"An organization-level bucket cannot be deleted"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Internal server error"}},"summary":"Delete profile buckets","tags":["Profiles"],"parameters":[{"in":"path","name":"namespace","schema":{"type":"string","maxLength":100,"pattern":"^[a-zA-Z0-9_:-]+$","example":"user_alex"},"required":true,"description":"The isolated namespace to search. This can be an ID for your user, a project ID, or any other identifier you wish to use to scope memories."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"buckets":{"minItems":1,"maxItems":50,"type":"array","items":{"type":"string","minLength":1,"maxLength":64,"pattern":"^[a-z0-9][a-z0-9_-]*$","description":"Stable slug for the bucket, stored on each memory"},"description":"Namespace-owned bucket names to delete. Organization-level buckets are protected and cannot be removed here.","example":["interests"]}},"required":["buckets"],"additionalProperties":false}}}}}},"/ns/{namespace}/memories":{"delete":{"operationId":"deleteNsByNamespaceMemories","description":"Remove exact memories from normal recall while preserving their audit history. Each ID is handled independently and any missing or ineligible memory is reported without rolling back successful changes.","responses":{"200":{"content":{"application/json":{"schema":{"type":"object","properties":{"count":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"Number of memories matched by this operation"},"errors":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Requested memory identifier"},"error":{"type":"string","description":"Why the memory could not be forgotten"}},"required":["id","error"],"additionalProperties":false},"description":"Per-memory failures for exact-ID requests"},"matches":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Stable identifier of the matched memory"},"memory":{"type":"string","description":"Matched memory text"}},"required":["id","memory"],"additionalProperties":false},"description":"Memories selected by the operation, whether previewed or forgotten"}},"required":["count","errors","matches"],"additionalProperties":false}}},"description":"Exact memory forget completed"},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/ErrorResponse"},{"$ref":"#/components/schemas/ValidationErrorResponse"}]}}}},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Unauthorized"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Namespace write access denied"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Server error"}},"summary":"Forget memories by ID","tags":["Content Management"],"parameters":[{"in":"path","name":"namespace","schema":{"type":"string","maxLength":100,"pattern":"^[a-zA-Z0-9_:-]+$","example":"user_alex"},"required":true,"description":"Namespace containing the memories to forget. This can be an ID for your user, a project ID, or any other identifier you wish to use to scope memories."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"ids":{"minItems":1,"maxItems":500,"type":"array","items":{"type":"string","minLength":1,"description":"Stable memory identifier"},"description":"Memory identifiers to remove from normal recall","example":["mem_abc123"]}},"required":["ids"],"additionalProperties":false}}}},"x-codeSamples":[{"lang":"bash","label":"cURL","source":"curl -X DELETE \"https://api.supermemory.ai/ns/user_123/memories\" \\\n  -H \"Authorization: Bearer $SUPERMEMORY_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{ \"ids\": [\"mem_1\", \"mem_2\"] }'"}]}},"/ns/{namespace}/memories/semantic":{"delete":{"operationId":"deleteNsByNamespaceMemoriesSemantic","description":"Describe what should be forgotten in natural language, then preview or apply the matching set. Use dry-run results with the exact-ID endpoint when you need a reviewable, drift-free workflow.","responses":{"200":{"content":{"application/json":{"schema":{"type":"object","properties":{"count":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"Number of memories matched by this operation"},"errors":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Requested memory identifier"},"error":{"type":"string","description":"Why the memory could not be forgotten"}},"required":["id","error"],"additionalProperties":false},"description":"Per-memory failures for exact-ID requests"},"matches":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Stable identifier of the matched memory"},"memory":{"type":"string","description":"Matched memory text"}},"required":["id","memory"],"additionalProperties":false},"description":"Memories selected by the operation, whether previewed or forgotten"}},"required":["count","errors","matches"],"additionalProperties":false}}},"description":"Semantic memory forget completed or previewed"},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/ErrorResponse"},{"$ref":"#/components/schemas/ValidationErrorResponse"}]}}}},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Unauthorized"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Namespace write access denied"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Server error"}},"summary":"Forget memories semantically","tags":["Content Management"],"parameters":[{"in":"path","name":"namespace","schema":{"type":"string","maxLength":100,"pattern":"^[a-zA-Z0-9_:-]+$","example":"user_alex"},"required":true,"description":"Namespace containing the memories to forget. This can be an ID for your user, a project ID, or any other identifier you wish to use to scope memories."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"query":{"type":"string","minLength":1,"maxLength":2000,"description":"Natural-language description of the memories that should be forgotten","example":"everything about the old pricing plans"},"dryRun":{"type":"boolean","description":"When true, preview matching memories without changing their recall state","example":true}},"required":["query","dryRun"],"additionalProperties":false}}}},"x-codeSamples":[{"lang":"bash","label":"cURL","source":"curl -X DELETE \"https://api.supermemory.ai/ns/user_123/memories/semantic\" \\\n  -H \"Authorization: Bearer $SUPERMEMORY_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"query\": \"forget everything about the old pricing plan\",\n    \"dryRun\": true\n  }'"}]}},"/ns/{namespace}/list/{type}":{"post":{"operationId":"postNsByNamespaceListByType","parameters":[{"in":"path","name":"namespace","schema":{"type":"string","maxLength":100,"pattern":"^[a-zA-Z0-9_:-]+$","example":"user_alex"},"required":true,"description":"Namespace containing the resources to list. This can be an ID for your user, a project ID, or any other identifier you wish to use to scope resources."},{"in":"path","name":"type","schema":{"type":"string","enum":["documents","chunks","memories"],"example":"memories"},"required":true,"description":"Resource collection to list: source documents, extracted chunks, or learned memories"},{"in":"query","name":"page","schema":{"example":1,"anyOf":[{"type":"string","pattern":"^\\d+$"},{"type":"number"}]},"description":"One-based page number"},{"in":"query","name":"limit","schema":{"example":10,"anyOf":[{"type":"string","pattern":"^\\d+$"},{"type":"number"}]},"description":"Maximum resources to return per page"},{"in":"query","name":"sort","schema":{"example":"createdAt","type":"string","enum":["createdAt","updatedAt","position"]},"description":"Field used to order results. Position is available only when listing chunks."},{"in":"query","name":"order","schema":{"default":"desc","example":"desc","type":"string","enum":["asc","desc"]},"description":"Ascending or descending sort direction"}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"filter":{"description":"Type-safe metadata conditions applied before pagination","$ref":"#/components/schemas/FilterExpression"}},"additionalProperties":false}}}},"description":"Browse documents, source chunks, or learned memories through one predictable paginated contract. Choose the collection in the path; the other collection arrays remain empty for a stable response shape.","responses":{"200":{"content":{"application/json":{"schema":{"type":"object","properties":{"documents":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Stable document identifier"},"title":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Extracted or caller-provided document title"},"type":{"type":"string","description":"Detected source or content type"},"summary":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Generated summary of the document, when available"},"metadata":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{},"description":"Public metadata attached to the document"},"url":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Original source URL, when the document was ingested from the web"},"system":{"type":"object","properties":{"status":{"type":"string","description":"Current extraction and memory-processing status"},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$","description":"ISO 8601 timestamp when the document was created"},"updatedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$","description":"ISO 8601 timestamp of the latest document update"}},"required":["status","createdAt","updatedAt"],"description":"Processing status, lifecycle timestamps, and storage path maintained by Supermemory"}},"required":["id","title","type","summary","metadata","url","system"],"description":"A document in this namespace without its content"},"description":"Documents on this page; empty when a different resource type is requested"},"chunks":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Stable chunk identifier"},"position":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Zero-based order within the document"},"content":{"type":"string","description":"Chunk text used for retrieval"},"type":{"type":"string","description":"Chunk content type"},"metadata":{"anyOf":[{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},{"type":"null"}],"description":"Chunk metadata, when available"},"system":{"type":"object","properties":{"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$","description":"ISO 8601 timestamp when the chunk was created"}},"required":["createdAt"],"description":"Lifecycle timestamps maintained by Supermemory"},"documentId":{"type":"string","description":"ID of the chunk's parent document"}},"required":["id","position","content","type","metadata","system","documentId"]},"description":"Chunks on this page; empty when a different resource type is requested"},"memories":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Stable memory identifier"},"memory":{"type":"string","description":"Learned fact or context extracted from the document"},"metadata":{"anyOf":[{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},{"type":"null"}],"description":"Memory metadata, including temporal context when available"},"isStatic":{"type":"boolean","description":"Whether the memory belongs to the stable profile section"},"isInference":{"type":"boolean","description":"Whether the memory was inferred rather than explicitly stated"},"isLatest":{"type":"boolean","description":"Whether this is the newest version in its memory chain"},"isForgotten":{"type":"boolean","description":"Whether this memory has been excluded from normal recall"},"version":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Version number within the memory chain"},"system":{"type":"object","properties":{"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$","description":"ISO 8601 timestamp when this memory version was created"},"updatedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$","description":"ISO 8601 timestamp of the latest update to this version"}},"required":["createdAt","updatedAt"],"description":"Lifecycle timestamps maintained by Supermemory"}},"required":["id","memory","metadata","isStatic","isInference","isLatest","isForgotten","version","system"],"description":"A memory formed from documents in this namespace"},"description":"Memories on this page; empty when a different resource type is requested"},"pagination":{"type":"object","properties":{"currentPage":{"type":"number","description":"Current one-based page number"},"limit":{"default":10,"description":"Maximum resources returned per page","type":"number","maximum":1100},"totalItems":{"type":"number","description":"Total resources matching the request"},"totalPages":{"type":"number","description":"Total pages available at the selected limit"}},"required":["currentPage","totalItems","totalPages"],"description":"Page metadata for the selected resource collection"}},"required":["documents","chunks","memories","pagination"],"description":"A namespace-scoped page of one resource type"}}},"description":"Namespace resources retrieved successfully"},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/ErrorResponse"},{"$ref":"#/components/schemas/ValidationErrorResponse"}]}}}},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Unauthorized"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Namespace access denied"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Internal server error"}},"summary":"List resources","tags":["Content Management"]}},"/namespaces":{"get":{"operationId":"getNamespaces","description":"Discover every namespace available to the caller, including its purpose, document volume, memory count, and lifecycle timestamps.","responses":{"200":{"content":{"application/json":{"schema":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Internal identifier for the namespace"},"namespace":{"type":"string","description":"Namespace identifier used in API paths"},"documentCount":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"Number of active source documents in the namespace"},"memoryCount":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"Number of current, recallable memories in the namespace"},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Human-readable purpose or scope of the namespace"},"system":{"type":"object","properties":{"createdAt":{"type":"string","format":"date-time","description":"ISO 8601 timestamp when the namespace was created"},"updatedAt":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of the latest namespace update"}},"required":["createdAt","updatedAt"],"description":"Namespace lifecycle timestamps"}},"required":["id","namespace","documentCount","memoryCount","description","system"]}}}},"description":"Namespaces available to the caller"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Unauthorized"},"403":{"description":"The API key cannot access this endpoint or namespace","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Internal server error"}},"summary":"List namespaces","tags":["Namespaces"]}},"/ns":{"get":{"operationId":"getNs","description":"Discover every namespace available to the caller, including its purpose, document volume, memory count, and lifecycle timestamps.","responses":{"200":{"content":{"application/json":{"schema":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Internal identifier for the namespace"},"namespace":{"type":"string","description":"Namespace identifier used in API paths"},"documentCount":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"Number of active source documents in the namespace"},"memoryCount":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"Number of current, recallable memories in the namespace"},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Human-readable purpose or scope of the namespace"},"system":{"type":"object","properties":{"createdAt":{"type":"string","format":"date-time","description":"ISO 8601 timestamp when the namespace was created"},"updatedAt":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of the latest namespace update"}},"required":["createdAt","updatedAt"],"description":"Namespace lifecycle timestamps"}},"required":["id","namespace","documentCount","memoryCount","description","system"]}}}},"description":"Namespaces available to the caller"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Unauthorized"},"403":{"description":"The API key cannot access this endpoint or namespace","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Internal server error"}},"summary":"List namespaces","tags":["Namespaces"]}},"/ns/{namespace}":{"get":{"operationId":"getNsByNamespace","description":"Read the supporting context that helps Supermemory understand content and form better memories inside this namespace.","responses":{"200":{"content":{"application/json":{"schema":{"type":"object","properties":{"namespace":{"type":"string","description":"Namespace identifier used in API paths"},"supportingContext":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Background that helps Supermemory interpret documents and form better memories in this namespace"},"system":{"type":"object","properties":{"createdAt":{"type":"string","format":"date-time","description":"ISO 8601 timestamp when the namespace was created"},"updatedAt":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of the latest settings update"}},"required":["createdAt","updatedAt"],"description":"Namespace lifecycle timestamps"}},"required":["namespace","supportingContext","system"]}}},"description":"Namespace settings"},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/ErrorResponse"},{"$ref":"#/components/schemas/ValidationErrorResponse"}]}}}},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Unauthorized"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Namespace access denied"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Namespace not found"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Internal server error"}},"summary":"Get namespace settings","tags":["Namespaces"],"parameters":[{"in":"path","name":"namespace","schema":{"type":"string","maxLength":100,"pattern":"^[a-zA-Z0-9_:-]+$","example":"user_alex"},"required":true,"description":"Namespace identifier. This can be an ID for your user, a project ID, or any other identifier you wish to use to scope documents and memories."}]},"patch":{"operationId":"patchNsByNamespace","parameters":[{"in":"path","name":"namespace","schema":{"type":"string","maxLength":100,"pattern":"^[a-zA-Z0-9_:-]+$","example":"user_alex"},"required":true,"description":"Namespace identifier. This can be an ID for your user, a project ID, or any other identifier you wish to use to scope documents and memories."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"supportingContext":{"description":"Background that guides how Supermemory interprets documents and forms memories. Max 1500 characters. Set null to clear it.","example":"This namespace holds Acme Corp support tickets.","anyOf":[{"type":"string","maxLength":1500},{"type":"null"}]}},"additionalProperties":false}}}},"description":"Shape how Supermemory understands an existing namespace by updating the background context used during ingestion and memory formation.","responses":{"200":{"content":{"application/json":{"schema":{"type":"object","properties":{"namespace":{"type":"string","description":"Namespace identifier used in API paths"},"supportingContext":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Background that helps Supermemory interpret documents and form better memories in this namespace"},"system":{"type":"object","properties":{"createdAt":{"type":"string","format":"date-time","description":"ISO 8601 timestamp when the namespace was created"},"updatedAt":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of the latest settings update"}},"required":["createdAt","updatedAt"],"description":"Namespace lifecycle timestamps"}},"required":["namespace","supportingContext","system"]}}},"description":"Updated namespace settings"},"400":{"description":"Invalid namespace settings","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/ErrorResponse"},{"$ref":"#/components/schemas/ValidationErrorResponse"}]}}}},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Unauthorized"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Write access required"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Namespace not found"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Internal server error"}},"summary":"Update namespace settings","tags":["Namespaces"]},"delete":{"operationId":"deleteNsByNamespace","description":"Retire a namespace by permanently deleting its content, or preserve that knowledge by moving everything into another namespace first. Moves are queued and complete asynchronously.","responses":{"200":{"content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","const":true,"description":"Confirms the namespace was deleted"},"namespace":{"type":"string","description":"Deleted namespace identifier"},"deletedDocumentsCount":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"Number of documents permanently removed"},"deletedMemoriesCount":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"Number of memories permanently removed"}},"required":["success","namespace","deletedDocumentsCount","deletedMemoriesCount"]}}},"description":"Namespace permanently deleted"},"202":{"content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","const":true,"description":"Confirms the namespace move was accepted"},"status":{"type":"string","const":"queued","description":"The move continues asynchronously after this response"},"operationId":{"type":"string","description":"Identifier used to trace the asynchronous move operation"},"namespace":{"type":"string","description":"Source namespace being removed"},"moveTo":{"type":"string","description":"Destination namespace receiving the content"}},"required":["success","status","operationId","namespace","moveTo"]}}},"description":"Namespace move queued"},"400":{"description":"Invalid move destination","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/ErrorResponse"},{"$ref":"#/components/schemas/ValidationErrorResponse"}]}}}},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Unauthorized"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Write access required"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Namespace not found"},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Namespace is busy"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Internal server error"}},"summary":"Delete namespace","tags":["Namespaces"],"parameters":[{"in":"path","name":"namespace","schema":{"type":"string","maxLength":100,"pattern":"^[a-zA-Z0-9_:-]+$","example":"user_alex"},"required":true,"description":"Namespace identifier. This can be an ID for your user, a project ID, or any other identifier you wish to use to scope documents and memories."}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"default":{},"type":"object","properties":{"moveTo":{"description":"Destination namespace that should receive this namespace's content before deletion. Omit to permanently delete the content.","example":"project_archive","type":"string","maxLength":100,"pattern":"^[a-zA-Z0-9_:-]+$"}},"additionalProperties":false}}}}}},"/organization":{"get":{"operationId":"getOrganization","description":"Read the shared background that guides memory formation across the organization, together with the number of active namespaces.","responses":{"200":{"content":{"application/json":{"schema":{"type":"object","properties":{"organizationalContext":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Shared background that helps Supermemory interpret content consistently across every namespace"},"namespaceCount":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"Number of namespaces in the organization"}},"required":["organizationalContext","namespaceCount"]}}},"description":"Organization settings retrieved successfully"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Unauthorized"},"403":{"description":"The API key cannot access this endpoint or namespace","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Internal server error"}},"summary":"Get organization settings","tags":["Organization"]},"patch":{"operationId":"patchOrganization","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"organizationalContext":{"anyOf":[{"type":"string","minLength":1},{"type":"null"}],"description":"Shared background that guides memory formation across every namespace. Set null to clear it.","example":"Acme Corp builds developer tools for startups."}},"required":["organizationalContext"],"additionalProperties":false}}}},"description":"Give Supermemory organization-wide background that improves how content is interpreted across every namespace. Send null to remove the existing context.","responses":{"200":{"content":{"application/json":{"schema":{"type":"object","properties":{"organizationalContext":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Shared background that helps Supermemory interpret content consistently across every namespace"},"namespaceCount":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"Number of namespaces in the organization"}},"required":["organizationalContext","namespaceCount"]}}},"description":"Organization settings updated successfully"},"400":{"description":"Invalid organization settings","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/ErrorResponse"},{"$ref":"#/components/schemas/ValidationErrorResponse"}]}}}},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Unauthorized"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Admin access required"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Internal server error"}},"summary":"Update organization settings","tags":["Organization"]}}}}