Shares API — invite and manage collaborators

The shares API lets you invite other Spote users to a note by email. Once invited, they receive an email with an invitation link. When they accept the invitation, they gain access to the note with the permission level you specified.

You can only manage shares for notes you own. Collaborators cannot invite other users to a note.

string

required

UUID identifying the share.

string

required

UUID of the note this share is for.

string

required

Email address of the invited user.

string

required

Access level granted: "read" or "write".

string

required

ISO 8601 date string of when the invitation was created.

string

ISO 8601 date string of when the invitation was accepted. null if the invitation has not been accepted yet.

The invitation token used to generate the invite link is never included in API responses.

GET /api/notes/:id/shares

List all active share invitations for a note.

Path parameters

string

required

The UUID of the note.

Response

200 OK — array of share objects for the note.

curl https://your-spote-app.com/api/notes/NOTE_ID/shares \
  -H "Authorization: Bearer spote_YOUR_TOKEN"

[
  {
    "_id": "s1a2b3c4-...",
    "note_id": "a3f1e2b4-...",
    "invited_email": "colleague@company.com",
    "permission": "write",
    "created_at": "2024-01-15T10:00:00Z",
    "accepted_at": "2024-01-15T10:05:00Z"
  },
  {
    "_id": "s5d6e7f8-...",
    "note_id": "a3f1e2b4-...",
    "invited_email": "reader@company.com",
    "permission": "read",
    "created_at": "2024-01-15T11:00:00Z",
    "accepted_at": null
  }
]

POST /api/notes/:id/shares

Invite a collaborator to a note by email. Spote creates a share record and immediately sends an invitation email via Resend. The recipient receives a link they can use to accept the invitation.

Path parameters

string

required

The UUID of the note to share.

Request body

string

required

Email address of the person to invite.

string

required

Access level to grant: "read" or "write". Collaborators with "write" access can edit the note but cannot delete it or invite additional users.

Response

201 Created — returns the created share object. 409 Conflict — this email address already has a share for this note. Revoke the existing share first if you want to change the permission. 500 Internal Server Error — the invitation email failed to send. The share record is rolled back automatically.

curl -X POST https://your-spote-app.com/api/notes/NOTE_ID/shares \
  -H "Authorization: Bearer spote_YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"email": "colleague@company.com", "permission": "write"}'

{
  "_id": "s1a2b3c4-...",
  "note_id": "a3f1e2b4-...",
  "invited_email": "colleague@company.com",
  "permission": "write",
  "created_at": "2024-01-15T10:00:00Z",
  "accepted_at": null
}

DELETE /api/notes/:id/shares/:shareId

Revoke a share, immediately removing the collaborator’s access to the note.

Path parameters

string

required

The UUID of the note.

The UUID of the share to revoke.

Response

204 No Content — the share has been revoked.

curl -X DELETE https://your-spote-app.com/api/notes/NOTE_ID/shares/SHARE_ID \
  -H "Authorization: Bearer spote_YOUR_TOKEN"

Overview

Endpoints

Shares API — invite and manage collaborators

GET /api/notes/:id/shares

Path parameters

Response

POST /api/notes/:id/shares

Path parameters

Request body

Response

DELETE /api/notes/:id/shares/:shareId

Path parameters

Response

​Share object

​GET /api/notes/:id/shares

​Path parameters

​Response

​POST /api/notes/:id/shares

​Path parameters

​Request body

​Response

​DELETE /api/notes/:id/shares/:shareId

​Path parameters

​Response

Share object

GET /api/notes/:id/shares

Path parameters

Response

POST /api/notes/:id/shares

Path parameters

Request body

Response

DELETE /api/notes/:id/shares/:shareId

Path parameters

Response