Memories

Add a memory

Changed on

Adds an arbitrary document to the index. This can be any text, email, call transcript, etc. The document will be processed and made available for querying once the processing is complete.

post/memories/add

Request

  • Base URL
    https://api.hyperspell.com
  • URL
    https://api.hyperspell.com/memories/add
  • Auth
    HTTP bearer

Headers

X-As-Userstring nullable

Optionally set this header to act as a specific user when using an API Key, equivalent to first exchanging the API Key for a User Token

Request body

resource_idstring

The resource ID to add the document to. If not provided, a new resource ID will be generated. If provided, the document will be updated if it already exists.

textstring required

Full text of the document.

collectionstring nullable

The collection to add the document to — deprecated, set the collection using metadata instead.

titlestring nullable

Title of the document.

datestring date-time

Date of the document. Depending on the document, this could be the creation date or date the document was last updated (eg. for a chat transcript, this would be the date of the last message). This helps the ranking algorithm and allows you to filter by date range.

metadataobject nullable

Custom metadata for filtering. Keys must be alphanumeric with underscores, max 64 chars. Values must be string, number, boolean, or null.

share'personal' | 'suggest' | 'shared' nullable

Who should see this memory, for a memory written on behalf of a user. personal (the default) keeps it visible to that user only. suggest keeps it personal and asks the user, in their Inbox, whether to share it with everyone in the app. shared shares it with everyone in the app once it is processed, and is only accepted when the app allows direct sharing. A memory written without a user is always visible to everyone in the app, so it accepts suggest and shared and refuses personal.

Example request

{
  "collection": "my-collection",
  "metadata": {
    "author": "John Doe",
    "date": "2025-05-20T02:31:00Z",
    "rating": 3
  },
  "text": "...",
  "title": "My Document"
}

Response

Successful Response

source'reddit' | 'notion' | 'slack' | 'google_calendar' | 'google_mail' | 'imap' | 'google_meet' | 'box' | 'dropbox' | 'github' | 'gitlab' | 'google_drive' | 'vault' | 'web_crawler' | 'trace' | 'microsoft_outlook' | 'microsoft_teams' | 'granola' | 'fathom' | 'fireflies' | 'figma' | 'linear' | 'hubspot' | 'salesforce' | 'coda' | 'confluence' | 'jira' | 'metabase' | 'gong' | 'clickup' | 'lightfield' | 'pylon' | 'fellow' | 'odoo' | 'external_mcp' | 'page' required
resource_idstring required
status'pending' | 'processing' | 'completed' | 'failed' | 'pending_review' | 'skipped' | 'filtered' | 'cancelled' required

Changes