Users - Memos

Overview

Users are the people who create and interact with memos. The User API provides endpoints for user management, authentication, settings, and statistics.

List Users

Retrieves a list of all users. Requires admin privileges.

GET /api/v1/users

curl https://your-memos-instance.com/api/v1/users \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Query Parameters

page_size

integer

Maximum number of users to return. Default: 50, Maximum: 1000

page_token

string

Token for retrieving the next page (from previous response)

filter

string

Filter users by criteria. Example: username == "alice"Supported operators: ==Supported fields: username

show_deleted

boolean

Include deleted users in results. Default: false

Response

users

array

Array of user objects

next_page_token

string

Token for the next page. Omitted if no more pages.

total_size

integer

Total count of users (may be approximate)

Error Responses

401

error

Unauthenticated - User not authenticated

403

error

Permission Denied - User is not an admin

Get User

Retrieves a single user by ID or username. Supports both numeric IDs and username strings.

GET /api/v1/users/{user}

curl https://your-memos-instance.com/api/v1/users/alice \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

# Or by numeric ID
curl https://your-memos-instance.com/api/v1/users/101 \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Path Parameters

user

string

required

The user ID (numeric) or username (string). Examples:

users/101 - Get user by ID
users/alice - Get user by username

Response

name

string

The resource name of the user. Format: users/{user_id}

role

string

The user’s role: ADMIN or USER

username

string

Unique username for login

string

Email address (may be empty)

display_name

string

Display name shown in the UI

avatar_url

string

URL to user’s avatar image

description

string

User bio/description

state

string

Account state: NORMAL or ARCHIVED

create_time

timestamp

Account creation timestamp

update_time

timestamp

Last update timestamp

Error Responses

400

error

Invalid Argument - Invalid user name format

404

error

Not Found - User does not exist

Create User

Creates a new user account. The first user created automatically becomes an admin. Subsequent users require admin privileges or enabled registration.

POST /api/v1/users

curl -X POST https://your-memos-instance.com/api/v1/users \
  -H "Content-Type: application/json" \
  -d '{
    "user": {
      "username": "alice",
      "password": "secure_password_123",
      "email": "[email protected]",
      "display_name": "Alice Smith"
    }
  }'

Request Body

user

object

required

The user to create

Show properties

username

string

required

Unique username (1-32 characters, alphanumeric and hyphens only)

password

string

required

User’s password (will be hashed before storage)

string

Email address (optional)

display_name

string

Display name for the user (optional)

role

string

Role to assign. Only settable by admin users:

ADMIN - Full system access
USER - Regular user (default)

user_id

string

Optional custom user ID. Must match pattern [a-z0-9-]+. If not provided, an ID will be generated.

validate_only

boolean

If true, validates the request without creating the user. Default: false

request_id

string

Idempotency token to ensure multiple requests have the same result

User Creation Rules

First User: Automatically becomes an admin (no authentication required)
Admin Users: Can create users with any role
Regular Users: Can only create regular user accounts if registration is enabled
Disabled Registration: Non-admin users cannot create accounts

Response

Returns the created user object (same structure as Get User response).

Error Responses

400

error

Invalid Argument - Invalid username format or missing required fields

403

error

Permission Denied - User registration is disabled

Update User

Updates specific fields of a user account using field masks. Users can update their own accounts; admins can update any account.

PATCH /api/v1/users/{user_id}

curl -X PATCH https://your-memos-instance.com/api/v1/users/101 \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "user": {
      "name": "users/101",
      "display_name": "Alice Johnson",
      "email": "[email protected]"
    },
    "update_mask": {
      "paths": ["display_name", "email"]
    }
  }'

Path Parameters

user_id

string

required

The ID of the user to update

Request Body

user

object

required

The user object with updated fields. Must include name field.

update_mask

object

required

Specifies which fields to update.

Show paths

paths

array

required

Array of field paths: ["username", "email", "display_name", "avatar_url", "description", "password", "role"]

