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.

The notes endpoints are the core of the Spote API. You can create, read, update, delete, and list notes programmatically. When you create or update a note, Spote automatically generates a semantic embedding so the note is immediately searchable.

​
Note object

All endpoints that return a note use this structure:
​
_id
string
required
UUID string identifying the note. Use this to reference the note in other endpoints.
​
title
string
required
The note title.
​
text
string
required
The note body in Markdown.
​
bucket
string
required
The folder the note belongs to. Defaults to "Inbox".
​
tags
string[]
required
Array of tag strings. Tags do not include the # prefix.
​
attachments
object[]
File attachments linked to this note.
​
created_at
string
required
ISO 8601 date string of when the note was created.
​
updated_at
string
required
ISO 8601 date string of when the note was last updated.

​
POST /api/notes

Create a new note. Spote generates a semantic embedding from the title, bucket, tags, and text automatically.

​
Request body

​
title
string
required
The note title. Must be at least 1 character.
​
text
string
required
The note body in Markdown.
​
bucket
string
default:"Inbox"
The folder to place the note in. If the bucket does not exist, it is created automatically.
​
tags
string[]
required
Array of tags without the # prefix. Pass an empty array if the note has no tags.

​
Response

201 Created — returns the full Note object. 
curl -X POST https://your-spote-app.com/api/notes \
  -H "Authorization: Bearer spote_YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "How vector search works",
    "text": "Vector search finds semantically similar content by comparing embeddings...",
    "bucket": "Research",
    "tags": ["ai", "search", "embeddings"]
  }'

{
  "_id": "a3f1e2b4-...",
  "title": "How vector search works",
  "text": "Vector search finds semantically similar content by comparing embeddings...",
  "bucket": "Research",
  "tags": ["ai", "search", "embeddings"],
  "attachments": [],
  "created_at": "2024-01-15T10:30:00Z",
  "updated_at": "2024-01-15T10:30:00Z"
}

​
GET /api/notes

List notes for your account. Results are sorted by creation date, newest first. Supports pagination and filtering by bucket or tag.

​
Query parameters

​
limit
number
default:"20"
Maximum number of notes to return.
​
offset
number
default:"0"
Number of notes to skip. Use with limit for pagination.
​
buckets
string[]
Filter by bucket name. Pass multiple values to include notes from several buckets: ?buckets=Work&buckets=Research.
​
tags
string[]
Filter by tag. Pass multiple values to include notes with any of the specified tags: ?tags=ai&tags=ml.

​
Response

200 OK — returns an array of note list items. Embedding fields (embedding, embedding_text) are excluded from list responses. 
curl "https://your-spote-app.com/api/notes?limit=5&buckets=Research&tags=ai" \
  -H "Authorization: Bearer spote_YOUR_TOKEN"

[
  {
    "_id": "a3f1e2b4-...",
    "title": "How vector search works",
    "text": "Vector search finds semantically similar content...",
    "bucket": "Research",
    "tags": ["ai", "search", "embeddings"],
    "created_at": "2024-01-15T10:30:00Z"
  }
]

​
GET /api/notes/:id

Retrieve a single note by its ID.

​
Path parameters

​
id
string
required
The note UUID.

​
Response

200 OK — returns the full Note object including the version field. 404 Not Found — the note does not exist or belongs to another user. 
curl https://your-spote-app.com/api/notes/a3f1e2b4-... \
  -H "Authorization: Bearer spote_YOUR_TOKEN"

​
PUT /api/notes/:id

Update an existing note. All body fields are optional — only the fields you include are updated. If you include a version, Spote performs conflict detection.

​
Path parameters

​
id
string
required
The note UUID.

​
Request body

​
title
string
Updated title.
​
text
string
Updated Markdown body. Updating text triggers a new embedding to be generated.
​
bucket
string
Updated bucket name.
​
tags
string[]
Updated tags array without # prefixes.
​
version
number
The version number you last received for this note. If provided, Spote compares this against the database version. If they differ, a 409 is returned instead of applying the update.

​
Response

200 OK — returns the updated Note object with the incremented version. 403 Forbidden — you have read-only access to this note via a share. 409 Conflict — the version you sent does not match the current version in the database. The response body contains the current note so you can resolve the conflict. 
curl -X PUT https://your-spote-app.com/api/notes/a3f1e2b4-... \
  -H "Authorization: Bearer spote_YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "How vector search works (updated)",
    "tags": ["ai", "search", "embeddings", "cosine"],
    "version": 2
  }'

​
DELETE /api/notes/:id

Delete a note and all of its shares permanently.

​
Path parameters

​
id
string
required
The note UUID.

​
Response

204 No Content — the note and all associated shares have been deleted. 
curl -X DELETE https://your-spote-app.com/api/notes/a3f1e2b4-... \
  -H "Authorization: Bearer spote_YOUR_TOKEN"