Complete reference for the Memos REST API including endpoints, authentication, and examples.

REST API Reference

The Memos REST API provides programmatic access to all functionality available in the web interface. Use the API to integrate Memos with other tools, automate workflows, or build custom applications.

Base URL and Versioning

Base URL: https://your-memos-instance.com/api/v1/
Version: v1 (current)

All API endpoints are prefixed with /api/v1/ and return JSON responses.

Authentication

See the API Authentication guide for detailed authentication information.

Quick Start

# Get your access token from the web interface
export MEMOS_TOKEN="your-access-token"
export MEMOS_HOST="https://your-memos-instance.com"

# Test authentication
curl -H "Authorization: Bearer $MEMOS_TOKEN" \
     "$MEMOS_HOST/api/v1/auth/status"

Memos Endpoints

List Memos

Get a list of memos with optional filtering.

GET /api/v1/memos

Query Parameters

Parameter	Type	Description	Default
`page`	integer	Page number (1-based)	`1`
`limit`	integer	Results per page (1-100)	`20`
`tag`	string	Filter by tag	-
`visibility`	string	`private`, `protected`, `public`	`all`
`orderBy`	string	`created_ts`, `updated_ts`, `pinned`	`created_ts`
`order`	string	`asc`, `desc`	`desc`

Example Request

curl -H "Authorization: Bearer $MEMOS_TOKEN" \
     "$MEMOS_HOST/api/v1/memos?tag=work&limit=10"

Example Response

{
  "data": [
    {
      "id": 123,
      "name": "memos/123",
      "uid": "1a2b3c4d",
      "rowStatus": "NORMAL",
      "creator": "users/1",
      "createTime": "2025-08-19T10:00:00Z",
      "updateTime": "2025-08-19T11:30:00Z",
      "displayTime": "2025-08-19T10:00:00Z",
      "content": "# Meeting Notes\n\nDiscussed project timeline and deliverables.\n\n#work #meeting",
      "visibility": "PRIVATE",
      "pinned": false,
      "resources": [],
      "relations": [],
      "tags": ["work", "meeting"]
    }
  ],
  "nextPageToken": "eyJpZCI6MTIzfQ=="
}

Create Memo

Create a new memo.

POST /api/v1/memos

Request Body

{
  "content": "string",
  "visibility": "PRIVATE|PROTECTED|PUBLIC"
}

Example Request

curl -X POST \
     -H "Authorization: Bearer $MEMOS_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{
       "content": "# Daily Standup\n\n- Completed: User authentication\n- Working on: API documentation\n- Blocked: None\n\n#daily #work",
       "visibility": "PRIVATE"
     }' \
     "$MEMOS_HOST/api/v1/memos"

Example Response

{
  "id": 124,
  "name": "memos/124",
  "uid": "2b3c4d5e",
  "rowStatus": "NORMAL",
  "creator": "users/1",
  "createTime": "2025-08-19T12:00:00Z",
  "updateTime": "2025-08-19T12:00:00Z",
  "displayTime": "2025-08-19T12:00:00Z",
  "content": "# Daily Standup\n\n- Completed: User authentication\n- Working on: API documentation\n- Blocked: None\n\n#daily #work",
  "visibility": "PRIVATE",
  "pinned": false,
  "resources": [],
  "relations": [],
  "tags": ["daily", "work"]
}

Get Memo

Retrieve a specific memo by ID.

GET /api/v1/memos/{id}

Example Request

curl -H "Authorization: Bearer $MEMOS_TOKEN" \
     "$MEMOS_HOST/api/v1/memos/123"

Update Memo

Update an existing memo.

PATCH /api/v1/memos/{id}

Request Body

{
  "content": "string",
  "visibility": "PRIVATE|PROTECTED|PUBLIC",
  "pinned": boolean
}

Example Request

curl -X PATCH \
     -H "Authorization: Bearer $MEMOS_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{
       "content": "# Updated Meeting Notes\n\n## Action Items\n- [ ] Review design mockups\n- [ ] Schedule follow-up meeting\n\n#work #meeting #action-items",
       "pinned": true
     }' \
     "$MEMOS_HOST/api/v1/memos/123"

Delete Memo

Delete a memo (moves to trash).

DELETE /api/v1/memos/{id}

Example Request

curl -X DELETE \
     -H "Authorization: Bearer $MEMOS_TOKEN" \
     "$MEMOS_HOST/api/v1/memos/123"

Resources (File Attachments)

Upload Resource

Upload a file attachment.

POST /api/v1/resources

Request

Use multipart/form-data with the file in a file field.

Example Request

curl -X POST \
     -H "Authorization: Bearer $MEMOS_TOKEN" \
     -F "file=@screenshot.png" \
     "$MEMOS_HOST/api/v1/resources"

Example Response

{
  "id": 456,
  "name": "resources/456",
  "uid": "3c4d5e6f",
  "createTime": "2025-08-19T12:30:00Z",
  "filename": "screenshot.png",
  "type": "image/png",
  "size": 102400,
  "linkedMemos": []
}

List Resources

Get uploaded resources.

GET /api/v1/resources

Query Parameters

Parameter	Type	Description	Default
`page`	integer	Page number	`1`
`limit`	integer	Results per page	`20`