allow_missing

boolean

If true, allows updating sensitive fields. Default: false

Updatable Fields

username - Username (admin only)
email - Email address
display_name - Display name
avatar_url - Avatar URL
description - User bio
password - Password (self or admin only)
role - User role (admin only)

Response

Returns the updated user object.

Error Responses

400

error

Invalid Argument - Empty update_mask or invalid field values

401

error

Unauthenticated - User not authenticated

403

error

Permission Denied - User cannot modify this account

Delete User

Deletes a user account. Requires admin privileges.

DELETE /api/v1/users/{user_id}

curl -X DELETE https://your-memos-instance.com/api/v1/users/101 \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Path Parameters

user_id

string

required

The ID of the user to delete

Query Parameters

force

boolean

If true, delete even if user has associated data. Default: false

Response

Returns empty response on success.

Get User Statistics

Retrieves statistics for a specific user including memo counts, tags, and activity.

GET /api/v1/users/{user_id}:getStats

curl https://your-memos-instance.com/api/v1/users/101:getStats \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Response

name

string

Resource name of the user

total_memo_count

integer

Total number of memos created by the user

memo_display_timestamps

array

Array of timestamps when memos were displayed

memo_type_stats

object

Statistics by memo type:

link_count - Memos containing links
code_count - Memos containing code
todo_count - Memos with task lists
undo_count - Memos with completed tasks

tag_count

object

Map of tag names to usage counts. Example: {"work": 15, "personal": 42}

pinned_memos

array

Array of pinned memo resource names

List All User Statistics

Retrieves statistics for all users. Requires admin privileges.

GET /api/v1/users:stats

curl https://your-memos-instance.com/api/v1/users:stats \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Response

stats

array

Array of user statistics objects (same structure as Get User Statistics)

User Settings

Get User Setting

Retrieves a specific user setting.

GET /api/v1/users/{user_id}/settings/{setting_key}

curl https://your-memos-instance.com/api/v1/users/101/settings/GENERAL \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Available Setting Keys:

GENERAL - General user preferences (locale, theme, default visibility)
WEBHOOKS - Webhook configurations

Update User Setting

PATCH /api/v1/users/{user_id}/settings/{setting_key}

curl -X PATCH https://your-memos-instance.com/api/v1/users/101/settings/GENERAL \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "setting": {
      "name": "users/101/settings/GENERAL",
      "general_setting": {
        "locale": "en",
        "theme": "dark",
        "memo_visibility": "PRIVATE"
      }
    },
    "update_mask": {
      "paths": ["general_setting"]
    }
  }'

General Setting Fields:

locale - Preferred language code (e.g., "en", "zh", "fr")
theme - Theme name from web/public/themes/ directory
memo_visibility - Default visibility for new memos: PRIVATE, PROTECTED, or PUBLIC

List User Settings

GET /api/v1/users/{user_id}/settings

curl https://your-memos-instance.com/api/v1/users/101/settings \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Personal Access Tokens

List Personal Access Tokens

Retrieves all Personal Access Tokens for a user.

GET /api/v1/users/{user_id}/personalAccessTokens

curl https://your-memos-instance.com/api/v1/users/101/personalAccessTokens \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Create Personal Access Token

Creates a new long-lived token for API/script access.

POST /api/v1/users/{user_id}/personalAccessTokens

curl -X POST https://your-memos-instance.com/api/v1/users/101/personalAccessTokens \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "CI/CD Pipeline Token",
    "expires_in_days": 90
  }'

Request Fields:

description - Human-readable description of the token’s purpose
expires_in_days - Expiration in days (0 = never expires)

Response:

{
  "personal_access_token": {
    "name": "users/101/personalAccessTokens/abc123",
    "description": "CI/CD Pipeline Token",
    "created_at": "2024-01-15T10:00:00Z",
    "expires_at": "2024-04-15T10:00:00Z"
  },
  "token": "memos_pat_abc123xyz789..."  // Only shown once!
}

