The external API accesses notes synced to the connected account's cloud storage. It cannot read unsynced local notes.
Base URL: https://api.noolingo.com/api. Create or refresh an API key in account settings, then send Authorization: Bearer YOUR_API_KEY. Refreshing replaces the previous key. Never put keys in URLs, conversations, public source code, or plugin packages.
API keys authorize account-level note reading, writing and deletion. Third-party applications can use separate OAuth authorization instead of requesting the user's API key.
| Method | Path | Purpose |
|---|---|---|
| GET | /me | Account details including email, phone and entitlements; call only when needed |
| GET | /notes | List notes, most recently updated first |
| GET | /notes/:noteId | Read an account-owned note |
| POST | /notes | Create a note; id, _id and noteId are prohibited |
| PUT | /notes/:noteId | Update supplied fields; id is immutable |
| DELETE | /notes/:noteId | Permanently delete a note |
List parameters: limit defaults to 20 (1–1000); offset defaults to 0 (0–100000). Optional deck_id and tag apply exact filters. Full-text search is not supported. Responses have {"success":true,"data":[...]}, without total. Advance offset by the returned count until an empty page. Concurrent edits can cause offset pagination to repeat or skip notes.
Create/update fields: title (up to 300 characters), markdown_text (recommended, up to 50000), legacy html_text (up to 50000), tags (up to 20 strings of 1–100 characters), deck_id (an account-owned deck), priority (integer 0–100), and the legacy numeric recall field. recall is not a review-scoring endpoint.
Creation requires nonempty content. Updates may contain tags only. The optional deck_id query parameter takes precedence over the body. An omitted deck on creation is null; it does not create a notebook. Mutations participate in the existing cloud sync change log.
POST /api/notes
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
{"title":"Retrieval practice","markdown_text":"{{Retrieval practice}} supports long-term memory.","tags":["study"]}
Single-note response:
{"success":true,"data":{"id":"note-id","title":"Retrieval practice","markdown_text":"{{Retrieval practice}} supports long-term memory.","tags":["study"],"deck_id":null,"created_at":1792368000000,"updated_at":1792368000000}}
Timestamps are epoch milliseconds. Optional fields appear only when present. Creation returns 201; successful reads, updates and deletion return 200. Errors use {"success":false,"message":"ERROR_CODE"}. Status codes include 400 (validation/business error), 401, 404, 413 (body too large), 429 and 500. The body limit is 128 KiB. The current single-process REST entry budget is 300 requests per source per minute; shared exits share the budget. Cloud note quotas also apply to creation.
Handle INVALID_NOTE, INVALID_QUERY, DECK_NOT_FOUND and CLOUD_NOTE_QUOTA_EXCEEDED by correcting the input or informing the user. For retryable creation, send Idempotency-Key (16–128 letters, digits, underscores or hyphens). Reuse the same key and identical content on retries; different content returns IDEMPOTENCY_CONFLICT. Without a key, do not blindly retry creation.
OAuth grants access directly to the REST API and coexists with API keys. Applications must be registered by a maintainer. There is no open dynamic registration. Contact [email protected] with your application name, exact HTTPS redirect URIs and required scopes.
| Scope | Allowed operation |
|---|---|
| notes:read | GET /notes and /notes/:noteId |
| notes:create | POST /notes |
| notes:update | PUT /notes/:noteId |
| notes:delete | DELETE /notes/:noteId, permanent deletion |
| profile:read | GET /me, including email, phone and account details |
Request the least privilege needed. OAuth is scope-limited; API keys remain account-level credentials. Insufficient scope returns 403 OAUTH_INSUFFICIENT_SCOPE. Invalid or revoked OAuth access returns 401 OAUTH_TOKEN_INVALID.
https://api.noolingo.com/.well-known/oauth-authorization-serverhttps://api.noolingo.com/.well-known/oauth-protected-resource/apihttps://api.noolingo.com/apiPre-registered public clients use token endpoint authentication method none and authorization code + PKCE S256. Implicit, client_credentials, and exchanging API keys for OAuth tokens are unsupported. Production client IDs and callback URLs must be registered; example values do not grant access.
Authorization requires response_type=code, client_id, an exactly registered redirect_uri, resource, space-delimited scope, state, code_challenge and code_challenge_method=S256. The user signs into Noolingo, reviews the application and permissions, and approves explicitly. Validate state and iss on the callback.
Codes expire after five minutes and are single-use. Exchange using an application/x-www-form-urlencoded POST containing grant_type=authorization_code, code, client_id, redirect_uri, resource and code_verifier. Successful responses include access_token, refresh_token, token_type=Bearer, expires_in=3600 and scope.
Call the API with Authorization: Bearer ACCESS_TOKEN, never a token in a URL. Access tokens last one hour and grants last at most 30 days. Refresh using grant_type=refresh_token, refresh_token, client_id and resource; scope may reduce existing permissions. Refresh tokens rotate; replay of a consumed refresh token revokes the grant. Avoid concurrent refresh requests.
POST /oauth/revoke with form fields token (an access or refresh token) and client_id to revoke a grant. Users may also use Connected apps. Revocation stops future access but does not delete saved notes or recall data already received by the third party.
See the OAuth integration guide, Privacy policy and Terms.