API Reference

Client

Copy Markdown

Open in Claude

Open in ChatGPT

Open in Cursor

---

Copy Markdown

View as Markdown

Get user profile

POST/v4/profile

Get user profile with optional search results

Body ParametersJSONExpand Collapse

containerTag: string

Tag to filter the profile by. This can be an ID for your user, a project ID, or any other identifier you wish to use to filter memories.

buckets: optional array of string

Specific bucket keys to return. Omit to return all configured buckets. Only relevant when “buckets” is included.

filters: optional object { OR } or object { AND }

Optional metadata filters to apply to profile results and search results. Supports complex AND/OR queries with multiple conditions.

One of the following:

Or object { OR }

OR: array of object { key, value, filterType, 3 more } or object { OR } or object { AND }

Array of OR filter expressions

One of the following:

FilterCondition object { key, value, filterType, 3 more }

A single filter condition based on metadata, numeric values, array contents, or string matching

key: string

value: string

filterType: optional "metadata" or "numeric" or "array_contains" or "string_contains"

One of the following:

"metadata"

"numeric"

"array_contains"

"string_contains"

ignoreCase: optional boolean or "true" or "false"

One of the following:

boolean

"true" or "false"

One of the following:

"true"

"false"

negate: optional boolean or "true" or "false"

One of the following:

boolean

"true" or "false"

One of the following:

"true"

"false"

numericOperator: optional ">" or "<" or ">=" or 2 more

One of the following:

">"

"<"

">="

"<="

"="

Or object { OR }

OR: array of unknown

OR: Array of conditions or nested expressions

And object { AND }

AND: array of unknown

AND: Array of conditions or nested expressions

And object { AND }

AND: array of object { key, value, filterType, 3 more } or object { OR } or object { AND }

Array of AND filter expressions

One of the following:

FilterCondition object { key, value, filterType, 3 more }

A single filter condition based on metadata, numeric values, array contents, or string matching

key: string

value: string

filterType: optional "metadata" or "numeric" or "array_contains" or "string_contains"

One of the following:

"metadata"

"numeric"

"array_contains"

"string_contains"

ignoreCase: optional boolean or "true" or "false"

One of the following:

boolean

"true" or "false"

One of the following:

"true"

"false"

negate: optional boolean or "true" or "false"

One of the following:

boolean

"true" or "false"

One of the following:

"true"

"false"

numericOperator: optional ">" or "<" or ">=" or 2 more

One of the following:

">"

"<"

">="

"<="

"="

Or object { OR }

OR: array of unknown

OR: Array of conditions or nested expressions

And object { AND }

AND: array of unknown

AND: Array of conditions or nested expressions

include: optional array of "static" or "dynamic" or "buckets"

Profile sections to return. Omit to return all sections. Pass a subset to reduce payload — e.g. [“buckets”] skips static and dynamic entirely.

One of the following:

"static"

"dynamic"

"buckets"

q: optional string

Optional search query to include search results in the response

threshold: optional number

Threshold for search results. Only results with a score above this threshold will be included.

minimum0

maximum1

ReturnsExpand Collapse

profile: object { buckets, dynamic, static }

buckets: optional map[array of string]

Per-bucket memory lists, keyed by bucket key

dynamic: optional array of string

Dynamic profile information (recent memories)

static: optional array of string

Static profile information that remains relevant long-term

searchResults: optional object { results, timing, total }

Search results if a search query was provided

results: array of object { id, metadata, similarity, 10 more }

Search results for the provided query

id: string

Memory entry ID or chunk ID

metadata: map[unknown]

Memory metadata

similarity: number

Similarity score between the query and memory entry

maximum1

minimum0

updatedAt: string

Memory last update date

formatdatetime

chunk: optional string

The chunk content (only present for chunk results from hybrid search)

chunks: optional array of object { content, documentId, position }

Relevant chunks from associated documents (only included when chunks=true)

content: string

Content of the chunk

documentId: string

ID of the document this chunk belongs to

position: number

Position of chunk in the document (0-indexed)

context: optional object { children, parents, related }

Object containing version history (parents/children via updates) and related memories (extends/derives)

children: optional array of object { memory, relation, updatedAt, 2 more }

memory: string

The contextual memory content

relation: "updates" or "extends" or "derives"

Relation type between this memory and its parent/child

One of the following:

"updates"

"extends"

"derives"

updatedAt: string

Contextual memory last update date

formatdatetime

metadata: optional map[unknown]

Contextual memory metadata

version: optional number

Relative version distance from the primary memory (+1 for direct child, +2 for grand-child, etc.)

parents: optional array of object { memory, relation, updatedAt, 2 more }

memory: string

The contextual memory content

relation: "updates" or "extends" or "derives"

Relation type between this memory and its parent/child

One of the following:

"updates"

"extends"

"derives"

updatedAt: string

Contextual memory last update date

formatdatetime

metadata: optional map[unknown]

Contextual memory metadata

version: optional number

Relative version distance from the primary memory (-1 for direct parent, -2 for grand-parent, etc.)

related: optional array of object { memory, relation, updatedAt, metadata }

memory: string

The related memory content

relation: "extends" or "derives"

Relation type

One of the following:

"extends"

"derives"

updatedAt: string

Related memory last update date

