canonical: https://jentic.com/apis/reflect.app/reflect # Reflect App reflect The Reflect API appends text to daily notes, creates new notes, and saves bookmarked links in a Reflect graph, the note-taking app's personal knowledge base. It also lists the graphs a user can reach, returns saved links with their highlights, and returns books with their authors and notes. Note endpoints are append-only by design: Reflect encrypts note contents end to end, so its servers cannot read notes back and the API never returns them. Authentication is OAuth with authorization code and PKCE, using read:graph and write:graph scopes. ## For AI agents Append entries to a Reflect daily note, create a new markdown note, save a link, and list a graph's saved links and books, scoped to a graph id. ## Scope Does not return note contents, edit or delete existing notes, or manage tasks and calendars. Use for appending to Reflect notes and reading saved links and books only. ## Capabilities - Append a line to a Reflect daily note with PUT `/graphs/{graphId}/daily-notes` using transform_type list-append - Append under a named list in the daily note by passing list_name, using [[List Name]] to backlink - Create a new note from a subject and content_markdown, optionally pinned, with POST `/graphs/{graphId}/notes` - Save a bookmarked link with its url, title, and description to a graph via POST `/graphs/{graphId}/links` - List saved links with their highlights from GET `/graphs/{graphId}/links` - Return books with their title, authors, and notes from GET `/graphs/{graphId}/books` - Find the graph ids a user can write to with GET /graphs and GET `/users/me` ## Use cases ### Agent journaling into Reflect through Jentic A personal assistant agent that ends each work session by writing what happened needs a safe path into the user's notes. Through Jentic the agent searches for 'append to my daily note', loads PUT `/graphs/{graphId}/daily-notes`, and sends the text with transform_type list-append and an optional list_name such as Updates. Because Reflect's note endpoints are append-only, the agent can add entries but cannot read or overwrite existing note contents. Example prompt: Call GET /graphs to find the graphId, then PUT `/graphs/{graphId}/daily-notes` with text 'Shipped the billing fix', transform_type 'list-append', and list_name '[[Updates]]' ### Capturing research as new notes A research agent that has summarised a set of sources can file the result as its own note. POST `/graphs/{graphId}/notes` takes a subject and content_markdown, with pinned set to true for notes that should stay at the top, and returns the new note's id and timestamps. The markdown body keeps headings, lists, and backlinks intact inside Reflect. Example prompt: POST `/graphs/{graphId}/notes` with subject 'Vector database comparison' and content_markdown containing the summary, with pinned set to true ### Read-later link capture Links shared in chat or found while browsing can go straight into Reflect. POST `/graphs/{graphId}/links` saves a link object with its url, title, and description, and GET `/graphs/{graphId}/links` returns saved links with their highlights and updated_at timestamps, so an agent can build a weekly digest of what was saved. Example prompt: POST `/graphs/{graphId}/links` with url 'https://example.com/post' and title 'Post title', then GET `/graphs/{graphId}/links` and list links updated this week ### Book notes digest Readers who keep book notes in Reflect can have an agent surface them. GET `/graphs/{graphId}/books` returns each book's title, authors, and notes, where each note carries a type plus optional page, location, and value, which is enough to assemble a quote digest or flashcards. Example prompt: Call GET `/graphs/{graphId}/books` and return the notes for the book whose title matches 'Thinking in Systems' ## Key endpoints | Method | Path | Description | | --- | --- | --- | | PUT | `/graphs/{graphId}/daily-notes` | Append to a daily note | | POST | `/graphs/{graphId}/notes` | Create a note | | POST | `/graphs/{graphId}/links` | Save a link | | GET | `/graphs/{graphId}/links` | List saved links | | GET | `/graphs/{graphId}/books` | List books and their notes | | GET | `/graphs` | List graphs | | GET | `/users/me` | Read the current user | ## Key resources - **Graphs** — List the graphs a user can access; every other resource lives under a graph id - **Daily notes** — Append text to the daily note for a date, optionally under a named list - **Notes** — Create a new note from a subject and markdown content - **Links** — Save bookmarked links and list them with highlights - **Books** — List books with authors and notes - **Users** — Read the current user's uid, email, name, and graph_ids ## AI readiness This API is usable in Jentic One now. Its AI-readiness score against Jentic's framework shows where it stands today and where improvements would make it even easier for agents to use. - **Score:** 0 / 100 - **Maturity:** Non-Ready - **Dimensions:** - Foundational Compliance: 100 / 100 - Developer Experience & Jentic Compatibility: 57 / 100 - AI-Readiness & Agent Experience: 10 / 100 - Agent Usability: 94 / 100 - Security: 90 / 100 - AI Discoverability: 0 / 100 - **View full report:** https://jentic.com/apis/reflect.app/reflect/scorecard - **How the score is calculated:** https://docs.jentic.com/reference/api-readiness-framework/overview/ - **More about the dimensions:** https://docs.jentic.com/reference/api-readiness-framework/specification/#dimensional-model-overview ### Score it yourself Every API in the directory is allowlisted, so you can re-score it with no key required. - **Score your own API:** https://jentic.com/scorecard.md - **Scoring CLI agent skill:** https://github.com/jentic/jentic-api-scorecard/blob/main/skills/jentic-api-scorecard/SKILL.md ```sh npx @jentic/api-scorecard-cli score ``` ## Why Jentic - **Setup:** Wiring Reflect by hand means registering OAuth credentials in its developer settings, running the authorization-code flow with PKCE or generating a token, and resolving the graph id before any write. Through Jentic you install once, import Reflect from the API Directory, store the token once, and your agent calls it. - **Permission scoping:** Reflect puts the graph id in the URL path (`/graphs/{graphId}/...`), so a rule can pin your agent to one graph and the operations you pick. You choose the operations it may call, so writes like creating notes or saving links are not included unless you add them. - **Credential handling:** Your Reflect access token is stored once, encrypted, by your own Jentic One instance and injected at execution time. It never enters the agent's prompt, logs, or context. - **Discovery method:** Agents search Jentic by intent such as 'append to my daily note' or 'save a link to Reflect', and Jentic returns the matching Reflect operation with its input schema so the agent calls the right endpoint without browsing the reference docs. ## Related APIs - **Notion API** — Workspace pages and databases with full read and write access to content - **Evernote API** — Long-standing note service with notebooks and searchable notes - **Raindrop.io API** — Dedicated bookmark manager with collections and tags ## FAQ ### What authentication does the Reflect API use? Per its OpenAPI spec, the Reflect API uses OAuth with the authorization code flow, declared as the reflect_auth scheme with read:graph and write:graph scopes, and PKCE is supported. Reflect's developer settings can also generate an access token directly, which works much like an API key and is sent as a bearer token. Through Jentic, that token is stored encrypted by your own Jentic One instance and injected at call time. ### Can I read my Reflect notes with the API? No. Reflect encrypts note contents end to end, so its servers cannot read them and the note endpoints are append-only: you can append to a daily note or create a new note, but not fetch note text. The read endpoints cover graphs, saved links, books, and the current user. ### What are the rate limits for the Reflect API? The OpenAPI spec does not specify rate limits. Check Reflect's developer pages at https://reflect.app/developer/oauth for current guidance before running bulk link imports. ### Is there a Reflect MCP server? You don't need an MCP server to give your agent Reflect. Jentic connects it directly from the API Directory: import it, store your access token once, and your agent calls the note and link operations it needs, discovered on demand rather than loaded into its context up front. ### How do I append to today's daily note through Jentic? Search Jentic for 'append to my daily note', load PUT `/graphs/{graphId}/daily-notes`, and send text with transform_type set to list-append; date defaults to today and list_name is optional. Get the graphId first from GET /graphs. To run it on your own infrastructure, install Jentic One from its GitHub repo. ### Can I limit what my agent is allowed to do with the Reflect API? Yes. Write a rule that allows only PUT on `/graphs/abc123/daily-notes`, and the agent can add entries to that graph's daily notes and nothing else: no new notes, no link writes, no other graph. Every call it makes is logged.