Visión general de la API REST

Explora la API REST pública de SNotes: aprende sobre autenticación, URL base, paginación, límites de petición y gestión de errores para tus integraciones.

The SNotes Public REST API allows authorized third-party applications, background jobs, and developer tools to interact with notes, checklists, and collections.

Base URL

All requests to the Cloud SNotes Public API are served over HTTPS:

https://api.snotes.io/v1/public/

If you are running a self-hosted instance of SNotes, replace https://api.snotes.io with your backend hostname (for example, https://api.yourdomain.com).

Notice the /v1/public/ path segment. Internal web app endpoints (/v1/notes/ and /v1/collections/) use browser session cookies, whereas external developer integrations use /v1/public/ with personal API tokens.

Plan Requirements

Access to the Public REST API requires the Pro plan with the api feature flag enabled.

If your account is on the Free plan, API requests return an HTTP 403 Forbidden response with a code indicating that an upgrade is required.

Request & Response Format

Content-Type: Always send Content-Type: application/json for requests containing a JSON payload (POST, PATCH).
Encoding: UTF-8.
Field names: JSON request and response bodies use camelCase (e.g. noteType, createdAt, isPinned).
Dates & Times: Formatted according to ISO 8601 UTC strings (e.g. 2026-08-18T14:30:00Z).
Identifiers: All note, collection, and checkbox IDs are RFC 4122 standard UUIDs (e.g. 9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d).

Pagination

All list endpoints (GET /v1/public/notes/, GET /v1/public/collections/, etc.) use limit-offset pagination.

Query Parameters

Parameter	Type	Default	Max	Description
`limit`	`integer`	`20`	`100`	Number of results to return in one page.
`offset`	`integer`	`0`	—	Number of initial results to skip.

Paginated Response Structure

{
  "count": 42,
  "next": "https://api.snotes.io/v1/public/notes/?limit=20&offset=20",
  "previous": null,
  "results": [
    {
      "id": "c7a8d438-e6fc-4632-9df6-2e8bf535bfd9",
      "noteType": "text",
      "title": "Meeting Notes",
      "content": "Discussed roadmap and API launch.",
      "color": "#fef08a",
      "isPinned": true,
      "archived": false,
      "trashedAt": null,
      "createdAt": "2026-08-18T10:00:00Z",
      "updatedAt": "2026-08-18T10:30:00Z"
    }
  ]
}

Rate Limiting

The Public API enforces rate limits on a per-token basis to protect service availability:

Public API requests are subject to the public_api rate limit throttle.
If you exceed the rate limit, the server responds with HTTP 429 Too Many Requests containing a Retry-After header indicating how many seconds to wait before retrying.

HTTP Status Codes

Status Code	Meaning	Description
`200 OK`	Success	The request succeeded and the requested data is returned.
`201 Created`	Created	A new note, collection, or checklist item was successfully created.
`204 No Content`	Deleted	The resource was permanently deleted (no body returned).
`400 Bad Request`	Validation Error	The request parameters or body were invalid.
`401 Unauthorized`	Auth Failed	Missing, malformed, or invalid API token.
`403 Forbidden`	Permission Denied	The account lacks the Pro `api` feature or access to the resource.
`404 Not Found`	Not Found	The requested note, collection, or item does not exist or was deleted.
`409 Conflict`	Conflict	Optimistic lock collision (`expectedUpdatedAt`) or duplicate unique name.
`429 Too Many Requests`	Throttled	Rate limit exceeded.
`500 Server Error`	Internal Error	An unexpected server error occurred.

Error Handling

When an error occurs, the response contains a JSON object explaining the cause:

{
  "detail": "This note was changed elsewhere. Reload and try again."
}

For validation errors on specific fields:

{
  "title": ["This field may not be blank."],
  "color": ["Enter a valid hex color code like #fde68a."]
}

REST API Overview