> ## 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 REST API overview

> The Spote REST API gives you full programmatic access to notes, semantic search, file uploads, collaboration shares, and Personal Access Token management.

The Spote REST API gives you programmatic access to your notes, buckets, tags, and files. All endpoints require authentication via a Personal Access Token or a Clerk session. Use this reference to build integrations, automate note workflows, or connect AI agents to your Spote account.

## Base URL

```
https://your-spote-app.com
```

If you are running a self-hosted instance, substitute your own domain. All endpoints are relative to this base URL.

## Authentication

Every request must include an `Authorization` header with a Bearer token. See [Authentication](/api/authentication) for details on obtaining and using Personal Access Tokens.

## Content type

All request and response bodies use `application/json`, except file uploads which use `multipart/form-data`. Always set `Content-Type: application/json` on requests that include a body.

## Available resources

<CardGroup cols={2}>
  <Card title="Notes" icon="file-text" href="/api/notes">
    Create, read, update, delete, and list notes. The core resource of the Spote API.
  </Card>

  <Card title="Search" icon="search" href="/api/search">
    Semantic search by natural language query, and find notes similar to a given note.
  </Card>

  <Card title="Shares" icon="share" href="/api/shares">
    Invite collaborators to a note by email. Set read or write permission and revoke access.
  </Card>

  <Card title="Files" icon="paperclip" href="/api/files">
    Upload file attachments and retrieve them via the secure proxy endpoint.
  </Card>

  <Card title="Buckets & Tags" icon="folder" href="/api/buckets-tags">
    List the folders and tags that make up your note organization structure.
  </Card>

  <Card title="Tokens" icon="key" href="/api/tokens">
    Create, list, and delete Personal Access Tokens programmatically.
  </Card>
</CardGroup>

## Response format

All endpoints return standard HTTP status codes. Successful responses return JSON. Error responses return JSON with at least a `message` field describing the problem.

| Code | Meaning                                  |
| ---- | ---------------------------------------- |
| 200  | Success                                  |
| 201  | Created                                  |
| 204  | No content (delete operations)           |
| 400  | Bad request (validation error)           |
| 401  | Unauthorized                             |
| 403  | Forbidden                                |
| 404  | Not found                                |
| 409  | Conflict (duplicate or version mismatch) |