Get Resource

Download a specific resource.

GET /api/v1/resources/{id}

Delete Resource

Delete an uploaded resource.

DELETE /api/v1/resources/{id}

User Management

Get Current User

Get information about the authenticated user.

GET /api/v1/auth/status

Example Response

{
  "user": {
    "id": 1,
    "name": "users/1",
    "username": "admin",
    "role": "HOST",
    "email": "admin@example.com",
    "nickname": "Administrator",
    "avatarUrl": "",
    "createTime": "2025-01-01T00:00:00Z",
    "updateTime": "2025-08-19T10:00:00Z"
  }
}

Update User

Update user profile information.

PATCH /api/v1/users/{username}

Request Body

{
  "nickname": "string",
  "email": "string",
  "avatarUrl": "string"
}

Search

Search Memos

Search memos by content and metadata.

GET /api/v1/search

Query Parameters

Parameter	Type	Description
`q`	string	Search query
`limit`	integer	Results limit
`tag`	string	Filter by tag

Example Request

curl -H "Authorization: Bearer $MEMOS_TOKEN" \
     "$MEMOS_HOST/api/v1/search?q=meeting%20notes&tag=work"

System Information

Get System Info

Get system information and statistics.

GET /api/v1/system/info

Example Response

{
  "version": "0.24.0",
  "mode": "prod",
  "allowSignUp": false,
  "disablePasswordLogin": false,
  "additionalScript": "",
  "customizedProfile": {
    "title": "Memos",
    "description": "A privacy-first, lightweight note-taking service",
    "logoUrl": "",
    "locale": "en"
  }
}

Webhooks

List Webhooks

Get configured webhooks.

GET /api/v1/webhooks

Create Webhook

Create a new webhook.

POST /api/v1/webhooks

Request Body

{
  "name": "string",
  "url": "string",
  "events": ["memo.created", "memo.updated", "memo.deleted"]
}

Error Handling

The API uses standard HTTP status codes and returns error details in JSON format.

Error Response Format

{
  "error": {
    "code": "INVALID_ARGUMENT",
    "message": "Invalid request parameters",
    "details": [
      {
        "field": "content",
        "issue": "Content cannot be empty"
      }
    ]
  }
}

Common Error Codes

Status	Code	Description
400	`INVALID_ARGUMENT`	Invalid request parameters
401	`UNAUTHENTICATED`	Missing or invalid authentication
403	`PERMISSION_DENIED`	Insufficient permissions
404	`NOT_FOUND`	Resource not found
409	`ALREADY_EXISTS`	Resource already exists
429	`RESOURCE_EXHAUSTED`	Rate limit exceeded
500	`INTERNAL_ERROR`	Server error

Rate Limiting

API requests are subject to rate limiting:

Authenticated requests: 1000 requests per hour
Unauthenticated requests: 100 requests per hour

Rate limit information is included in response headers:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1692448800

Rate Limits: When you hit rate limits, the API returns a 429 Too Many Requests status. Implement exponential backoff in your applications.

SDK and Libraries

Official Libraries

Currently, no official SDKs are available, but the API follows REST conventions making it easy to integrate with any HTTP client.

Community Libraries

JavaScript/Node.js: Community libraries available on npm
Python: REST client libraries
Go: HTTP client implementations
Curl: All examples in this documentation work with curl

Example Integration (JavaScript)

class MemosAPI {
  constructor(baseURL, token) {
    this.baseURL = baseURL;
    this.token = token;
  }

  async request(method, endpoint, data = null) {
    const response = await fetch(`${this.baseURL}${endpoint}`, {
      method,
      headers: {
        'Authorization': `Bearer ${this.token}`,
        'Content-Type': 'application/json',
      },
      body: data ? JSON.stringify(data) : null,
    });

    if (!response.ok) {
      throw new Error(`API error: ${response.statusText}`);
    }

    return response.json();
  }

  async createMemo(content, visibility = 'PRIVATE') {
    return this.request('POST', '/api/v1/memos', {
      content,
      visibility,
    });
  }

  async getMemos(params = {}) {
    const query = new URLSearchParams(params);
    return this.request('GET', `/api/v1/memos?${query}`);
  }
}

// Usage
const api = new MemosAPI('https://memos.example.com', 'your-token');
const memo = await api.createMemo('# API Test\n\nTesting API integration!');

Best Practices

Authentication Security

Store tokens securely - Never expose tokens in client-side code
Use environment variables for API credentials
Rotate tokens regularly for security
Implement token refresh if using short-lived tokens

Performance Optimization

Use pagination for large datasets
Cache responses when appropriate
Batch operations when possible
Implement retry logic with exponential backoff

Error Handling

async function safeAPICall(apiFunction) {
  try {
    return await apiFunction();
  } catch (error) {
    if (error.status === 429) {
      // Rate limited - wait and retry
      await sleep(60000);
      return apiFunction();
    } else if (error.status === 401) {
      // Unauthorized - refresh token
      await refreshToken();
      return apiFunction();
    } else {
      // Log error and handle appropriately
      console.error('API Error:', error);
      throw error;
    }
  }
}

Next Steps

Need help with the API? Check specific endpoint documentation or ask questions in our community discussions.

REST API Reference

On this page