canonical: https://jentic.com/apis/collectednotes.com/collectednotes

# Collected Notes API

Collected Notes is a minimalist writing platform whose API lets developers and agents create, update, search, and publish notes against one or more authored sites. The API exposes 14 endpoints covering note CRUD, full-text search, reorder, link extraction, back-reference lookups, rendered HTML retrieval, and site management. Authentication is via an Authorization header containing a paired email and personal token, scoped to the authenticated user.

## For AI agents

Create, update, search, and publish notes on Collected Notes sites and read rendered HTML, links, and back-references through 14 endpoints.

## Scope

Does not handle multi-author workflows, page templating, or e-commerce - use for personal markdown note publishing and reading only.

## Capabilities

- Publish a new note with markdown body and visibility flag via POST `/sites/{site_id}/notes`
- Update an existing note's title, body, or visibility via PUT `/sites/{site_id}/notes/{note_id}`
- Full-text search across a site's notes via GET `/sites/{site_id}/notes/search`
- Pull a note's rendered HTML body for embedding via GET `/sites/{site_id}/notes/{note_id}/body`
- List outbound links and inbound back-references for a note via /links.json and /references.json
- Reorder notes within a site via GET `/sites/{site_id}/notes/reorder`
- Manage sites: list, create, and fetch by path via /sites and /{site_path}

## Use cases

### Headless CMS for a Personal Site

Use Collected Notes as a headless CMS by publishing notes via POST `/sites/{site_id}/notes` and rendering them on a custom front-end with the HTML returned from `/sites/{site_id}/notes/{note_id}/body.` Each note carries markdown source plus rendered output, so a Next.js or Astro site can fetch content at build time or on demand without running a database. Visibility flags control which notes are public.

Example prompt: Call POST `/sites/{site_id}/notes` with body containing markdown and visibility='public', then fetch GET `/sites/{site_id}/notes/{note_id}/body` for the rendered HTML to embed on a Next.js page

### AI-Generated Drafts and Updates

Drive content creation from an LLM by generating markdown and posting it via POST `/notes/add` (which auto-selects the first site) or POST `/sites/{site_id}/notes` for explicit targeting. Subsequent revisions use PUT `/sites/{site_id}/notes/{note_id}` so the same note evolves over time. This pattern supports newsletters, daily briefings, and AI-assisted documentation.

Example prompt: Generate a 300-word markdown draft, call POST `/notes/add` with body and title, then if revisions are needed call PUT `/sites/{site_id}/notes/{note_id}` with the updated body

### Knowledge Graph Across Notes

Build a back-reference map of a knowledge base by walking each note's outbound links via GET `/sites/{site_id}/notes/{note_id}/links.json` and incoming references via /references.json. Collected Notes exposes both directions of the link graph natively so an agent can answer 'what notes link to this concept?' without reparsing markdown.

Example prompt: Call GET `/sites/{site_id}/notes/{note_id}/references.json` to list all notes that reference the target, then return their titles and IDs

### AI Agent Note Publishing via Jentic

Let an LLM agent publish or update notes on a Collected Notes site by searching Jentic for the operation and executing it. The Authorization header (email + token) is held in your Jentic One instance and injected at execution so the agent never sees the credential. Useful for daily summary publishing, lab notebooks, and automated documentation pipelines.

Example prompt: Use Jentic to search 'create a note', load the POST `/sites/{site_id}/notes` schema, and execute it with the generated markdown body

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| POST | `/sites/{site_id}/notes` | Create a note on a site |
| PUT | `/sites/{site_id}/notes/{note_id}` | Update an existing note |
| DELETE | `/sites/{site_id}/notes/{note_id}` | Delete a note |
| GET | `/sites/{site_id}/notes/search` | Search notes within a site |
| GET | `/sites/{site_id}/notes/{note_id}/body` | Get rendered HTML body for a note |
| GET | `/sites/{site_id}/notes/{note_id}/references.json` | List notes that reference this note |
| GET | `/sites` | List your authored sites |

## Key resources

- **Notes** — Create, read, update, delete, search, and reorder notes within a site
- **Sites** — List, create, and fetch authored sites by ID or path
- **Note Body** — Pre-rendered HTML for embedding in custom front-ends
- **Links and References** — Outbound links and inbound back-references for any note
- **User Profile** — The authenticated user's profile information

## Why Jentic

- **Setup:** Wiring Collected Notes by hand means building its Authorization header from your email plus token on the collectednotes.com host and handling the note create, update, and search endpoints yourself. Through Jentic you install once, import Collected Notes from the API Directory, store the credential once, and your agent calls it.
- **Permission scoping:** Collected Notes puts the site id in the URL path (`/sites/{site_id}/notes/...`), so a rule can pin your agent to one site: it can read and search notes there and nothing else. You choose the operations it may call, so write actions like updating or deleting a note are not included unless you add them.
- **Credential handling:** Your Collected Notes email and token are stored once, encrypted, by your own Jentic One instance and injected into the Authorization header at execution time. They never enter the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'create a note' or 'search notes on a site', and Jentic returns the matching Collected Notes operation with its input schema so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **Ghost Content API** — Headless publishing platform with richer theming and member features
- **Notion API** — Block-based knowledge base with databases and rich content types
- **Forem (DEV.to) API** — Cross-post the same markdown to a developer community

## FAQ

### What authentication does the Collected Notes API use?

Every request requires an Authorization header in the format 'email token', combining the account email and a personal access token. Through Jentic both values live in the encrypted vault and are injected at execution so the credential never enters the agent's prompt.

### Can I publish a note without specifying a site ID?

Yes. POST `/notes/add` creates a note and automatically targets your first site, which is convenient for single-site users. For multi-site accounts use POST `/sites/{site_id}/notes` with the explicit site ID.

### Does Collected Notes return rendered HTML or only markdown?

Both. Notes are authored in markdown but GET `/sites/{site_id}/notes/{note_id}/body` returns the rendered HTML, so a custom front-end can embed it directly without running a markdown processor.

### What are the rate limits for the Collected Notes API?

The OpenAPI spec does not enumerate explicit rate limits. Limits are enforced server-side; requests that exceed them return HTTP 429. For production workloads cache rendered bodies and search results when possible.

### How do I publish an AI-generated note through Jentic?

Search Jentic for 'create a note', load the POST `/sites/{site_id}/notes` schema, and execute it with body, title, and visibility. Jentic injects the Authorization header from the vault and returns the created note's ID and URL.

### Can I query the back-references for a note?

Yes. GET `/sites/{site_id}/notes/{note_id}/references.json` returns notes that link to the target, and /links.json returns its outbound links. Together they expose the bidirectional link graph for knowledge-base use cases.

### Can I limit what my agent is allowed to do with the Collected Notes API?

Yes. Because you run Jentic One yourself, your own rules decide which Collected Notes operations and credentials the agent may use. Since the site id lives in the URL path (`/sites/{site_id}/notes/...`), a rule can pin the agent to a single site and grant only read and search on it, such as GET `/sites/{site_id}/notes/search`, while withholding write operations like POST `/sites/{site_id}/notes` or DELETE `/sites/{site_id}/notes/{note_id}.` Those write actions run only when you add them to the agent's allowed set.