metadata: optional map[unknown]

Related memory metadata

documents: optional array of object { id, createdAt, updatedAt, 4 more }

Associated documents for this memory entry

id: string

Document ID

createdAt: string

Document creation date

formatdatetime

updatedAt: string

Document last update date

formatdatetime

metadata: optional map[unknown]

Document metadata (only included when documents=true)

summary: optional string

Document summary (only included when summaries=true)

title: optional string

Document title (only included when documents=true)

type: optional string

Document type (only included when documents=true)

filepath: optional string

Filepath of the source document this memory or chunk came from

isAggregated: optional boolean

Indicates if this memory was created by aggregating multiple source memories

memory: optional string

The memory content (only present for memory results)

rootMemoryId: optional string

ID of the root (first version) memory entry this one descends from. Null for memories that have never been superseded. Only present on memory results, not on standalone chunk results.

version: optional number

Version number of this memory entry

timing: number

Search timing in milliseconds

total: number

Total number of search results

Get user profile

HTTP

HTTP

TypeScript

Python

curl https://api.supermemory.ai/v4/profile \
    -H 'Content-Type: application/json' \
    -H "Authorization: Bearer $SUPERMEMORY_API_KEY" \
    -d '{
          "containerTag": "containerTag"
        }'

200 example

{
  "profile": {
    "buckets": {
      "foo": [
        "string"
      ]
    },
    "dynamic": [
      "string"
    ],
    "static": [
      "string"
    ]
  },
  "searchResults": {
    "results": [
      {
        "id": "mem_abc123",
        "metadata": {
          "source": "bar",
          "confidence": "bar"
        },
        "similarity": 0.89,
        "updatedAt": "updatedAt",
        "chunk": "This is a chunk of content from a document...",
        "chunks": [
          {
            "content": "This is a chunk of content from the document...",
            "documentId": "doc_xyz789",
            "position": 0
          }
        ],
        "context": {
          "children": [
            {
              "memory": "Later version: API rate limit increased to 100 req/min on the free tier.",
              "relation": "extends",
              "updatedAt": "updatedAt",
              "metadata": {
                "foo": "bar"
              },
              "version": 1
            }
          ],
          "parents": [
            {
              "memory": "Earlier version: API rate limit is 50 req/min on the free tier.",
              "relation": "updates",
              "updatedAt": "updatedAt",
              "metadata": {
                "foo": "bar"
              },
              "version": -1
            }
          ],
          "related": [
            {
              "memory": "memory",
              "relation": "extends",
              "updatedAt": "updatedAt",
              "metadata": {
                "foo": "bar"
              }
            }
          ]
        },
        "documents": [
          {
            "id": "doc_xyz789",
            "createdAt": "createdAt",
            "updatedAt": "updatedAt",
            "metadata": {
              "source": "bar",
              "language": "bar"
            },
            "summary": "API rate limit policy: 100 req/min free, 1000 req/min pro.",
            "title": "API Rate Limiting Policy",
            "type": "web"
          }
        ],
        "filepath": "filepath",
        "isAggregated": false,
        "memory": "The user prefers detailed API responses over minimal ones.",
        "rootMemoryId": "mem_abc123",
        "version": 3
      }
    ],
    "timing": 0,
    "total": 0
  }
}

Returns Examples

200 example

{
  "profile": {
    "buckets": {
      "foo": [
        "string"
      ]
    },
    "dynamic": [
      "string"
    ],
    "static": [
      "string"
    ]
  },
  "searchResults": {
    "results": [
      {
        "id": "mem_abc123",
        "metadata": {
          "source": "bar",
          "confidence": "bar"
        },
        "similarity": 0.89,
        "updatedAt": "updatedAt",
        "chunk": "This is a chunk of content from a document...",
        "chunks": [
          {
            "content": "This is a chunk of content from the document...",
            "documentId": "doc_xyz789",
            "position": 0
          }
        ],
        "context": {
          "children": [
            {
              "memory": "Later version: API rate limit increased to 100 req/min on the free tier.",
              "relation": "extends",
              "updatedAt": "updatedAt",
              "metadata": {
                "foo": "bar"
              },
              "version": 1
            }
          ],
          "parents": [
            {
              "memory": "Earlier version: API rate limit is 50 req/min on the free tier.",
              "relation": "updates",
              "updatedAt": "updatedAt",
              "metadata": {
                "foo": "bar"
              },
              "version": -1
            }
          ],
          "related": [
            {
              "memory": "memory",
              "relation": "extends",
              "updatedAt": "updatedAt",
              "metadata": {
                "foo": "bar"
              }
            }
          ]
        },
        "documents": [
          {
            "id": "doc_xyz789",
            "createdAt": "createdAt",
            "updatedAt": "updatedAt",
            "metadata": {
              "source": "bar",
              "language": "bar"
            },
            "summary": "API rate limit policy: 100 req/min free, 1000 req/min pro.",
            "title": "API Rate Limiting Policy",
            "type": "web"
          }
        ],
        "filepath": "filepath",
        "isAggregated": false,
        "memory": "The user prefers detailed API responses over minimal ones.",
        "rootMemoryId": "mem_abc123",
        "version": 3
      }
    ],
    "timing": 0,
    "total": 0
  }
}