Notes API — create, read, update, delete

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:

string

required

UUID string identifying the note. Use this to reference the note in other endpoints.

string

required

The note title.

string

required

The note body in Markdown.

string

required

The folder the note belongs to. Defaults to "Inbox".

string[]

required

Array of tag strings. Tags do not include the # prefix.

object[]

File attachments linked to this note.

Show attachment properties

string

Original filename of the uploaded file.

string

Internal proxy URL: /api/files/{userId}/{uuid}.{ext}. See Files.

string

MIME type of the file, e.g. "image/png".

number

File size in bytes.

string

required

ISO 8601 date string of when the note was created.

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

string

required

The note title. Must be at least 1 character.

string

required

The note body in Markdown.

string

default:"Inbox"

The folder to place the note in. If the bucket does not exist, it is created automatically.

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

number

default:"20"

Maximum number of notes to return.

number

default:"0"

Number of notes to skip. Use with limit for pagination.

string[]

Filter by bucket name. Pass multiple values to include notes from several buckets: ?buckets=Work&buckets=Research.

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

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

string

required

The note UUID.

Request body

string

Updated title.

string

Updated Markdown body. Updating text triggers a new embedding to be generated.

string

Updated bucket name.

string[]

Updated tags array without # prefixes.

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

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"

Overview

Endpoints

Notes API — create, read, update, delete

Note object

POST /api/notes

Request body

Response

GET /api/notes

Query parameters

Response

GET /api/notes/:id

Path parameters

Response

PUT /api/notes/:id

Path parameters

Request body

Response

DELETE /api/notes/:id

Path parameters

Response

​Note object

​POST /api/notes

​Request body

​Response

​GET /api/notes

​Query parameters

​Response

​GET /api/notes/:id

​Path parameters

​Response

​PUT /api/notes/:id

​Path parameters

​Request body

​Response

​DELETE /api/notes/:id

​Path parameters

​Response

Note object

POST /api/notes

Request body

Response

GET /api/notes

Query parameters

Response

GET /api/notes/:id

Path parameters

Response

PUT /api/notes/:id

Path parameters

Request body

Response

DELETE /api/notes/:id

Path parameters

Response