Memories

Upload a file

Changed on

This endpoint will upload a file to the index and return a resource_id. The file will be processed in the background and the memory will be available for querying once the processing is complete. You can use the resource_id to query the memory later, and check the status of the memory.

Supported formats are PDF, Word (.docx, .doc), OpenDocument text, RTF, plain text and Markdown, and spreadsheets as CSV, TSV, or Excel workbooks (.xlsx, .xlsm). Each row of a large spreadsheet is indexed with its column headers.

The examples upload a local notes.txt file for a specific user. Set these environment variables before running them:

  • HYPERSPELL_API_URL: your API base URL, without a trailing slash. Use https://api.hyperspell.com for US apps or https://api.eu.hyperspell.com for EU apps. For a dedicated instance, use its API URL.
  • HYPERSPELL_API_KEY: your API key.
  • HYPERSPELL_USER_ID: the user who should own the uploaded memory.

The X-As-User header selects the user when using an app-wide key. With a user-scoped key, omit this header or set it to that key's user ID.

post/memories/upload

Request

  • Base URL
    https://api.hyperspell.com
  • URL
    https://api.hyperspell.com/memories/upload
  • 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 multipart/form-data

filestring binary required

The file to ingest.

collectionstring nullable

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

metadatastring nullable

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

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

Who should see this memory, for a file uploaded 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 file uploaded without a user is always visible to everyone in the app, so it accepts suggest and shared and refuses personal.

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