API Reference

RESTful API for integrating Memory into your applications. All endpoints require authentication via JWT bearer token.

Endpoints

Authentication
Chat & Queries
Memory Management
Data Sources
Model Configuration

Base URL

https://ai.senuamedia.com/api

Authentication

Authenticate and receive a JWT access token.

Request Body

Field	Type	Description
`username_or_email` required	string	Username or email address
`password` required	string	Account password
`mfa_code`	string	TOTP code if MFA enabled

Response

                {

  "access_token": "eyJhbGciOiJIUzI1NiIs...",

  "token_type": "bearer",

  "expires_in": 86400,

  "user": {

    "id": "545ebe7c-d75f-4f8f-aca5-fc1da58c8d5c",

    "username": "admin",

    "email": "user@example.com",

    "role": "admin"

  }

}

Chat & Queries

Send a message and receive an AI response with personal context.

Headers

Header	Value
`Authorization`	Bearer {access_token}
`Content-Type`	application/json

Request Body

Field	Type	Description
`message` required	string	User message/query
`conversation_id`	string	Continue existing conversation
`model`	string	Override default model
`include_memory`	boolean	Include memory context (default: true)
`stream`	boolean	Stream response tokens

Response

                {

  "id": "msg_abc123",

  "conversation_id": "conv_xyz789",

  "response": "Based on your recent work...",

  "model": "mistral:7b",

  "memory_used": {

    "short_term": 5,

    "long_term": 12,

    "sources": ["email", "github"]

  },

  "tokens": {

    "prompt": 1250,

    "completion": 380

  }

}

Memory Management

Search your memory using semantic similarity.

Query Parameters

Parameter	Type	Description
`q` required	string	Search query
`limit`	integer	Max results (default: 10)
`source`	string	Filter by source type
`from_date`	string	ISO date filter
`to_date`	string	ISO date filter

Response

                {

  "results": [

    {

      "id": "mem_123",

      "content": "Meeting notes from...",

      "source": "notion",

      "similarity": 0.89,

      "timestamp": "2025-01-15T10:30:00Z"

    }

  ],

  "total": 47

}

Get memory statistics and usage metrics.

Response

                {

  "total_memories": 15420,

  "short_term": 48,

  "long_term": 15372,

  "by_source": {

    "email": 5200,

    "github": 3100,

    "notion": 2400,

    "slack": 4720

  },

  "last_sync": "2025-01-15T14:30:00Z"

}

Data Sources

List all connected data sources and their status.

Connect a new data source. Returns OAuth URL for cloud services.

Trigger a sync for a connected data source.

Model Configuration

List available LLM models.

Response

                {

  "models": [

    {

      "id": "mistral:7b",

      "provider": "ollama",

      "size": "4.1GB",

      "status": "ready"

    },

    {

      "id": "claude-3-sonnet",

      "provider": "anthropic",

      "status": "available"

    }

  ],

  "default": "mistral:7b"

}

Error Responses

All errors follow a consistent format:

          {

  "error": {

    "code": "unauthorized",

    "message": "Invalid or expired token",

    "details": {}

  }

}

Status Code	Error Code	Description
400	bad_request	Invalid request parameters
401	unauthorized	Missing or invalid authentication
403	forbidden	Insufficient permissions
404	not_found	Resource not found
429	rate_limited	Too many requests
500	internal_error	Server error

Rate Limits

API requests are rate limited to protect the service:

Chat endpoints: 60 requests/minute
Memory search: 120 requests/minute
Sync operations: 10 requests/minute

OpenAPI Specification

Full OpenAPI 3.0 spec available at /api/openapi.json. Interactive docs at /api/docs (Swagger UI).