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

# Search and discover notes via the API

> Use GET /api/notes/search for natural language semantic search, GET /api/notes/similar/:id for related notes, and GET /api/notes/shared for shared notes.

Spote provides two discovery endpoints: semantic search (query → ranked notes) and similar notes (note ID → related notes). Both are powered by vector embeddings — results are ranked by semantic similarity, not keyword frequency. There is also an endpoint to retrieve notes shared with your account by other users.

## NoteWithScore object

The search and similar endpoints return `NoteWithScore` objects. These extend the standard Note object with one additional field:

<ResponseField name="score" type="number" required>
  Semantic similarity score between 0 and 1. Higher values indicate closer semantic match. Scores above 0.8 indicate strong relevance.
</ResponseField>

All standard Note fields (`_id`, `title`, `text`, `bucket`, `tags`, `attachments`, `created_at`, `updated_at`) are also included. Embedding fields are excluded.

***

## GET /api/notes/search

Semantic search over your notes. Spote embeds your query using the same model used to index notes, then finds the most semantically similar notes by comparing vector embeddings.

### Query parameters

<ParamField query="q" type="string" required>
  Natural language search query. Do not use keyword syntax — phrase your query as you would ask a question or describe a topic.
</ParamField>

### Response

**200 OK** — array of up to 10 `NoteWithScore` objects, sorted by `score` descending.

```bash theme={null}
curl "https://your-spote-app.com/api/notes/search?q=machine+learning+decisions" \
  -H "Authorization: Bearer spote_YOUR_TOKEN"
```

```json theme={null}
[
  {
    "_id": "a3f1e2b4-...",
    "title": "AI model selection",
    "text": "When choosing between models, consider...",
    "bucket": "Research",
    "tags": ["ai", "ml"],
    "attachments": [],
    "score": 0.91,
    "created_at": "2024-01-10T08:00:00Z",
    "updated_at": "2024-01-10T08:00:00Z"
  },
  {
    "_id": "b7c3d9e1-...",
    "title": "Evaluating LLM outputs",
    "text": "Automated evaluation frameworks help...",
    "bucket": "Research",
    "tags": ["ai", "evals"],
    "attachments": [],
    "score": 0.84,
    "created_at": "2024-01-12T09:15:00Z",
    "updated_at": "2024-01-12T09:15:00Z"
  }
]
```

***

## GET /api/notes/similar/:id

Find notes that are semantically similar to a specific note. Spote uses the note's stored embedding directly — no re-embedding is required.

### Path parameters

<ParamField path="id" type="string" required>
  The UUID of the source note. The source note itself is excluded from the results.
</ParamField>

### Response

**200 OK** — array of up to 10 `NoteWithScore` objects, sorted by `score` descending. The source note is not included.

**404 Not Found** — the note does not exist or belongs to another user.

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

```json theme={null}
[
  {
    "_id": "c2d4f6a8-...",
    "title": "Cosine similarity explained",
    "text": "Cosine similarity measures the angle between two vectors...",
    "bucket": "Research",
    "tags": ["math", "embeddings"],
    "attachments": [],
    "score": 0.88,
    "created_at": "2024-01-08T14:00:00Z",
    "updated_at": "2024-01-08T14:00:00Z"
  }
]
```

***

## GET /api/notes/shared

Retrieve all notes that other users have shared with you and that you have accepted. Only notes where you have an accepted share invitation (read or write) are returned.

### Query parameters

None.

### Response

**200 OK** — array of Note objects (without embedding fields) where the authenticated user has read or write access via an accepted invitation.

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

```json theme={null}
[
  {
    "_id": "e9f1a2b3-...",
    "title": "Shared project brief",
    "text": "This quarter's goals are...",
    "bucket": "Work",
    "tags": ["project", "q1"],
    "attachments": [],
    "created_at": "2024-01-05T11:00:00Z",
    "updated_at": "2024-01-05T11:00:00Z"
  }
]
```