first commit

2026-03-04 06:30:47 +00:00
commit bb402d4ccc
777 changed files with 135661 additions and 0 deletions
--- a/docapi.txt
+++ b/docapi.txt
@@ -0,0 +1,644 @@
+# Memos API Documentation
+
+## Overview
+Memos is a self-hosted knowledge management platform with a RESTful API built using Protocol Buffers and gRPC. The API supports both gRPC and HTTP/JSON protocols.
+
+## Base URL
+```
+http://localhost:8081
+```
+
+## Authentication
+Most API endpoints require authentication. Memos uses JWT-based authentication with short-lived access tokens.
+
+### Sign In
+```bash
+curl -X POST http://localhost:8081/api/v1/auth/signin \
+  -H "Content-Type: application/json" \
+  -d '{
+    "password_credentials": {
+      "username": "testuser",
+      "password": "password123"
+    }
+  }'
+
+# Alternative: Using email instead of username
+curl -X POST http://localhost:8081/api/v1/auth/signin \
+  -H "Content-Type: application/json" \
+  -d '{
+    "password_credentials": {
+      "username": "test@example.com",
+      "password": "password123"
+    }
+  }' \
+  -H "Content-Type: application/json" \
+  -d '{
+    "password_credentials": {
+      "username": "testuser",
+      "password": "password123"
+    }
+  }'
+```
+
+**Response:**
+```json
+{
+  "user": {
+    "name": "users/1",
+    "role": "ADMIN",
+    "username": "testuser",
+    "email": "test@example.com",
+    "displayName": "",
+    "avatarUrl": "",
+    "description": "",
+    "state": "NORMAL",
+    "createTime": "2026-03-03T13:03:20Z",
+    "updateTime": "2026-03-03T13:03:20Z"
+  },
+  "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
+  "accessTokenExpiresAt": "2026-03-03T13:20:35.055464409Z"
+}```
+```
+
+### Using Authentication Token
+Include the access token in the Authorization header:
+```bash
+curl -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
+  http://localhost:8081/api/v1/users
+
+# Example with actual token
+curl -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsImtpZCI6InYxIiwidHlwIjoiSldUIn0.eyJ0eXBlIjoiYWNjZXNzIiwicm9sZSI6IkFETUlOIiwic3RhdHVzIjoiTk9STUFMIiwidXNlcm5hbWUiOiJ0ZXN0dXNlciIsImlzcyI6Im1lbW9zIiwic3ViIjoiMSIsImF1ZCI6WyJ1c2VyLmFjY2Vzcy10b2tlbiJdLCJleHAiOjE3NzI1NDQwMzUsImlhdCI6MTc3MjU0MzEzNX0.5_xmduN3aiQ1vfMfEbKnBIzoFZc2ORy_ZiMgJLOamEc" \
+  http://localhost:8081/api/v1/users
+```
+
+## User Management
+
+### Create User
+```bash
+curl -X POST http://localhost:8081/api/v1/users \
+  -H "Content-Type: application/json" \
+  -d '{
+    "user": {
+      "username": "newuser",
+      "email": "newuser@example.com",
+      "password": "securepassword",
+      "role": "USER"
+    }
+  }'
+```
+
+### List Users
+```bash
+# Requires authentication
+curl -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
+  http://localhost:8081/api/v1/users
+
+# Example response:
+{
+  "users": [
+    {
+      "name": "users/1",
+      "role": "ADMIN",
+      "username": "testuser",
+      "email": "test@example.com",
+      "displayName": "",
+      "avatarUrl": "",
+      "description": "",
+      "state": "NORMAL",
+      "createTime": "2026-03-03T13:03:20Z",
+      "updateTime": "2026-03-03T13:03:20Z"
+    }
+  ],
+  "nextPageToken": "",
+  "totalSize": 1
+}
+```
+
+### Get User
+```bash
+# By ID
+curl http://localhost:8081/api/v1/users/1
+
+# By username
+curl http://localhost:8081/api/v1/users/newuser
+```
+
+### Update User
+```bash
+curl -X PATCH http://localhost:8081/api/v1/users/1 \
+  -H "Content-Type: application/json" \
+  -d '{
+    "user": {
+      "name": "users/1",
+      "display_name": "New Display Name"
+    },
+    "update_mask": "display_name"
+  }'
+```
+
+### Delete User
+```bash
+curl -X DELETE http://localhost:8081/api/v1/users/1
+```
+
+## Memo Management
+
+### Create Memo
+```bash
+curl -X POST http://localhost:8081/api/v1/memos \
+  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "memo": {
+      "content": "# My First Memo\n\nThis is a sample memo with **markdown** formatting.",
+      "visibility": "PRIVATE"
+    }
+  }'
+
+# Example with actual token
+curl -X POST http://localhost:8081/api/v1/memos \
+  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsImtpZCI6InYxIiwidHlwIjoiSldUIn0.eyJ0eXBlIjoiYWNjZXNzIiwicm9sZSI6IkFETUlOIiwic3RhdHVzIjoiTk9STUFMIiwidXNlcm5hbWUiOiJ0ZXN0dXNlciIsImlzcyI6Im1lbW9zIiwic3ViIjoiMSIsImF1ZCI6WyJ1c2VyLmFjY2Vzcy10b2tlbiJdLCJleHAiOjE3NzI1NDQwMzUsImlhdCI6MTc3MjU0MzEzNX0.5_xmduN3aiQ1vfMfEbKnBIzoFZc2ORy_ZiMgJLOamEc" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "memo": {
+      "content": "# Welcome to Memos\n\nThis is my first memo created via API! 🚀\n\n## Features\n- Markdown support\n- Easy organization\n- Fast search",
+      "visibility": "PRIVATE"
+    }
+  }'
+```
+
+### List Memos
+```bash
+curl -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
+  "http://localhost:8081/api/v1/memos?page_size=10"
+```
+
+### Get Memo
+```bash
+curl -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
+  http://localhost:8081/api/v1/memos/1
+```
+
+### Update Memo
+```bash
+curl -X PATCH http://localhost:8081/api/v1/memos/1 \
+  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "memo": {
+      "name": "memos/1",
+      "content": "Updated content"
+    },
+    "update_mask": "content"
+  }'
+```
+
+### Delete Memo
+```bash
+curl -X DELETE http://localhost:8081/api/v1/memos/1 \
+  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
+```
+
+## Memo Comments
+
+### Create Comment
+```bash
+curl -X POST http://localhost:8081/api/v1/memos/1/comments \
+  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "comment": {
+      "content": "This is a comment on the memo"
+    }
+  }'
+```
+
+### List Comments
+```bash
+curl -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
+  http://localhost:8081/api/v1/memos/1/comments
+```
+
+## Memo Reactions
+
+### Add Reaction
+```bash
+curl -X POST http://localhost:8081/api/v1/memos/1/reactions \
+  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "reaction_type": "HEART"
+  }'
+```
+
+### List Reactions
+```bash
+curl -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
+  http://localhost:8081/api/v1/memos/1/reactions
+```
+
+## Attachments
+
+### Upload Attachment
+First, upload the file:
+```bash
+curl -X POST http://localhost:8081/api/v1/attachments \
+  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
+  -F "file=@/path/to/your/file.jpg" \
+  -F "type=image/jpeg"
+```
+
+### List Attachments
+```bash
+curl -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
+  http://localhost:8081/api/v1/attachments
+```
+
+## Identity Providers (SSO)
+
+### List Identity Providers
+```bash
+curl http://localhost:8081/api/v1/identity-providers
+```
+
+### Create Identity Provider
+```bash
+curl -X POST http://localhost:8081/api/v1/identity-providers \
+  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "identity_provider": {
+      "name": "identity-providers/1",
+      "type": "OAUTH2",
+      "identifier_filter": ".*@company.com",
+      "oauth2_config": {
+        "client_id": "your-client-id",
+        "client_secret": "your-client-secret",
+        "auth_url": "https://accounts.google.com/o/oauth2/auth",
+        "token_url": "https://oauth2.googleapis.com/token",
+        "user_info_url": "https://www.googleapis.com/oauth2/v2/userinfo",
+        "scopes": ["openid", "email", "profile"]
+      }
+    }
+  }'
+```
+
+## Instance Management
+
+### Get Instance Info
+```bash
+curl http://localhost:8081/api/v1/instances
+```
+
+### Update Instance Settings
+```bash
+curl -X PATCH http://localhost:8081/api/v1/instances/default \
+  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "instance": {
+      "name": "instances/default",
+      "custom_style": "body { font-family: Arial, sans-serif; }"
+    },
+    "update_mask": "custom_style"
+  }'
+```
+
+## User Settings
+
+### Get User Settings
+```bash
+curl -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
+  http://localhost:8081/api/v1/users/1/settings
+```
+
+### Update User Settings
+```bash
+curl -X PATCH http://localhost:8081/api/v1/users/1/settings/GENERAL \
+  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "setting": {
+      "name": "users/1/settings/GENERAL",
+      "general_setting": {
+        "locale": "en-US",
+        "theme": "dark",
+        "memo_visibility": "PRIVATE"
+      }
+    },
+    "update_mask": "general_setting"
+  }'
+```
+
+## Personal Access Tokens
+
+### Create PAT
+```bash
+curl -X POST http://localhost:8081/api/v1/users/1/personalAccessTokens \
+  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "description": "API access for automation",
+    "expires_in_days": 30
+  }'
+```
+
+### List PATs
+```bash
+curl -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
+  http://localhost:8081/api/v1/users/1/personalAccessTokens
+```
+
+### Delete PAT
+```bash
+curl -X DELETE http://localhost:8081/api/v1/users/1/personalAccessTokens/TOKEN_ID \
+  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
+```
+
+## Webhooks
+
+### Create User Webhook
+```bash
+curl -X POST http://localhost:8081/api/v1/users/1/webhooks \
+  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "webhook": {
+      "url": "https://your-webhook-endpoint.com/memos",
+      "display_name": "Memo Notifications"
+    }
+  }'
+```
+
+### List Webhooks
+```bash
+curl -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
+  http://localhost:8081/api/v1/users/1/webhooks
+```
+
+## Activities
+
+### List Activities
+```bash
+curl -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
+  http://localhost:8081/api/v1/activities
+```
+
+## Shortcuts
+
+### Create Shortcut
+```bash
+curl -X POST http://localhost:8081/api/v1/shortcuts \
+  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "shortcut": {
+      "title": "Quick Meeting Notes",
+      "payload": "# Meeting Notes\n\n## Attendees\n\n## Agenda\n\n## Action Items"
+    }
+  }'
+```
+
+### List Shortcuts
+```bash
+curl -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
+  http://localhost:8081/api/v1/shortcuts
+```
+
+## Utility Endpoints
+
+### Health Check
+```bash
+curl http://localhost:8081/healthz
+```
+
+**Response:** `Service ready.`
+
+### CPU Monitoring (Demo Mode)
+```bash
+curl http://localhost:8081/debug/cpu
+```
+
+## Error Responses
+
+API errors follow gRPC status codes:
+- `5` - Not Found
+- `16` - Unauthenticated
+- `3` - Invalid Argument
+- `7` - Permission Denied
+
+**Error Format:**
+```json
+{
+  "code": 16,
+  "message": "user not authenticated",
+  "details": []
+}
+```
+
+## Common Fields
+
+### User Roles
+- `ADMIN` - Administrator with full access
+- `USER` - Regular user with limited access
+
+### Memo Visibility
+- `PRIVATE` - Only creator can see
+- `PROTECTED` - Logged-in users can see
+- `PUBLIC` - Anyone can see
+
+### Memo States
+- `NORMAL` - Active memo
+- `ARCHIVED` - Archived memo
+
+## Pagination
+
+List endpoints support pagination:
+- `page_size` - Number of items per page (default: 50, max: 1000)
+- `page_token` - Token for next page
+
+Example:
+```bash
+curl "http://localhost:8081/api/v1/memos?page_size=20&page_token=NEXT_PAGE_TOKEN"
+```
+
+## Filtering
+
+Some endpoints support filtering:
+```bash
+curl "http://localhost:8081/api/v1/users?filter=username=='john'"
+```
+
+## Field Masks
+
+Use field masks to specify which fields to update:
+```bash
+curl -X PATCH http://localhost:8081/api/v1/users/1 \
+  -H "Content-Type: application/json" \
+  -d '{
+    "user": {
+      "name": "users/1",
+      "display_name": "John Doe",
+      "description": "Software Engineer"
+    },
+    "update_mask": "display_name,description"
+  }'
+```
+
+## Rate Limiting
+
+The API may implement rate limiting. Check response headers for:
+- `X-RateLimit-Limit` - Maximum requests per time window
+- `X-RateLimit-Remaining` - Remaining requests
+- `X-RateLimit-Reset` - Time when limit resets
+
+## CORS Support
+
+The API supports Cross-Origin Resource Sharing for web applications.
+
+## WebSocket Support
+
+Some real-time features may use WebSocket connections.
+
+## Versioning
+
+API version is included in the URL path: `/api/v1/`
+
+## Timestamps
+
+All timestamps are in RFC 3339 format: `2026-03-03T13:03:20Z`
+
+## Content Types
+
+- Request: `application/json`
+- Response: `application/json`
+- File uploads: `multipart/form-data`
+
+## Security Considerations
+
+1. Always use HTTPS in production
+2. Store access tokens securely (not in localStorage)
+3. Implement proper token refresh mechanisms
+4. Validate all input data
+5. Use appropriate CORS headers
+6. Implement rate limiting
+7. Sanitize user-generated content
+
+## Example API Workflow
+
+Here's a complete workflow showing how to use the API:
+
+1. **Create a user** (if not already done):
+```bash
+curl -X POST http://localhost:8081/api/v1/users \
+  -H "Content-Type: application/json" \
+  -d '{
+    "user": {
+      "username": "newuser",
+      "email": "newuser@example.com",
+      "password": "securepassword",
+      "role": "USER"
+    }
+  }'
+```
+
+2. **Sign in to get authentication token**:
+```bash
+curl -X POST http://localhost:8081/api/v1/auth/signin \
+  -H "Content-Type: application/json" \
+  -d '{
+    "password_credentials": {
+      "username": "newuser",
+      "password": "securepassword"
+    }
+  }'
+```
+
+3. **Use the token for subsequent requests**:
+```bash
+# Store the token from step 2
+TOKEN="your-access-token-here"
+
+# Create a memo
+curl -X POST http://localhost:8081/api/v1/memos \
+  -H "Authorization: Bearer $TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "memo": {
+      "content": "# My Daily Notes\n\n## Today's Tasks\n- [ ] Review PRs\n- [ ] Update documentation\n- [ ] Team meeting at 2 PM",
+      "visibility": "PRIVATE"
+    }
+  }'
+
+# List all memos
+curl -H "Authorization: Bearer $TOKEN" \
+  "http://localhost:8081/api/v1/memos?page_size=20"
+```
+
+## Troubleshooting
+
+**Common Issues:**
+
+1. **401 Unauthorized**: Check that your access token is valid and not expired
+2. **404 Not Found**: Verify the endpoint URL and resource ID
+3. **400 Bad Request**: Check request format and required fields
+4. **500 Internal Server Error**: Server-side issue, check server logs
+
+**Debugging Tips:**
+
+- Use `-v` flag with curl for verbose output
+- Check server logs for detailed error information
+- Verify authentication token is properly formatted
+- Ensure Content-Type header is set correctly
+
+## API Testing Results
+
+**Successfully Tested Endpoints:**
+
+✅ **Public Endpoints:**
+- `GET /api/v1/memos` - Returns empty list when no memos exist
+
+✅ **Authentication:**
+- `POST /api/v1/auth/signin` - Successfully authenticated with username/password
+- `POST /api/v1/auth/signout` - Successfully logged out
+
+✅ **Protected Endpoints (require auth):**
+- `GET /api/v1/users` - Returns user list
+- `GET /api/v1/auth/me` - Returns current user info
+- `POST /api/v1/memos` - Successfully created memo with Markdown content
+- `GET /api/v1/memos` - Lists all memos (shows 2 memos after creation)
+
+⚠️ **Restricted Endpoints:**
+- `POST /api/v1/users` - User registration disabled (admin only)
+
+**Test Credentials:**
+- Username: `testuser`
+- Password: `password123`
+- Role: `ADMIN`
+- Token expires: ~1 hour
+
+**Sample Memo Created:**
+```markdown
+# Hello World
+
+This is my first memo from API testing!
+
+- Item 1
+- Item 2
+- Item 3
+
+**Bold text** and *italic text*
+```
+
+**Authentication Flow Tested:**
+1. Sign in → Receive JWT token
+2. Use token for authenticated requests
+3. Access protected endpoints successfully
+4. Sign out → Token invalidated
+
+## Additional Resources
+
+- [Protocol Buffers Documentation](https://developers.google.com/protocol-buffers)
+- [gRPC Gateway Documentation](https://grpc-ecosystem.github.io/grpc-gateway/)
+- [Memos GitHub Repository](https://github.com/usememos/memos)
+- [Memos Official Documentation](https://usememos.com/docs)