Preview — not yet GA. The Open Notes public API is actively iterating.
Endpoints, payload shapes, and scope names may change without a deprecation
window until we announce general availability. The Discourse plugin (our
reference implementation) is the best signal of which endpoints are stable
in production today.
About this reference
Every endpoint documented here is auto-generated fromopenapi-public.json
— the public API surface exported by opennotes-server. The schema is regenerated
locally with mise run docs:regenerate-openapi and committed alongside the docs.
All endpoints share the base path /api/public/v1/ and require a bearer token with
the platform:adapter scope. See Authentication and
Conventions for the shared rules that apply to every call.
Where to start
If you are building an integration for the first time, the narrative entry point is the Integration Guide walkthrough. It explains the public API contract, auth flow, and the full sequence across endpoints before you dive into the per-endpoint reference. The Discourse plugin is the canonical reference implementation. Every public endpoint is exercised by the plugin in production, so the plugin’s source code is the best signal for which fields and flows are stable today.Endpoint groups
| Group | What it covers |
|---|---|
| Requests | Submit content for moderation; retrieve and update request state |
| Notes | Create, read, update, force-publish, and dismiss community notes |
| Ratings | Rate notes; retrieve per-note ratings and aggregate stats |
| Moderation Actions | Record and query actions taken on content or users |
| Community Servers | Look up and retrieve community server records |
| User Profiles | Look up user profile records by platform identity |
Requests
Submit a piece of content for moderation (POST /api/public/v1/requests), poll its
state, and handle the resulting moderation action. The Discourse plugin submits every
flagged post as a Request and then applies the returned ModerationAction back to
the post. See the walkthrough step 3
for the full flow.
Notes
Community notes are the scored text explanations attached to content under review. Your integration may create notes on behalf of community members and dismiss notes that are no longer relevant. AI-generated notes are triggered viaPOST /api/public/v1/requests/{request_id}/ai-notes.
Ratings
Ratings drive the helpfulness score that determines whether a note is published. Your integration submits ratings from community members and can read aggregate stats to surface note quality signals in the platform UI.Moderation Actions
Moderation actions represent decisions taken on content — approve, remove, escalate, etc. Actions are created by the server after evaluating request state and note scores, and your integration applies them to the platform. Integrations may also submit actions directly for platform-originated moderation events.Community Servers
Look up the Open Notes server record for a given platform community usingGET /api/public/v1/community-servers/lookup. The server record holds configuration
that governs tier assignment and moderation behavior. See
Onboarding: Manage instances for
registration details.
User Profiles
Look up a user profile by platform identity usingGET /api/public/v1/user-profiles/lookup. Profiles carry cross-platform identity
state and integration-supplied metadata. See
Walkthrough step 1: Identify user
for how to resolve a profile before submitting a request.