The token value is only returned once during creation. Store it securely - you won’t be able to retrieve it again.

Delete Personal Access Token

DELETE /api/v1/users/{user_id}/personalAccessTokens/{token_id}

curl -X DELETE https://your-memos-instance.com/api/v1/users/101/personalAccessTokens/abc123 \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

User Webhooks

List User Webhooks

GET /api/v1/users/{user_id}/webhooks

curl https://your-memos-instance.com/api/v1/users/101/webhooks \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Create User Webhook

POST /api/v1/users/{user_id}/webhooks

curl -X POST https://your-memos-instance.com/api/v1/users/101/webhooks \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "webhook": {
      "url": "https://example.com/webhook",
      "display_name": "My Webhook"
    }
  }'

Update User Webhook

PATCH /api/v1/users/{user_id}/webhooks/{webhook_id}

curl -X PATCH https://your-memos-instance.com/api/v1/users/101/webhooks/xyz789 \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "webhook": {
      "name": "users/101/webhooks/xyz789",
      "url": "https://new-url.com/webhook"
    },
    "update_mask": {
      "paths": ["url"]
    }
  }'

Delete User Webhook

DELETE /api/v1/users/{user_id}/webhooks/{webhook_id}

curl -X DELETE https://your-memos-instance.com/api/v1/users/101/webhooks/xyz789 \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

User Notifications

List User Notifications

GET /api/v1/users/{user_id}/notifications

curl https://your-memos-instance.com/api/v1/users/101/notifications \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Query Parameters:

page_size - Maximum notifications to return
page_token - Pagination token
filter - CEL expression to filter notifications

Update User Notification

Mark a notification as read or archived.

PATCH /api/v1/users/{user_id}/notifications/{notification_id}

curl -X PATCH https://your-memos-instance.com/api/v1/users/101/notifications/xyz789 \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "notification": {
      "name": "users/101/notifications/xyz789",
      "status": "ARCHIVED"
    },
    "update_mask": {
      "paths": ["status"]
    }
  }'

Notification Status:

UNREAD - New notification
ARCHIVED - Read/dismissed

Notification Types:

MEMO_COMMENT - Someone commented on your memo

Delete User Notification

DELETE /api/v1/users/{user_id}/notifications/{notification_id}

curl -X DELETE https://your-memos-instance.com/api/v1/users/101/notifications/xyz789 \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Overview

Resources

Integration

​Overview

​List Users

​Query Parameters

​Response

​Error Responses

​Get User

​Path Parameters

​Response

​Error Responses

​Create User

​Request Body

​User Creation Rules

​Response

​Error Responses

​Update User

​Path Parameters

​Request Body

​Updatable Fields

​Response

​Error Responses

​Delete User

​Path Parameters

​Query Parameters

​Response

​Get User Statistics

​Response

​List All User Statistics

​Response

​User Settings

​Get User Setting

​Update User Setting

​List User Settings

​Personal Access Tokens

​List Personal Access Tokens

​Create Personal Access Token

​Delete Personal Access Token

​User Webhooks

​List User Webhooks

​Create User Webhook

​Update User Webhook

​Delete User Webhook

​User Notifications

​List User Notifications

​Update User Notification

​Delete User Notification

Build docs developers (and LLMs) love

Overview

List Users

Query Parameters

Response

Error Responses

Get User

Path Parameters

Response

Error Responses

Create User

Request Body

User Creation Rules

Response

Error Responses

Update User

Path Parameters

Request Body

Updatable Fields

Response

Error Responses

Delete User

Path Parameters

Query Parameters

Response

Get User Statistics

Response

List All User Statistics

Response

User Settings

Get User Setting

Update User Setting

List User Settings

Personal Access Tokens

List Personal Access Tokens

Create Personal Access Token

Delete Personal Access Token

User Webhooks

List User Webhooks

Create User Webhook

Update User Webhook

Delete User Webhook

User Notifications

List User Notifications

Update User Notification

Delete User Notification