Skip to main content

API Overview

The Memsolus REST API lets you store, search, and manage persistent memory for AI agents and applications. All communication is over HTTPS and all request and response bodies are JSON.

Base URL​

https://api.memsolus.com/v1

Authentication​

All endpoints require an API key passed in the X-Api-Key header:

curl https://api.memsolus.com/v1/memories \
  -H "X-Api-Key: msk_live_..."

Keys prefixed with msk_live_ are production keys. Test keys start with msk_test_.

Getting Your API Key​

1

Sign in to the dashboard

Log in at memsolus.com and navigate to Settings → API Keys.

2

Create a new key

Click New API Key, give it a descriptive name (e.g., production-agent), and select the permission scopes your integration requires.

Use the minimum set of permissions needed — avoid creating keys with full access unless required.

3

Copy and store the key

The key is shown only once immediately after creation. Copy it and store it in a secrets manager or environment variable.

export MEMSOLUS_API_KEY="msk_live_..."

Permissions​

Each API key is scoped to one or more permissions. The API enforces permissions on every request — a key missing the required permission receives 403 Forbidden.

To retrieve the full list of available permissions programmatically:

GET/v1/api-keys/permissions
API Key

List all available permission groups

curl https://api.memsolus.com/v1/api-keys/permissions \
  -H "X-Api-Key: msk_live_..."

Memory​

PermissionDescription
memory.readList, search, and view memories
memory.writeCreate and update memories
memory.deleteDelete individual or all memories

Knowledge​

PermissionDescription
knowledge.readList and view knowledge entries
knowledge.writeCreate and update knowledge entries
knowledge.deleteDelete knowledge entries

Workspace​

PermissionDescription
workspace.readList and view workspaces
workspace.writeCreate workspaces
workspace.deleteDelete workspaces

Export​

PermissionDescription
export.readList and download exports
export.writeCreate export jobs

Dashboard​

PermissionDescription
dashboard.readView statistics, charts, and alerts

Webhooks​

PermissionDescription
webhook.readList webhooks and view delivery history
webhook.writeCreate and update webhooks
webhook.deleteDelete webhooks

Memory Templates​

PermissionDescription
template.readList and view templates
template.writeCreate, edit, and apply templates
template.deleteDelete templates

Ingest​

PermissionDescription
ingest.writeSubmit files and URLs for ingestion
ingest.readList and view ingestion job status

Pagination​

Paginated endpoints accept page and page_size query parameters and return a consistent envelope:

{
  "data": [...],
  "total": 142,
  "page": 1,
  "page_size": 20
}
ParameterDescription
pagePage number, starting at 1 (default: 1)
page_sizeResults per page, max 100
totalTotal number of matching records

Use total and page_size to calculate the number of pages: Math.ceil(total / page_size).

Error Responses​

All errors follow a consistent structure:

{
  "status_code": 404,
  "error": "Not Found",
  "message": "Memory a1b2c3d4 not found",
  "error_code": "MEMORY_NOT_FOUND"
}
FieldDescription
status_codeHTTP status code
errorStandard HTTP status text
messageHuman-readable description of the error
error_codeMachine-readable error identifier for programmatic handling

Common Error Codes​

HTTPError CodeDescription
400VALIDATION_ERRORRequest body or query params failed validation
400PASSWORD_CONFIRMATION_REQUIREDDestructive endpoint requires password confirmation
401UNAUTHORIZEDMissing or invalid API key
403FORBIDDENAPI key lacks the required permission
403WORKSPACE_ACCESS_DENIEDKey does not have access to the specified workspace
404MEMORY_NOT_FOUNDMemory does not exist or belongs to another workspace
404EXPORT_NOT_FOUNDExport job not found
404ENTITY_NOT_FOUNDGraph entity not found
409DUPLICATE_MEMORYMemory with identical content already exists
409DUPLICATE_WEBHOOK_URLA webhook for this URL already exists
409EXPORT_NOT_READYExport is still processing
409MEMORY_NOT_PROMOTABLEMemory cannot be promoted from its current state
410MEMORY_EXPIREDMemory has already expired
410EXPORT_EXPIREDExport file is no longer available
422WEBHOOK_LIMIT_EXCEEDEDPlan webhook limit reached

Request Format​

All requests with a body must include Content-Type: application/json, except for file upload endpoints which use multipart/form-data.

curl -X POST https://api.memsolus.com/v1/memories \
  -H "X-Api-Key: msk_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "memory": "...", "user_id": "user-123" }'