Skip to main content
All sharing endpoints require authentication via JWT or API token. Only note owners can manage shares.
​
Authorization
string
required
Bearer token (JWT or API token)

​
Share Note

Share a note with another user by their user ID. 
curl -X POST http://localhost:3001/api/notes/note-uuid-123/shares \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "sharedWithUserId": "user-uuid-789",
    "permission": "viewer"
  }'
​
id
string
required
Note UUID to share
​
sharedWithUserId
string
required
UUID of user to share with (cannot be empty)
​
permission
enum
required
Share permission level:
  • viewer - Read-only access
  • editor - Read and write access
{
  "id": "share-uuid-456",
  "noteId": "note-uuid-123",
  "sharedWithUserId": "user-uuid-789",
  "sharedByUserId": "user-uuid-456",
  "permission": "viewer",
  "isDeleted": false,
  "createdAt": "2026-03-02T10:30:00.000Z",
  "updatedAt": "2026-03-02T10:30:00.000Z",
  "sharedWithUser": {
    "id": "user-uuid-789",
    "name": "Jane Collaborator",
    "email": "jane@example.com",
    "profileImage": null
  }
}
​
id
string
Unique share ID
​
noteId
string
Note being shared
​
sharedWithUserId
string
User receiving access
​
sharedByUserId
string
User who created the share (note owner)
​
permission
enum
Permission level: viewer or editor
​
sharedWithUser
object
User details for the recipient

​
Error Responses

403 Forbidden
{
  "statusCode": 403,
  "message": "Only note owner can share notes",
  "error": "Forbidden"
}
404 Not Found
{
  "statusCode": 404,
  "message": "User not found",
  "error": "Not Found"
}
409 Conflict
{
  "statusCode": 409,
  "message": "Note already shared with this user",
  "error": "Conflict"
}
You cannot share a note with yourself. The sharedWithUserId must be different from the note owner’s ID.

​
List Note Shares

Get all users a note is shared with. 
curl -X GET http://localhost:3001/api/notes/note-uuid-123/shares \
  -H "Authorization: Bearer YOUR_TOKEN"
​
id
string
required
Note UUID
[
  {
    "id": "share-uuid-456",
    "noteId": "note-uuid-123",
    "sharedWithUserId": "user-uuid-789",
    "sharedByUserId": "user-uuid-456",
    "permission": "viewer",
    "isDeleted": false,
    "createdAt": "2026-03-02T10:30:00.000Z",
    "updatedAt": "2026-03-02T10:30:00.000Z",
    "sharedWithUser": {
      "id": "user-uuid-789",
      "name": "Jane Collaborator",
      "email": "jane@example.com",
      "profileImage": null
    }
  },
  {
    "id": "share-uuid-999",
    "noteId": "note-uuid-123",
    "sharedWithUserId": "user-uuid-321",
    "sharedByUserId": "user-uuid-456",
    "permission": "editor",
    "isDeleted": false,
    "createdAt": "2026-03-01T14:00:00.000Z",
    "updatedAt": "2026-03-01T14:00:00.000Z",
    "sharedWithUser": {
      "id": "user-uuid-321",
      "name": "John Editor",
      "email": "john@example.com",
      "profileImage": "/uploads/profiles/john-avatar.jpg"
    }
  }
]
Only the note owner can view the list of shares. Users with shared access cannot see who else has access to the note.

​
Update Share Permission

Change the permission level of an existing share. 
curl -X PATCH http://localhost:3001/api/notes/note-uuid-123/shares/share-uuid-456 \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "permission": "editor"
  }'
​
id
string
required
Note UUID
​
shareId
string
required
Share UUID
​
permission
enum
required
Updated permission level:
  • viewer - Read-only access
  • editor - Read and write access
{
  "id": "share-uuid-456",
  "noteId": "note-uuid-123",
  "sharedWithUserId": "user-uuid-789",
  "sharedByUserId": "user-uuid-456",
  "permission": "editor",
  "isDeleted": false,
  "createdAt": "2026-03-02T10:30:00.000Z",
  "updatedAt": "2026-03-02T11:00:00.000Z",
  "sharedWithUser": {
    "id": "user-uuid-789",
    "name": "Jane Collaborator",
    "email": "jane@example.com",
    "profileImage": null
  }
}

​
Error Responses

403 Forbidden
{
  "statusCode": 403,
  "message": "Only note owner can update share permissions",
  "error": "Forbidden"
}
404 Not Found
{
  "statusCode": 404,
  "message": "Share not found",
  "error": "Not Found"
}

​
Revoke Share

Remove a user’s access to a note. 
curl -X DELETE http://localhost:3001/api/notes/note-uuid-123/shares/share-uuid-456 \
  -H "Authorization: Bearer YOUR_TOKEN"
​
id
string
required
Note UUID
​
shareId
string
required
Share UUID to revoke
{
  "message": "Share revoked successfully"
}

​
Error Responses

403 Forbidden
{
  "statusCode": 403,
  "message": "Only note owner can revoke shares",
  "error": "Forbidden"
}
404 Not Found
{
  "statusCode": 404,
  "message": "Share not found",
  "error": "Not Found"
}
Revoking a share soft-deletes it (marks as isDeleted: true). The share record remains in the database but the user immediately loses access to the note.

​
Permission Levels

​
Viewer Permission

Users with viewer permission can:
  • View note content
  • See note metadata (title, tags, timestamps)
  • View note in their shared notes list
Users with viewer permission cannot:
  • Edit note content or metadata
  • Delete or archive the note
  • Share the note with others
  • Modify tags

​
Editor Permission

Users with editor permission can:
  • View note content
  • Edit note content, title, and metadata
  • Pin/unpin the note
  • Archive/unarchive the note
  • Add/remove tags
  • Move note to trash (soft delete)
Users with editor permission cannot:
  • Permanently delete the note
  • Share the note with others
  • Modify existing shares
  • Change note ownership

​
Shared Note Behavior

​
In List Endpoints

Shared notes appear in the note list with additional metadata: 
{
  "id": "note-uuid-123",
  "title": "Shared Note",
  "isOwner": false,
  "permission": "editor",
  "userId": "user-uuid-999",  // Original owner's ID
  // ... other fields
}
​
isOwner
boolean
false for shared notes, true for owned notes
​
permission
enum
Current user’s permission: viewer or editor (null for owned notes)

​
Deleted Shares

Shares marked as isDeleted: true are excluded from:
  • List note shares endpoint
  • Note list queries (shared users no longer see the note)
  • Permission checks (access is revoked)

​
Finding Shared Notes

The main notes list endpoint (GET /api/notes) automatically includes:
  1. Notes you own
  2. Notes shared with you (with active shares)
Shared notes are ordered the same way as owned notes (pinned first, then by update time).
Use the isOwner and permission fields in the response to determine whether the current user can modify sharing settings.

​
Share Lifecycle

  1. Create Share: Owner shares note with user
  2. Active: User can access note per permission level
  3. Update: Owner can change permission from viewer to editor or vice versa
  4. Revoke: Owner removes user’s access (soft delete)

Build docs developers (and LLMs) love

Get started for freeTalk to us