{"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":{"description":"Numeric or boolean value to compare against","type":["number","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":["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":"http://localhost:6767"}],"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":"Connectors","description":"Sync external sources such as Google Drive, Notion and GitHub into a namespace"},{"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","properties":{"id":{"type":"string","minLength":1,"description":"Document identifier to poll or retrieve"},"status":{"type":"string","enum":["unknown","queued","extracting","chunking","embedding","indexing","done","failed"],"description":"The document's processing state after this request. queued when new work was queued; otherwise its current state, e.g. done for an unchanged duplicate or failed for a metadata-only update to a failed document."}},"required":["id","status"],"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":{"example":"user_alex","type":"string","maxLength":100,"pattern":"^[a-zA-Z0-9_:-]+$"},"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":{"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"},"taskType":{"description":"Processing pipeline. \"memory\" builds durable learned context; \"superrag\" optimizes the document for retrieval without generating memories.","type":"string","enum":["memory","superrag"]},"dreaming":{"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.","type":"string","enum":["dynamic","instant"]}},"required":["content"],"additionalProperties":false}}}},"x-codeSamples":[{"lang":"typescript","label":"TypeScript SDK","source":"import { Supermemory } from \"supermemory\";\n\nconst client = new Supermemory(); // reads SUPERMEMORY_API_KEY\n\nconst doc = await client.add(\"user_123\", {\n  content: \"Sarah is being promoted to VP of Product.\",\n  id: \"chat_session_1\",\n  metadata: { type: \"conversation\" },\n  dreaming: \"instant\",\n});\nconsole.log(doc.id, doc.status);"},{"lang":"python","label":"Python SDK","source":"from supermemory import Supermemory\n\nclient = Supermemory()  # reads SUPERMEMORY_API_KEY\n\ndoc = client.add(\n    \"user_123\",\n    content=\"Sarah is being promoted to VP of Product.\",\n    id=\"chat_session_1\",\n    metadata={\"type\": \"conversation\"},\n    dreaming=\"instant\",\n)\nprint(doc.id, doc.status)"},{"lang":"bash","label":"cURL","source":"curl -X POST \"https://api.supermemory.ai/ns/user_123/document\" \\\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    \"dreaming\": \"instant\"\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":{"count":{"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":["count","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":{"example":"user_alex","type":"string","maxLength":100,"pattern":"^[a-zA-Z0-9_:-]+$"},"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}}}},"x-codeSamples":[{"lang":"typescript","label":"TypeScript SDK","source":"import { Supermemory } from \"supermemory\";\n\nconst client = new Supermemory(); // reads SUPERMEMORY_API_KEY\n\nconst res = await client.documents.delete(\"user_123\", {\n  ids: [\"chat_session_1\", \"doc_roadmap\"],\n});\nconsole.log(res.count, res.errors);"},{"lang":"python","label":"Python SDK","source":"from supermemory import Supermemory\n\nclient = Supermemory()  # reads SUPERMEMORY_API_KEY\n\nres = client.documents.delete(\"user_123\", ids=[\"chat_session_1\", \"doc_roadmap\"])\nprint(res.count, res.errors)"},{"lang":"bash","label":"cURL","source":"curl -X DELETE \"https://api.supermemory.ai/ns/user_123/document\" \\\n  -H \"Authorization: Bearer $SUPERMEMORY_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{ \"ids\": [\"chat_session_1\", \"doc_roadmap\"] }'"}]}},"/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","properties":{"results":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Document identifier"},"status":{"type":"string","enum":["unknown","queued","extracting","chunking","embedding","indexing","done","failed","error"],"description":"The document's processing state after this request, or error when this item failed"},"error":{"description":"Failure reason","type":"string"},"details":{"description":"Human-readable explanation of the failure","type":"string"},"url":{"description":"URL of the failed item, when it had one","type":"string"}},"required":["id","status"],"additionalProperties":false},"description":"One result per submitted document: accepted documents first, in request order, then failed ones. Match results by id, or by url for a failed item with no id."},"count":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"Number of documents accepted"},"failed":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"Number of documents that failed"}},"required":["results","count","failed"],"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":{"example":"user_alex","type":"string","maxLength":100,"pattern":"^[a-zA-Z0-9_:-]+$"},"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":{"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"},"taskType":{"description":"Processing pipeline. \"memory\" builds durable learned context; \"superrag\" optimizes the document for retrieval without generating memories.","type":"string","enum":["memory","superrag"]},"dreaming":{"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.","type":"string","enum":["dynamic","instant"]}},"required":["documents"],"additionalProperties":false}}}},"x-codeSamples":[{"lang":"typescript","label":"TypeScript SDK","source":"import { Supermemory } from \"supermemory\";\n\nconst client = new Supermemory(); // reads SUPERMEMORY_API_KEY\n\nconst res = await client.documents.batchAdd(\"user_123\", {\n  documents: [\n    { content: \"Q3 roadmap notes\", id: \"doc_roadmap\" },\n    { content: \"Gift policy for VP promotions\", id: \"doc_gifts\" },\n  ],\n  dreaming: \"instant\",\n});\nconsole.log(res.count, res.failed);"},{"lang":"python","label":"Python SDK","source":"from supermemory import Supermemory\n\nclient = Supermemory()  # reads SUPERMEMORY_API_KEY\n\nres = client.documents.batch_add(\n    \"user_123\",\n    documents=[\n        {\"content\": \"Q3 roadmap notes\", \"id\": \"doc_roadmap\"},\n        {\"content\": \"Gift policy for VP promotions\", \"id\": \"doc_gifts\"},\n    ],\n    dreaming=\"instant\",\n)\nprint(res.count, res.failed)"},{"lang":"bash","label":"cURL","source":"curl -X POST \"https://api.supermemory.ai/ns/user_123/document/batch\" \\\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    \"dreaming\": \"instant\"\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 include 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":{"description":"Extracted or caller-provided document title","example":"API Rate Limiting Policy","type":["string","null"]},"type":{"type":"string","description":"Detected source or content type","example":"text"},"summary":{"description":"Generated summary of the document, when available","type":["string","null"]},"content":{"description":"Canonical extracted text used for processing and recall","example":"Our API rate limits are 100 req/min on free and 1000 on pro.","type":["string","null"]},"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","enum":["unknown","queued","extracting","chunking","embedding","indexing","done","failed"],"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":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{},"description":"Chunk metadata; empty object when none"},"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":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{},"description":"Memory metadata, including temporal context; empty object when none"},"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. Included 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":{"example":"user_alex","type":"string","maxLength":100,"pattern":"^[a-zA-Z0-9_:-]+$"},"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":"include","schema":{"type":"array","items":{"type":"string","enum":["chunks","memories"]},"style":"form","explode":false},"description":"Comma-separated child resources to include: chunks, memories, or both."}],"x-codeSamples":[{"lang":"typescript","label":"TypeScript SDK","source":"import { Supermemory } from \"supermemory\";\n\nconst client = new Supermemory(); // reads SUPERMEMORY_API_KEY\n\nconst doc = await client.documents.get(\"user_123\", \"doc_abc123\", {\n  include: [\"chunks\", \"memories\"],\n});\nconsole.log(doc.system.status, doc.chunks?.length, doc.memories?.length);"},{"lang":"python","label":"Python SDK","source":"from supermemory import Supermemory\n\nclient = Supermemory()  # reads SUPERMEMORY_API_KEY\n\ndoc = client.documents.get(\"user_123\", \"doc_abc123\", include=[\"chunks\", \"memories\"])\nprint(doc.system.status, len(doc.chunks or []), len(doc.memories or []))"},{"lang":"bash","label":"cURL","source":"curl \"https://api.supermemory.ai/ns/user_123/document/doc_abc123?include=chunks,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","properties":{"id":{"type":"string","minLength":1,"description":"Document identifier to poll or retrieve"},"status":{"type":"string","enum":["unknown","queued","extracting","chunking","embedding","indexing","done","failed"],"description":"The document's processing state after this request. queued when new work was queued; otherwise its current state, e.g. done for an unchanged duplicate or failed for a metadata-only update to a failed document."}},"required":["id","status"],"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":{"example":"user_alex","type":"string","maxLength":100,"pattern":"^[a-zA-Z0-9_:-]+$"},"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"}],"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"},"taskType":{"description":"Processing pipeline. \"memory\" builds durable learned context; \"superrag\" optimizes the document for retrieval without generating memories.","type":"string","enum":["memory","superrag"]},"dreaming":{"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.","type":"string","enum":["dynamic","instant"]}},"additionalProperties":false}}}},"x-codeSamples":[{"lang":"typescript","label":"TypeScript SDK","source":"import { Supermemory } from \"supermemory\";\n\nconst client = new Supermemory(); // reads SUPERMEMORY_API_KEY\n\nconst updated = await client.documents.update(\"user_123\", \"chat_session_1\", {\n  content: \"Updated notes: Sarah is now VP of Product.\",\n  metadata: { type: \"conversation\" },\n});\nconsole.log(updated.status);"},{"lang":"python","label":"Python SDK","source":"from supermemory import Supermemory\n\nclient = Supermemory()  # reads SUPERMEMORY_API_KEY\n\nupdated = client.documents.update(\n    \"user_123\",\n    \"chat_session_1\",\n    content=\"Updated notes: Sarah is now VP of Product.\",\n    metadata={\"type\": \"conversation\"},\n)\nprint(updated.status)"},{"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","enum":["unknown","queued","extracting","chunking","embedding","indexing","done","failed"],"description":"The document's processing state after this request. queued when new work was queued; otherwise its current state, e.g. done for an unchanged duplicate or failed for a metadata-only update to a failed document."}},"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":{"example":"user_alex","type":"string","maxLength":100,"pattern":"^[a-zA-Z0-9_:-]+$"},"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":{"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"},"taskType":{"description":"Processing pipeline. \"memory\" builds durable learned context; \"superrag\" optimizes the document for retrieval without generating memories.","type":"string","enum":["memory","superrag"]},"dreaming":{"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.","type":"string","enum":["dynamic","instant"]},"fileType":{"description":"Explicit source type used when automatic inference is insufficient","type":"string","enum":["text","pdf","image","video","audio"]},"mimeType":{"description":"Explicit MIME type used when upload metadata is insufficient","type":"string","pattern":"^[^\\s/]+\\/[^\\s/]+$"}},"required":["file"],"additionalProperties":false}}}},"x-codeSamples":[{"lang":"typescript","label":"TypeScript SDK","source":"import { Supermemory } from \"supermemory\";\nimport { openAsBlob } from \"node:fs\";\nconst client = new Supermemory(); // reads SUPERMEMORY_API_KEY\n\nconst doc = await client.documents.uploadFile(\"user_123\", {\n  file: await openAsBlob(\"notes.pdf\"),\n  metadata: JSON.stringify({ source: \"upload\" }), // multipart: metadata is a JSON string\n});\nconsole.log(doc.id, doc.status);"},{"lang":"python","label":"Python SDK","source":"from supermemory import Supermemory\nimport json\nclient = Supermemory()  # reads SUPERMEMORY_API_KEY\n\nwith open(\"notes.pdf\", \"rb\") as f:\n    doc = client.documents.upload_file(\n        \"user_123\",\n        file=f,\n        metadata=json.dumps({\"source\": \"upload\"}),  # multipart: metadata is a JSON string\n    )\nprint(doc.id, doc.status)"},{"lang":"bash","label":"cURL","source":"curl -X POST \"https://api.supermemory.ai/ns/user_123/document/file\" \\\n  -H \"Authorization: Bearer $SUPERMEMORY_API_KEY\" \\\n  -F \"file=@notes.pdf\" \\\n  -F 'metadata={\"source\":\"upload\"}'"}]}},"/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","enum":["unknown","queued","extracting","chunking","embedding","indexing","done","failed"],"description":"The document's processing state after this request. queued when new work was queued; otherwise its current state, e.g. done for an unchanged duplicate or failed for a metadata-only update to a failed document."}},"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":{"example":"user_alex","type":"string","maxLength":100,"pattern":"^[a-zA-Z0-9_:-]+$"},"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"}],"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"},"taskType":{"description":"Processing pipeline. \"memory\" builds durable learned context; \"superrag\" optimizes the document for retrieval without generating memories.","type":"string","enum":["memory","superrag"]},"dreaming":{"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.","type":"string","enum":["dynamic","instant"]},"fileType":{"description":"Explicit source type used when automatic inference is insufficient","type":"string","enum":["text","pdf","image","video","audio"]},"mimeType":{"description":"Explicit MIME type used when upload metadata is insufficient","type":"string","pattern":"^[^\\s/]+\\/[^\\s/]+$"}},"required":["file"],"additionalProperties":false}}}},"x-codeSamples":[{"lang":"typescript","label":"TypeScript SDK","source":"import { Supermemory } from \"supermemory\";\nimport { openAsBlob } from \"node:fs\";\nconst client = new Supermemory(); // reads SUPERMEMORY_API_KEY\n\nconst doc = await client.documents.replaceWithFile(\"user_123\", \"doc_abc123\", {\n  file: await openAsBlob(\"notes-v2.pdf\"),\n  metadata: JSON.stringify({ revision: 2 }),\n});\nconsole.log(doc.status);"},{"lang":"python","label":"Python SDK","source":"from supermemory import Supermemory\nimport json\nclient = Supermemory()  # reads SUPERMEMORY_API_KEY\n\nwith open(\"notes-v2.pdf\", \"rb\") as f:\n    doc = client.documents.replace_with_file(\n        \"user_123\",\n        \"doc_abc123\",\n        file=f,\n        metadata=json.dumps({\"revision\": 2}),\n    )\nprint(doc.status)"},{"lang":"bash","label":"cURL","source":"curl -X POST \"https://api.supermemory.ai/ns/user_123/document/file/doc_abc123\" \\\n  -H \"Authorization: Bearer $SUPERMEMORY_API_KEY\" \\\n  -F \"file=@notes-v2.pdf\" \\\n  -F 'metadata={\"revision\":2}'"}]},"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","enum":["unknown","queued","extracting","chunking","embedding","indexing","done","failed"],"description":"The document's processing state after this request. queued when new work was queued; otherwise its current state, e.g. done for an unchanged duplicate or failed for a metadata-only update to a failed document."}},"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":{"example":"user_alex","type":"string","maxLength":100,"pattern":"^[a-zA-Z0-9_:-]+$"},"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"}],"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"},"taskType":{"description":"Processing pipeline. \"memory\" builds durable learned context; \"superrag\" optimizes the document for retrieval without generating memories.","type":"string","enum":["memory","superrag"]},"dreaming":{"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.","type":"string","enum":["dynamic","instant"]},"fileType":{"description":"Explicit source type used when automatic inference is insufficient","type":"string","enum":["text","pdf","image","video","audio"]},"mimeType":{"description":"Explicit MIME type used when upload metadata is insufficient","type":"string","pattern":"^[^\\s/]+\\/[^\\s/]+$"}},"additionalProperties":false}}}},"x-codeSamples":[{"lang":"typescript","label":"TypeScript SDK","source":"import { Supermemory } from \"supermemory\";\n\nconst client = new Supermemory(); // reads SUPERMEMORY_API_KEY\n\nconst doc = await client.documents.updateFile(\"user_123\", \"doc_abc123\", {\n  metadata: JSON.stringify({ reviewed: true }), // file is optional here\n});\nconsole.log(doc.status);"},{"lang":"python","label":"Python SDK","source":"from supermemory import Supermemory\nimport json\nclient = Supermemory()  # reads SUPERMEMORY_API_KEY\n\ndoc = client.documents.update_file(\n    \"user_123\",\n    \"doc_abc123\",\n    metadata=json.dumps({\"reviewed\": True}),  # file is optional here\n)\nprint(doc.status)"},{"lang":"bash","label":"cURL","source":"curl -X PATCH \"https://api.supermemory.ai/ns/user_123/document/file/doc_abc123\" \\\n  -H \"Authorization: Bearer $SUPERMEMORY_API_KEY\" \\\n  -F 'metadata={\"reviewed\":true}'"}]}},"/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":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{},"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"},"isInference":{"type":"boolean","description":"Whether the memory was inferred rather than stated directly; false for chunks"},"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 included when requested","type":"object","properties":{"parents":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Related memory ID"},"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","type":["number","null"]},"memory":{"type":"string","description":"Related learned fact or context"},"metadata":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{},"description":"Public metadata associated with the related memory"},"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":["id","relation","memory","metadata","system"]},"description":"Earlier memories this result updates or derives from"},"children":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Related memory ID"},"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","type":["number","null"]},"memory":{"type":"string","description":"Related learned fact or context"},"metadata":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{},"description":"Public metadata associated with the related memory"},"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":["id","relation","memory","metadata","system"]},"description":"Newer memories that update or extend this result"},"siblings":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Related memory ID"},"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","type":["number","null"]},"memory":{"type":"string","description":"Related learned fact or context"},"metadata":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{},"description":"Public metadata associated with the related memory"},"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":["id","relation","memory","metadata","system"]},"description":"Other memories derived from related context"}},"required":["parents","children","siblings"]},"document":{"description":"Source document included when requested and available","type":"object","properties":{"id":{"type":"string","description":"Source document identifier"},"title":{"description":"Source document title","type":["string","null"]},"type":{"description":"Detected source or content type","type":["string","null"]},"metadata":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{},"description":"Public metadata attached to the source document"},"summary":{"description":"Generated summary of the source document","type":["string","null"]},"system":{"type":"object","properties":{"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":["createdAt","updatedAt"],"description":"Lifecycle timestamps maintained by Supermemory"}},"required":["id","title","type","metadata","summary","system"]}}}},"required":["id","metadata","similarity","isLatest","isInference","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":{"example":"user_alex","type":"string","maxLength":100,"pattern":"^[a-zA-Z0-9_:-]+$"},"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":{"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"},"searchMode":{"default":"hybrid","description":"Search surface. \"hybrid\" combines learned memories with source chunks, \"memories\" returns learned context, and \"chunks\" returns source passages.","example":"hybrid","type":"string","enum":["hybrid","memories","chunks"]},"limit":{"default":10,"description":"Maximum number of results to return","example":10,"type":"integer","minimum":1,"maximum":100},"include":{"default":{"documents":false,"related":false,"forgotten":false},"description":"Optional context to include alongside each matching result","example":{"related":true},"type":"object","properties":{"documents":{"default":false,"description":"Include the source document for each result when one is available","type":"boolean"},"related":{"default":false,"description":"Include parent, child, and sibling memories that explain how each memory evolved","type":"boolean"},"forgotten":{"default":false,"description":"Let forgotten and expired memories appear in results","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":"typescript","label":"TypeScript SDK","source":"import { Supermemory } from \"supermemory\";\n\nconst client = new Supermemory(); // reads SUPERMEMORY_API_KEY\n\nconst { results, searchTime } = await client.search(\"user_123\", {\n  query: \"gift ideas for a VP promotion after a Tokyo offsite\",\n  searchMode: \"hybrid\",\n  limit: 5,\n  include: { related: true },\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});\nfor (const r of results) console.log(r.similarity.toFixed(2), r.memory ?? r.chunk);"},{"lang":"python","label":"Python SDK","source":"from supermemory import Supermemory\n\nclient = Supermemory()  # reads SUPERMEMORY_API_KEY\n\nresponse = client.search(\n    \"user_123\",\n    query=\"gift ideas for a VP promotion after a Tokyo offsite\",\n    search_mode=\"hybrid\",\n    limit=5,\n    include={\"related\": True},\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)\nfor r in response.results:\n    print(round(r.similarity, 2), r.memory or r.chunk)"},{"lang":"bash","label":"cURL","source":"curl -X POST \"https://api.supermemory.ai/ns/user_123/search\" \\\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    \"searchMode\": \"hybrid\",\n    \"limit\": 5,\n    \"include\": { \"related\": true },\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  }'"}]}},"/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":{"example":"user_alex","type":"string","maxLength":100,"pattern":"^[a-zA-Z0-9_:-]+$"},"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":"typescript","label":"TypeScript SDK","source":"import { Supermemory } from \"supermemory\";\n\nconst client = new Supermemory(); // reads SUPERMEMORY_API_KEY\n\nconst { profile } = await client.profile(\"user_123\");\nconsole.log(profile.static.map((m) => m.memory));\nconsole.log(profile.dynamic.map((m) => m.memory));"},{"lang":"python","label":"Python SDK","source":"from supermemory import Supermemory\n\nclient = Supermemory()  # reads SUPERMEMORY_API_KEY\n\nprofile = client.profile(\"user_123\").profile\nprint([m.memory for m in profile.static])\nprint([m.memory for m in profile.dynamic])"},{"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 '{}'"}]}},"/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":{"example":"user_alex","type":"string","maxLength":100,"pattern":"^[a-zA-Z0-9_:-]+$"},"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":"typescript","label":"TypeScript SDK","source":"import { Supermemory } from \"supermemory\";\n\nconst client = new Supermemory(); // reads SUPERMEMORY_API_KEY\n\nconst buckets = await client.profiles.getBuckets(\"user_123\");\nconsole.log(buckets);"},{"lang":"python","label":"Python SDK","source":"from supermemory import Supermemory\n\nclient = Supermemory()  # reads SUPERMEMORY_API_KEY\n\nbuckets = client.profiles.get_buckets(\"user_123\")\nprint(buckets)"},{"lang":"bash","label":"cURL","source":"curl \"https://api.supermemory.ai/ns/user_123/profile/buckets\" \\\n  -H \"Authorization: Bearer $SUPERMEMORY_API_KEY\""}]},"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":{"example":"user_alex","type":"string","maxLength":100,"pattern":"^[a-zA-Z0-9_:-]+$"},"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}}}},"x-codeSamples":[{"lang":"typescript","label":"TypeScript SDK","source":"import { Supermemory } from \"supermemory\";\n\nconst client = new Supermemory(); // reads SUPERMEMORY_API_KEY\n\nawait client.profiles.setBuckets(\"user_123\", {\n  buckets: {\n    work: \"Job, team, and current projects\",\n    preferences: \"Food, travel, and communication preferences\",\n  },\n});"},{"lang":"python","label":"Python SDK","source":"from supermemory import Supermemory\n\nclient = Supermemory()  # reads SUPERMEMORY_API_KEY\n\nclient.profiles.set_buckets(\n    \"user_123\",\n    buckets={\n        \"work\": \"Job, team, and current projects\",\n        \"preferences\": \"Food, travel, and communication preferences\",\n    },\n)"},{"lang":"bash","label":"cURL","source":"curl -X PUT \"https://api.supermemory.ai/ns/user_123/profile/buckets\" \\\n  -H \"Authorization: Bearer $SUPERMEMORY_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"buckets\": {\n      \"work\": \"Job, team, and current projects\",\n      \"preferences\": \"Food, travel, and communication preferences\"\n    }\n  }'"}]},"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":{"example":"user_alex","type":"string","maxLength":100,"pattern":"^[a-zA-Z0-9_:-]+$"},"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}}}},"x-codeSamples":[{"lang":"typescript","label":"TypeScript SDK","source":"import { Supermemory } from \"supermemory\";\n\nconst client = new Supermemory(); // reads SUPERMEMORY_API_KEY\n\nawait client.profiles.deleteBuckets(\"user_123\", { buckets: [\"work\"] });"},{"lang":"python","label":"Python SDK","source":"from supermemory import Supermemory\n\nclient = Supermemory()  # reads SUPERMEMORY_API_KEY\n\nclient.profiles.delete_buckets(\"user_123\", buckets=[\"work\"])"},{"lang":"bash","label":"cURL","source":"curl -X DELETE \"https://api.supermemory.ai/ns/user_123/profile/buckets\" \\\n  -H \"Authorization: Bearer $SUPERMEMORY_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{ \"buckets\": [\"work\"] }'"}]}},"/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":{"example":"user_alex","type":"string","maxLength":100,"pattern":"^[a-zA-Z0-9_:-]+$"},"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":"typescript","label":"TypeScript SDK","source":"import { Supermemory } from \"supermemory\";\n\nconst client = new Supermemory(); // reads SUPERMEMORY_API_KEY\n\nconst res = await client.memories.forget(\"user_123\", { ids: [\"mem_1\", \"mem_2\"] });\nconsole.log(res.count, res.errors);"},{"lang":"python","label":"Python SDK","source":"from supermemory import Supermemory\n\nclient = Supermemory()  # reads SUPERMEMORY_API_KEY\n\nres = client.memories.forget(\"user_123\", ids=[\"mem_1\", \"mem_2\"])\nprint(res.count, res.errors)"},{"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":{"example":"user_alex","type":"string","maxLength":100,"pattern":"^[a-zA-Z0-9_:-]+$"},"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":"typescript","label":"TypeScript SDK","source":"import { Supermemory } from \"supermemory\";\n\nconst client = new Supermemory(); // reads SUPERMEMORY_API_KEY\n\n// Preview first, then run again with dryRun: false\nconst preview = await client.memories.forgetMatching(\"user_123\", {\n  query: \"forget everything about the old pricing plan\",\n  dryRun: true,\n});\nconsole.log(preview.matches.map((m) => m.memory));"},{"lang":"python","label":"Python SDK","source":"from supermemory import Supermemory\n\nclient = Supermemory()  # reads SUPERMEMORY_API_KEY\n\n# Preview first, then run again with dry_run=False\npreview = client.memories.forget_matching(\n    \"user_123\",\n    query=\"forget everything about the old pricing plan\",\n    dry_run=True,\n)\nprint([m.memory for m in preview.matches])"},{"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":{"example":"user_alex","type":"string","maxLength":100,"pattern":"^[a-zA-Z0-9_:-]+$"},"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,"default":1,"type":"integer","minimum":1,"maximum":9007199254740991},"description":"One-based page number"},{"in":"query","name":"limit","schema":{"example":10,"default":10,"type":"integer","minimum":1,"maximum":100},"description":"Maximum resources to return per page"},{"in":"query","name":"sort","schema":{"default":"createdAt","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"},"include":{"default":{"forgotten":false},"description":"Optional extras","example":{"forgotten":true},"type":"object","properties":{"forgotten":{"default":false,"description":"List forgotten and expired memories too, with isForgotten: true. Applies to type memories only.","type":"boolean"}},"additionalProperties":false}},"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":{"description":"Extracted or caller-provided document title","type":["string","null"]},"type":{"type":"string","description":"Detected source or content type"},"summary":{"description":"Generated summary of the document, when available","type":["string","null"]},"metadata":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{},"description":"Public metadata attached to the document"},"url":{"description":"Original source URL, when the document was ingested from the web","type":["string","null"]},"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":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{},"description":"Chunk metadata; empty object when none"},"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":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{},"description":"Memory metadata, including temporal context; empty object when none"},"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"],"x-codeSamples":[{"lang":"typescript","label":"TypeScript SDK","source":"import { Supermemory } from \"supermemory\";\n\nconst client = new Supermemory(); // reads SUPERMEMORY_API_KEY\n\nconst page = await client.list(\"user_123\", \"documents\", {\n  page: 1,\n  limit: 20,\n  sort: \"createdAt\",\n  order: \"desc\",\n  filter: { field: \"type\", operator: \"eq\", value: \"conversation\" },\n});\nconsole.log(page.documents.length, page.pagination.totalPages);"},{"lang":"python","label":"Python SDK","source":"from supermemory import Supermemory\n\nclient = Supermemory()  # reads SUPERMEMORY_API_KEY\n\npage = client.list(\n    \"user_123\",\n    \"documents\",\n    page=1,\n    limit=20,\n    sort=\"createdAt\",\n    order=\"desc\",\n    filter={\"field\": \"type\", \"operator\": \"eq\", \"value\": \"conversation\"},\n)\nprint(len(page.documents), page.pagination.total_pages)"},{"lang":"bash","label":"cURL","source":"curl -X POST \"https://api.supermemory.ai/ns/user_123/list/documents?page=1&limit=20&sort=createdAt&order=desc\" \\\n  -H \"Authorization: Bearer $SUPERMEMORY_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{ \"filter\": { \"field\": \"type\", \"operator\": \"eq\", \"value\": \"conversation\" } }'"}]}},"/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":"object","properties":{"namespaces":{"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":{"description":"Human-readable purpose or scope of the namespace","type":["string","null"]},"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 on this page, newest first"},"pagination":{"type":"object","properties":{"currentPage":{"type":"number"},"limit":{"default":10,"type":"number","maximum":1100},"totalItems":{"type":"number"},"totalPages":{"type":"number"}},"required":["currentPage","totalItems","totalPages"],"description":"Pagination metadata","example":{"currentPage":1,"limit":10,"totalItems":100,"totalPages":10}}},"required":["namespaces","pagination"]}}},"description":"Namespaces available to the caller"},"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"}}}},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Internal server error"}},"summary":"List namespaces","tags":["Namespaces"],"parameters":[{"in":"query","name":"page","schema":{"default":1,"type":"integer","minimum":1,"maximum":9007199254740991},"description":"One-based page number"},{"in":"query","name":"limit","schema":{"default":10,"type":"integer","minimum":1,"maximum":100},"description":"Maximum namespaces to return per page"}],"x-codeSamples":[{"lang":"typescript","label":"TypeScript SDK","source":"import { Supermemory } from \"supermemory\";\n\nconst client = new Supermemory(); // reads SUPERMEMORY_API_KEY\n\nconst { namespaces } = await client.namespaces.list({ page: 1, limit: 50 });\nconsole.log(namespaces.map((ns) => ns.namespace));"},{"lang":"python","label":"Python SDK","source":"from supermemory import Supermemory\n\nclient = Supermemory()  # reads SUPERMEMORY_API_KEY\n\npage = client.namespaces.list(page=1, limit=50)\nprint([ns.namespace for ns in page.namespaces])"},{"lang":"bash","label":"cURL","source":"curl \"https://api.supermemory.ai/namespaces?page=1&limit=50\" \\\n  -H \"Authorization: Bearer $SUPERMEMORY_API_KEY\""}]}},"/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":"object","properties":{"namespaces":{"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":{"description":"Human-readable purpose or scope of the namespace","type":["string","null"]},"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 on this page, newest first"},"pagination":{"type":"object","properties":{"currentPage":{"type":"number"},"limit":{"default":10,"type":"number","maximum":1100},"totalItems":{"type":"number"},"totalPages":{"type":"number"}},"required":["currentPage","totalItems","totalPages"],"description":"Pagination metadata","example":{"currentPage":1,"limit":10,"totalItems":100,"totalPages":10}}},"required":["namespaces","pagination"]}}},"description":"Namespaces available to the caller"},"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"}}}},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Internal server error"}},"summary":"List namespaces","tags":["Namespaces"],"parameters":[{"in":"query","name":"page","schema":{"default":1,"type":"integer","minimum":1,"maximum":9007199254740991},"description":"One-based page number"},{"in":"query","name":"limit","schema":{"default":10,"type":"integer","minimum":1,"maximum":100},"description":"Maximum namespaces to return per page"}],"x-codeSamples":[{"lang":"typescript","label":"TypeScript SDK","source":"import { Supermemory } from \"supermemory\";\n\nconst client = new Supermemory(); // reads SUPERMEMORY_API_KEY\n\nconst { namespaces, pagination } = await client.namespaces.list({ page: 1, limit: 50 });\nfor (const ns of namespaces) console.log(ns.namespace, ns.documentCount, ns.memoryCount);\nconsole.log(pagination.totalPages);"},{"lang":"python","label":"Python SDK","source":"from supermemory import Supermemory\n\nclient = Supermemory()  # reads SUPERMEMORY_API_KEY\n\npage = client.namespaces.list(page=1, limit=50)\nfor ns in page.namespaces:\n    print(ns.namespace, ns.document_count, ns.memory_count)\nprint(page.pagination.total_pages)"},{"lang":"bash","label":"cURL","source":"curl \"https://api.supermemory.ai/ns?page=1&limit=50\" \\\n  -H \"Authorization: Bearer $SUPERMEMORY_API_KEY\""}]}},"/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":{"description":"Background that helps Supermemory interpret documents and form better memories in this namespace","type":["string","null"]},"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":{"example":"user_alex","type":"string","maxLength":100,"pattern":"^[a-zA-Z0-9_:-]+$"},"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."}],"x-codeSamples":[{"lang":"typescript","label":"TypeScript SDK","source":"import { Supermemory } from \"supermemory\";\n\nconst client = new Supermemory(); // reads SUPERMEMORY_API_KEY\n\nconst ns = await client.namespaces.get(\"user_123\");\nconsole.log(ns.supportingContext, ns.system.createdAt);"},{"lang":"python","label":"Python SDK","source":"from supermemory import Supermemory\n\nclient = Supermemory()  # reads SUPERMEMORY_API_KEY\n\nns = client.namespaces.get(\"user_123\")\nprint(ns.supporting_context, ns.system.created_at)"},{"lang":"bash","label":"cURL","source":"curl \"https://api.supermemory.ai/ns/user_123\" \\\n  -H \"Authorization: Bearer $SUPERMEMORY_API_KEY\""}]},"patch":{"operationId":"patchNsByNamespace","parameters":[{"in":"path","name":"namespace","schema":{"example":"user_alex","type":"string","maxLength":100,"pattern":"^[a-zA-Z0-9_:-]+$"},"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":{"description":"Background that helps Supermemory interpret documents and form better memories in this namespace","type":["string","null"]},"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"],"x-codeSamples":[{"lang":"typescript","label":"TypeScript SDK","source":"import { Supermemory } from \"supermemory\";\n\nconst client = new Supermemory(); // reads SUPERMEMORY_API_KEY\n\nawait client.namespaces.update(\"user_123\", {\n  supportingContext: \"A paying customer on the Pro plan; prefers concise answers.\",\n});"},{"lang":"python","label":"Python SDK","source":"from supermemory import Supermemory\n\nclient = Supermemory()  # reads SUPERMEMORY_API_KEY\n\nclient.namespaces.update(\n    \"user_123\",\n    supporting_context=\"A paying customer on the Pro plan; prefers concise answers.\",\n)"},{"lang":"bash","label":"cURL","source":"curl -X PATCH \"https://api.supermemory.ai/ns/user_123\" \\\n  -H \"Authorization: Bearer $SUPERMEMORY_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{ \"supportingContext\": \"A paying customer on the Pro plan; prefers concise answers.\" }'"}]},"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":{"oneOf":[{"type":"object","properties":{"status":{"type":"string","const":"deleted","description":"The namespace and its content are gone"},"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":["status","namespace","deletedDocumentsCount","deletedMemoriesCount"]},{"type":"object","properties":{"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":["status","operationId","namespace","moveTo"]}]}}},"description":"Namespace permanently deleted (status \"deleted\"). A move answers 202 with status \"queued\"."},"202":{"content":{"application/json":{"schema":{"type":"object","properties":{"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":["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":{"example":"user_alex","type":"string","maxLength":100,"pattern":"^[a-zA-Z0-9_:-]+$"},"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."},{"in":"query","name":"moveTo","schema":{"example":"project_archive","type":"string","maxLength":100,"pattern":"^[a-zA-Z0-9_:-]+$"},"description":"Destination namespace that should receive this namespace's content before deletion. Omit to permanently delete the content."}],"x-codeSamples":[{"lang":"typescript","label":"TypeScript SDK","source":"import { Supermemory } from \"supermemory\";\n\nconst client = new Supermemory(); // reads SUPERMEMORY_API_KEY\n\n// Move everything into another namespace instead of deleting: add { moveTo: \"project_main\" }\nconst res = await client.namespaces.delete(\"project_old\");\nconsole.log(res.status); // \"deleted\", or \"queued\" when moving"},{"lang":"python","label":"Python SDK","source":"from supermemory import Supermemory\n\nclient = Supermemory()  # reads SUPERMEMORY_API_KEY\n\n# Move everything into another namespace instead of deleting: add move_to=\"project_main\"\nres = client.namespaces.delete(\"project_old\")\nprint(res.status)  # \"deleted\", or \"queued\" when moving"},{"lang":"bash","label":"cURL","source":"curl -X DELETE \"https://api.supermemory.ai/ns/project_old?moveTo=project_main\" \\\n  -H \"Authorization: Bearer $SUPERMEMORY_API_KEY\""}]}},"/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":{"description":"Shared background that helps Supermemory interpret content consistently across every namespace","type":["string","null"]},"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"],"x-codeSamples":[{"lang":"typescript","label":"TypeScript SDK","source":"import { Supermemory } from \"supermemory\";\n\nconst client = new Supermemory(); // reads SUPERMEMORY_API_KEY\n\nconst org = await client.organization.get();\nconsole.log(org.organizationalContext, org.namespaceCount);"},{"lang":"python","label":"Python SDK","source":"from supermemory import Supermemory\n\nclient = Supermemory()  # reads SUPERMEMORY_API_KEY\n\norg = client.organization.get()\nprint(org.organizational_context, org.namespace_count)"},{"lang":"bash","label":"cURL","source":"curl \"https://api.supermemory.ai/organization\" \\\n  -H \"Authorization: Bearer $SUPERMEMORY_API_KEY\""}]},"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":{"description":"Shared background that helps Supermemory interpret content consistently across every namespace","type":["string","null"]},"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"],"x-codeSamples":[{"lang":"typescript","label":"TypeScript SDK","source":"import { Supermemory } from \"supermemory\";\n\nconst client = new Supermemory(); // reads SUPERMEMORY_API_KEY\n\nawait client.organization.update({\n  organizationalContext: \"Acme sells billing software to dental clinics.\",\n});"},{"lang":"python","label":"Python SDK","source":"from supermemory import Supermemory\n\nclient = Supermemory()  # reads SUPERMEMORY_API_KEY\n\nclient.organization.update(\n    organizational_context=\"Acme sells billing software to dental clinics.\",\n)"},{"lang":"bash","label":"cURL","source":"curl -X PATCH \"https://api.supermemory.ai/organization\" \\\n  -H \"Authorization: Bearer $SUPERMEMORY_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{ \"organizationalContext\": \"Acme sells billing software to dental clinics.\" }'"}]}},"/ns/{namespace}/memories/{id}":{"get":{"operationId":"getNsByNamespaceMemoriesById","description":"Retrieve one memory by ID. Optionally include its versions (up to three steps away, nearest first), its direct extends and derives links, up to relatedLimit each, and its source document.","responses":{"200":{"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","description":"Stable memory identifier"},"memory":{"type":"string","description":"Learned fact or context extracted from the document"},"metadata":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{},"description":"Memory metadata, including temporal context; empty object when none"},"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"},"included":{"description":"Requested extras","type":"object","properties":{"related":{"description":"Present when include has related","type":"object","properties":{"parents":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Related memory ID"},"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","type":["number","null"]},"memory":{"type":"string","description":"Related learned fact or context"},"metadata":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{},"description":"Public metadata associated with the related memory"},"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"},"document":{"description":"Source document; present when include has both related and documents","type":"object","properties":{"id":{"type":"string","description":"Source document identifier"},"title":{"description":"Source document title","type":["string","null"]},"type":{"description":"Detected source or content type","type":["string","null"]},"metadata":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{},"description":"Public metadata attached to the source document"},"summary":{"description":"Generated summary of the source document","type":["string","null"]},"system":{"type":"object","properties":{"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":["createdAt","updatedAt"],"description":"Lifecycle timestamps maintained by Supermemory"}},"required":["id","title","type","metadata","summary","system"]}},"required":["id","relation","memory","metadata","system"]},"description":"Earlier versions this memory updates"},"children":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Related memory ID"},"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","type":["number","null"]},"memory":{"type":"string","description":"Related learned fact or context"},"metadata":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{},"description":"Public metadata associated with the related memory"},"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"},"document":{"description":"Source document; present when include has both related and documents","type":"object","properties":{"id":{"type":"string","description":"Source document identifier"},"title":{"description":"Source document title","type":["string","null"]},"type":{"description":"Detected source or content type","type":["string","null"]},"metadata":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{},"description":"Public metadata attached to the source document"},"summary":{"description":"Generated summary of the source document","type":["string","null"]},"system":{"type":"object","properties":{"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":["createdAt","updatedAt"],"description":"Lifecycle timestamps maintained by Supermemory"}},"required":["id","title","type","metadata","summary","system"]}},"required":["id","relation","memory","metadata","system"]},"description":"Newer versions that update this memory"},"siblings":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Related memory ID"},"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","type":["number","null"]},"memory":{"type":"string","description":"Related learned fact or context"},"metadata":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{},"description":"Public metadata associated with the related memory"},"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"},"document":{"description":"Source document; present when include has both related and documents","type":"object","properties":{"id":{"type":"string","description":"Source document identifier"},"title":{"description":"Source document title","type":["string","null"]},"type":{"description":"Detected source or content type","type":["string","null"]},"metadata":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{},"description":"Public metadata attached to the source document"},"summary":{"description":"Generated summary of the source document","type":["string","null"]},"system":{"type":"object","properties":{"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":["createdAt","updatedAt"],"description":"Lifecycle timestamps maintained by Supermemory"}},"required":["id","title","type","metadata","summary","system"]}},"required":["id","relation","memory","metadata","system"]},"description":"Memories connected by extends or derives"}},"required":["parents","children","siblings"]},"document":{"description":"Source document; present when include has documents and one exists","type":"object","properties":{"id":{"type":"string","description":"Source document identifier"},"title":{"description":"Source document title","type":["string","null"]},"type":{"description":"Detected source or content type","type":["string","null"]},"metadata":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{},"description":"Public metadata attached to the source document"},"summary":{"description":"Generated summary of the source document","type":["string","null"]},"system":{"type":"object","properties":{"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":["createdAt","updatedAt"],"description":"Lifecycle timestamps maintained by Supermemory"}},"required":["id","title","type","metadata","summary","system"]}}}},"required":["id","memory","metadata","isStatic","isInference","isLatest","isForgotten","version","system"]}}},"description":"Memory retrieved"},"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":"Memory not found"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Server error"}},"summary":"Get memory","tags":["Content Management"],"parameters":[{"in":"path","name":"namespace","schema":{"example":"user_alex","type":"string","maxLength":100,"pattern":"^[a-zA-Z0-9_:-]+$"},"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."},{"in":"path","name":"id","schema":{"type":"string","minLength":1,"example":"mem_abc123"},"required":true,"description":"Memory identifier"},{"in":"query","name":"include","schema":{"type":"array","items":{"type":"string","enum":["related","documents"]},"style":"form","explode":false},"description":"Comma-separated extras. related: the memory's version history and connected memories. documents: the source document, also attached to each related memory when both are requested."},{"in":"query","name":"relatedLimit","schema":{"default":10,"type":"integer","minimum":1,"maximum":100},"description":"Maximum parents, children and siblings to return, applied to each list separately. Parents and children are earlier and later versions up to three steps away, nearest first; siblings are direct extends or derives links."}],"x-codeSamples":[{"lang":"typescript","label":"TypeScript SDK","source":"import { Supermemory } from \"supermemory\";\n\nconst client = new Supermemory(); // reads SUPERMEMORY_API_KEY\n\nconst memory = await client.memories.get(\"user_123\", \"mem_abc123\", {\n  include: [\"related\", \"documents\"],\n});\nconsole.log(memory.memory, memory.isLatest);"},{"lang":"python","label":"Python SDK","source":"from supermemory import Supermemory\n\nclient = Supermemory()  # reads SUPERMEMORY_API_KEY\n\nmemory = client.memories.get(\"user_123\", \"mem_abc123\", include=[\"related\", \"documents\"])\nprint(memory.memory, memory.is_latest)"},{"lang":"bash","label":"cURL","source":"curl \"https://api.supermemory.ai/ns/user_123/memories/mem_abc123?include=related,documents\" \\\n  -H \"Authorization: Bearer $SUPERMEMORY_API_KEY\""}]}}}}