Skip to main content

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.

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:
​
score
number
required
Semantic similarity score between 0 and 1. Higher values indicate closer semantic match. Scores above 0.8 indicate strong relevance.
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

​
q
string
required
Natural language search query. Do not use keyword syntax — phrase your query as you would ask a question or describe a topic.

​
Response

200 OK — array of up to 10 NoteWithScore objects, sorted by score descending. 
curl "https://your-spote-app.com/api/notes/search?q=machine+learning+decisions" \
  -H "Authorization: Bearer spote_YOUR_TOKEN"

[
  {
    "_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

​
id
string
required
The UUID of the source note. The source note itself is excluded from the results.

​
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. 
curl https://your-spote-app.com/api/notes/similar/a3f1e2b4-... \
  -H "Authorization: Bearer spote_YOUR_TOKEN"

[
  {
    "_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. 
curl https://your-spote-app.com/api/notes/shared \
  -H "Authorization: Bearer spote_YOUR_TOKEN"

[
  {
    "_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"
  }
]