Activities

Overview

Activities track significant events in Memos, such as memo comments. They serve as an audit log and power the notification system. Activities are automatically created by the system and cannot be directly created or modified by users.

List Activities

Retrieves a paginated list of activities. Activities are returned in reverse chronological order (newest first).

GET /api/v1/activities

curl https://your-memos-instance.com/api/v1/activities?page_size=50 \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Query Parameters

page_size

integer

Maximum number of activities to return. Default: 100, Maximum: 1000If not specified or set to 0, defaults to 100 activities.

page_token

string

Token for retrieving the next page of results (from previous response)

Response

activities

array

Array of activity objects

Show activity object

name

string

The resource name of the activity. Format: activities/{activity_id}

creator

string

The user who triggered the activity. Format: users/{user_id}

type

string

The type of activity:

MEMO_COMMENT - A user commented on a memo
TYPE_UNSPECIFIED - Unknown or system activity

level

string

The severity level of the activity:

INFO - Informational (default)
WARN - Warning
ERROR - Error
LEVEL_UNSPECIFIED - Unknown

create_time

timestamp

When the activity occurred

payload

object

Activity-specific details. Structure depends on the activity type.

next_page_token

string

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

Activity Filtering

Activities referencing deleted content (like deleted memos) are automatically filtered out of the response rather than causing errors.

Example Response

{
  "activities": [
    {
      "name": "activities/42",
      "creator": "users/101",
      "type": "MEMO_COMMENT",
      "level": "INFO",
      "create_time": "2024-01-15T14:30:00Z",
      "payload": {
        "memo_comment": {
          "memo": "memos/comment123",
          "related_memo": "memos/original456"
        }
      }
    },
    {
      "name": "activities/41",
      "creator": "users/102",
      "type": "MEMO_COMMENT",
      "level": "INFO",
      "create_time": "2024-01-15T10:15:00Z",
      "payload": {
        "memo_comment": {
          "memo": "memos/comment789",
          "related_memo": "memos/original456"
        }
      }
    }
  ],
  "next_page_token": "CgRhYmNk"
}

Get Activity

Retrieves a single activity by its ID.

GET /api/v1/activities/{activity_id}

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

Path Parameters

activity_id

integer

required

The numeric ID of the activity to retrieve. Format: activities/{id}

Response

Returns an activity object (same structure as in List Activities).

Error Responses

400

error

Invalid Argument - Invalid activity name format

404

error

Not Found - Activity does not exist or references deleted content

500

error

Internal Error - Failed to retrieve activity from database

Activity Types

MEMO_COMMENT

Triggered when a user creates a comment on a memo. Payload Structure:

memo_comment

object

Details about the comment activity

Show properties

memo

string

The resource name of the comment memo. Format: memos/{memo_id}This is the newly created comment itself.

The resource name of the memo being commented on. Format: memos/{memo_id}This is the original memo that received the comment.

Example:

{
  "name": "activities/42",
  "creator": "users/101",
  "type": "MEMO_COMMENT",
  "level": "INFO",
  "create_time": "2024-01-15T14:30:00Z",
  "payload": {
    "memo_comment": {
      "memo": "memos/comment123",
      "related_memo": "memos/original456"
    }
  }
}

Use Cases:

Notifications: Alert the original memo’s author about new comments
Activity feed: Show recent commenting activity across the platform
Analytics: Track engagement on specific memos

Activity Levels

Activity levels indicate the importance or severity of an activity. Currently, most activities use the INFO level.

INFO

Standard informational activities:

User comments on memos
Regular user interactions
Non-critical system events

WARN

Warning-level activities (future use):

Approaching resource limits
Deprecated feature usage
Non-breaking issues

ERROR

Error-level activities (future use):

Failed operations
System errors affecting users
Critical issues requiring attention

Integration with Notifications

Activities are closely tied to the notification system. When certain activities occur, notifications are automatically created for relevant users.

Activity → Notification Mapping

MEMO_COMMENT Activity: When a user comments on someone else’s memo:

An activity is created with type MEMO_COMMENT
A notification is sent to the original memo’s creator
The notification links to the activity via activity_id

Accessing Related Notifications: See User Notifications for:

