> ## Documentation Index
> Fetch the complete documentation index at: https://docs.spote.cloud/llms.txt
> Use this file to discover all available pages before exploring further.

# Shares API — invite and manage collaborators

> Invite users to a specific note by email via POST /api/notes/:id/shares. Set read or write permission, list all invitations, and revoke access at any time.

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.

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

## Share object

<ResponseField name="_id" type="string" required>
  UUID identifying the share.
</ResponseField>

<ResponseField name="note_id" type="string" required>
  UUID of the note this share is for.
</ResponseField>

<ResponseField name="invited_email" type="string" required>
  Email address of the invited user.
</ResponseField>

<ResponseField name="permission" type="string" required>
  Access level granted: `"read"` or `"write"`.
</ResponseField>

<ResponseField name="created_at" type="string" required>
  ISO 8601 date string of when the invitation was created.
</ResponseField>

<ResponseField name="accepted_at" type="string">
  ISO 8601 date string of when the invitation was accepted. `null` if the invitation has not been accepted yet.
</ResponseField>

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

***

## GET /api/notes/:id/shares

List all active share invitations for a note.

### Path parameters

<ParamField path="id" type="string" required>
  The UUID of the note.
</ParamField>

### Response

**200 OK** — array of share objects for the note.

```bash theme={null}
curl https://your-spote-app.com/api/notes/NOTE_ID/shares \
  -H "Authorization: Bearer spote_YOUR_TOKEN"
```

```json theme={null}
[
  {
    "_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

<ParamField path="id" type="string" required>
  The UUID of the note to share.
</ParamField>

### Request body

<ParamField body="email" type="string" required>
  Email address of the person to invite.
</ParamField>

<ParamField body="permission" type="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.
</ParamField>

### 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.

```bash theme={null}
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"}'
```

```json theme={null}
{
  "_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

<ParamField path="id" type="string" required>
  The UUID of the note.
</ParamField>

<ParamField path="shareId" type="string" required>
  The UUID of the share to revoke.
</ParamField>

### Response

**204 No Content** — the share has been revoked.

```bash theme={null}
curl -X DELETE https://your-spote-app.com/api/notes/NOTE_ID/shares/SHARE_ID \
  -H "Authorization: Bearer spote_YOUR_TOKEN"
```