Skip to main content

​
Response envelope

All /api/public/v1/ endpoints follow JSON:API 1.1. Every response body has this top-level structure: 
{
  "jsonapi": { "version": "1.1" },
  "data": { ... },
  "links": { ... },
  "meta": { ... }
}
data is a single resource object for singular responses and an array for list responses. links and meta are omitted when empty.

​
Resource object

Each resource object has a type, an id, and an attributes object: 
{
  "type": "notes",
  "id": "01926b7f-...",
  "attributes": {
    "summary": "...",
    "status": "NEEDS_MORE_RATINGS",
    ...
  }
}

​
Pagination

List endpoints support page-based pagination via query parameters:
ParameterDefaultMaxDescription
page[number]1—1-indexed page number
page[size]20100Items per page
The response links object carries cursor URLs: 
{
  "links": {
    "self": "/api/public/v1/notes?page[number]=2&page[size]=20",
    "first": "/api/public/v1/notes?page[number]=1&page[size]=20",
    "prev": "/api/public/v1/notes?page[number]=1&page[size]=20",
    "next": "/api/public/v1/notes?page[number]=3&page[size]=20",
    "last": "/api/public/v1/notes?page[number]=12&page[size]=20"
  },
  "meta": {
    "count": 237,
    "page": 2,
    "pages": 12,
    "limit": 20
  }
}
next and prev are null when no further pages exist.

​
Error envelope

Error responses use standard HTTP status codes and carry a JSON body: 
{
  "detail": "Not authenticated"
}
Validation errors (422) include field-level detail: 
{
  "detail": [
    {
      "loc": ["body", "data", "attributes", "summary"],
      "msg": "Field required",
      "type": "missing"
    }
  ]
}
See Concepts: Errors for the full list of error codes and retry guidance.

​
ID formats

​
Server-issued IDs

All IDs generated by Open Notes are UUID v7 strings. UUID v7 is time-ordered, which means IDs sort chronologically and are safe to use as cursor tokens. 
01926b7f-3d2a-7e1f-9c8a-4f0b1c2d3e4f

​
Integration-supplied external IDs

IDs that originate from your platform (user IDs, message IDs, channel IDs, server IDs) are stored as plain strings. Pass them exactly as your platform exposes them — no transformation is applied by Open Notes. 
{
  "platform_user_id": "672345",
  "platform_message_id": "t/some-topic/42",
  "platform_channel_id": "9"
}

​
Timestamps

All timestamps are ISO 8601 strings in UTC: 
2024-10-15T14:32:07.123456Z
created_at and updated_at are present on all resource types. Additional event timestamps (e.g. force_published_at) appear on specific resource types.

​
Filtering

List endpoints that support filtering use bracket notation query parameters: 
GET /api/public/v1/notes?filter[status]=NEEDS_MORE_RATINGS&filter[community_server_id]=<uuid>
Available filter fields are documented per-endpoint in the generated reference. Filters are combined with AND logic; OR is not supported.