Listing user notifications
Marking notifications as read
Filtering notifications by activity type

Implementation Details

Automatic Creation

Activities are created automatically by the system:

Comment Creation: When CreateMemoComment is called
System Events: When significant system events occur
Background Jobs: From scheduled tasks and background workers

Users cannot directly create activities via the API.

Storage

Activities are stored in the activity table with:

Unique auto-incrementing ID
Creator ID (user who triggered the activity)
Type enum (e.g., MEMO_COMMENT)
Level enum (INFO, WARN, ERROR)
Created timestamp
Payload (JSON-serialized activity-specific data)

Retention

Activities are retained indefinitely by default. Consider implementing cleanup policies for:

Activities older than X months
Activities referencing deleted content
Low-priority INFO-level activities

Performance Considerations

Activities are indexed by creator_id and create_time for fast queries
Pagination is strongly recommended for listing activities
The system gracefully handles activities referencing deleted content

Use Cases

Audit Log

Track important user actions:

curl "https://your-memos-instance.com/api/v1/activities?page_size=100" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Filter in your application:

By user: Check creator field
By date: Parse create_time field
By type: Filter on type field

User Activity Feed

Show recent activity for a specific user:

List activities
Filter by creator matching the user’s ID
Display in a timeline view

Engagement Analytics

Track engagement metrics:

Count MEMO_COMMENT activities to measure interaction
Analyze activity timestamps for usage patterns
Identify most active users or most commented memos

Real-time Updates

Poll for new activities:

# Get the latest activity ID
latest_id=$(curl "https://your-memos-instance.com/api/v1/activities?page_size=1" | jq -r '.activities[0].name')

# Poll for newer activities
while true; do
  curl "https://your-memos-instance.com/api/v1/activities" \
    | jq -r '.activities[] | select(.name > "'$latest_id'")'  
  sleep 30
done

Best Practices

Pagination

Always use page_size to limit results
Store and use next_page_token for subsequent requests
Don’t assume all activities fit in one page

Error Handling

Handle 404 errors gracefully (activity may reference deleted content)
Implement retries for 500-level errors
Cache activity data to reduce API calls

Privacy

Respect memo visibility when displaying activities
Don’t expose private memo activities to unauthorized users
Filter activities based on user permissions in your application

Performance

Use reasonable page sizes (50-100 items)
Implement client-side caching for recently fetched activities
Consider rate limiting when polling for new activities

Overview

Resources

Integration

Overview

List Activities

Query Parameters

Response

Activity Filtering

Example Response

Get Activity

Path Parameters

Response

Error Responses

Activity Types

MEMO_COMMENT

Activity Levels

INFO

WARN

ERROR

Integration with Notifications

Activity → Notification Mapping

Implementation Details

Automatic Creation

Storage

Retention

Performance Considerations

Use Cases

Audit Log

User Activity Feed

Engagement Analytics

Real-time Updates

Best Practices

Error Handling

Privacy

Performance

Build docs developers (and LLMs) love

Overview

Resources

Integration

​Overview

​List Activities

​Query Parameters

​Response

​Activity Filtering

​Example Response

​Get Activity

​Path Parameters

​Response

​Error Responses

​Activity Types

​MEMO_COMMENT

​Activity Levels

​INFO

​WARN

​ERROR

​Integration with Notifications

​Activity → Notification Mapping

​Implementation Details

​Automatic Creation

​Storage

​Retention

​Performance Considerations

​Use Cases

​Audit Log

​User Activity Feed

​Engagement Analytics

​Real-time Updates

​Best Practices

​Pagination

​Error Handling

​Privacy

​Performance

Build docs developers (and LLMs) love

Overview

List Activities

Query Parameters

Response

Activity Filtering

Example Response

Get Activity

Path Parameters

Response

Error Responses

Activity Types

MEMO_COMMENT

Activity Levels

INFO

WARN

ERROR

Integration with Notifications

Activity → Notification Mapping

Implementation Details

Automatic Creation

Storage

Retention

Performance Considerations

Use Cases

Audit Log

User Activity Feed

Engagement Analytics

Real-time Updates

Best Practices

Pagination

Error Handling

Privacy

Performance