Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.memanto.ai/llms.txt

Use this file to discover all available pages before exploring further.

​
Authentication

Memanto uses a two-header authentication system: Moorcheh API key for all requests, and session tokens for memory operations.

All Requests

Uses Moorcheh API Key in the Authorization header. Required for every API call.
Authorization: Bearer your_api_key

Memory Operations

Uses Session Token in the X-Session-Token header. Required only for memory endpoints.
X-Session-Token: your_jwt_token

​
API Key Authentication

​
Required Header

Every request to Memanto API must include: 
Authorization: Bearer your_api_key_here

​
Getting Your API Key

  1. Go to https://console.moorcheh.ai/api-keys
  2. Create a new API key
  3. Copy the full key value
  4. Use in Authorization header

​
Example Request

curl -X GET "http://localhost:8000/api/v2/agents" \
  -H "Authorization: Bearer your_api_key"

​
In Python

import httpx

api_key = "your_api_key"
headers = {"Authorization": f"Bearer {api_key}"}

response = httpx.get(
    "http://localhost:8000/api/v2/agents",
    headers=headers
)

​
Session Token Authentication

​
When Session Tokens Are Required

Memory operations require a session token from agent activation:
  • POST /api/v2/agents/{agent_id}/remember
  • GET /api/v2/agents/{agent_id}/recall
  • POST /api/v2/agents/{agent_id}/answer
  • GET /api/v2/session/current
  • POST /api/v2/session/extend
  • POST /api/v2/agents/{agent_id}/deactivate
  • All temporal queries
  • All memory management endpoints

​
Getting a Session Token

  1. Activate an agent:
curl -X POST "http://localhost:8000/api/v2/agents/my-agent/activate" \
  -H "Authorization: Bearer your_api_key"
  1. Response contains session token:
{
  "session_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "agent_id": "my-agent",
  "expires_at": "2025-03-31T22:30:00Z"
}
  1. Use token in subsequent requests:
X-Session-Token: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

​
Example Request with Session Token

curl -X POST "http://localhost:8000/api/v2/agents/my-agent/remember" \
  -H "Authorization: Bearer your_api_key" \
  -H "X-Session-Token: eyJhbGc..." \
  -d '{"content": "Hello", "type": "fact"}'

​
In Python

import httpx

api_key = "your_api_key"

# 1. Activate to get session token
activate_resp = httpx.post(
    "http://localhost:8000/api/v2/agents/my-agent/activate",
    headers={"Authorization": f"Bearer {api_key}"}
)
session_token = activate_resp.json()["session_token"]

# 2. Use session token for memory operations
headers = {
    "Authorization": f"Bearer {api_key}",
    "X-Session-Token": session_token
}

remember_resp = httpx.post(
    "http://localhost:8000/api/v2/agents/my-agent/remember",
    params={"memory_type": "fact"},
    json={"content": "Hello"},
    headers=headers
)

​
Endpoints Not Requiring Session Token

These endpoints only need API key:
  • POST /api/v2/agents - Create agent
  • GET /api/v2/agents - List agents
  • GET /api/v2/agents/{agent_id} - Get agent details
  • DELETE /api/v2/agents/{agent_id} - Delete agent
  • POST /api/v2/agents/{agent_id}/activate - Activate (returns token)

​
Session Token Details

​
Token Format

Session tokens are JWT (JSON Web Tokens): 
eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.
eyJhZ2VudF9pZCI6Im15LWFnZW50IiwiZXhwaXJlc19hdCI6IjIwMjUtMDMtMzFUMjI6MzA6MDBaIn0.
[signature]

​
Token Expiration

  • Duration: 6 hours from activation
  • Checking expiry: Decode token to see expires_at
  • Extending: Use POST /api/v2/session/extend
  • Renewal: Activate a new session with POST /api/v2/agents/{agent_id}/activate

​
Decode Token (Python)

import jwt

token = "eyJhbGc..."

payload = jwt.decode(
    token,
    options={"verify_signature": False}  # Don't verify signature
)

print(f"Agent: {payload['agent_id']}")
print(f"Expires: {payload['expires_at']}")

​
Error: Invalid API Key

​
Symptom

{
  "status": "error",
  "error": {
    "code": "INVALID_API_KEY",
    "message": "API key is invalid or expired"
  }
}

​
Solutions

  1. Check API key value and ensure it is copied completely
  2. Verify key hasn’t been rotated in Moorcheh Console
  3. Ensure no typos in header value
  4. Generate new key if needed

​
Error: Missing Session Token

​
Symptom

{
  "status": "error",
  "error": {
    "code": "MISSING_SESSION_TOKEN",
    "message": "X-Session-Token header is required"
  }
}

​
Solutions

  1. Activate agent first: POST /api/v2/agents/{agent_id}/activate
  2. Save the returned session_token
  3. Include token in X-Session-Token header

​
Error: Expired Session Token

​
Symptom

{
  "status": "error",
  "error": {
    "code": "EXPIRED_SESSION_TOKEN",
    "message": "Session token has expired"
  }
}

​
Solutions

  1. Extend existing session: POST /api/v2/session/extend
  2. Or activate new session: POST /api/v2/agents/{agent_id}/activate

​
Best Practices

​
DO

  • Store API key in environment variable
  • Use secrets manager for production
  • Keep session tokens in memory (don’t persist)
  • Extend sessions before expiry
  • Rotate API keys periodically

​
DON’T

  • Commit API keys to git
  • Hardcode keys in code
  • Share API keys
  • Use same key across environments
  • Log tokens to files

​
Security

​
API Key Management

Development: 
export MOORCHEH_API_KEY=dev_key
Production (AWS Secrets Manager): 
import boto3

client = boto3.client('secretsmanager')
secret = client.get_secret_value(SecretId='memanto/api-key')
api_key = secret['SecretString']
Production (Environment): 
# In deployment platform
MOORCHEH_API_KEY=prod_key

​
Session Token Security

  • Tokens are JWT - treat as sensitive
  • Don’t log tokens
  • Don’t expose in client code
  • Short-lived (6 hours)
  • Unique per activation

​
Next Steps