| DEVELOPERS

Developers

Your API Keys

Use these keys to authenticate with the Collected Notes API.

You don't have any API keys yet.

CLI Setup & Tools

Configure your CLI and access official tools.

Configure CLI

Store your API token in ~/.collected-notes

echo "your-api-token" > ~/.collected-notes

API Usage

Use your API key with the Authorization header

curl -H "Authorization: Bearer YOUR_API_TOKEN" \
  https://collectednotes.com/sites

Official CLI Tools

Go CLI JavaScript CLI Rust CLI

Public API

v2.0.0

Download Spec

The public read-only API for accessing published content on Collected Notes.

These endpoints are designed for integrations, embeds, static site generators, and any tool that needs to read public note content. No authentication required for public/unlisted content.

Who this is for

Static site generators fetching content from CN
Embeds and widgets showing note content
Third-party readers and aggregators
Anyone building on top of published CN content

For CLI, MCP, and agent integrations

If you need to create, update, delete, search, or sync notes, see the Integration API spec at /api-integration.yaml. That API requires authentication and is used by the cn CLI, MCP clients, and AI agents.

Note Visibility

public — visible to everyone, listed on site
unlisted — accessible via direct link, not listed
private — only accessible to the owner (requires Integration API)
public_unlisted — public but not listed on site

Endpoints

Sites

get/{site_path}.json

Get site with notes

Returns site metadata along with all public notes (listed notes only; unlisted and private notes are excluded). Notes are returned as summaries (no body content).

Parameters

site_path

string

path

required

The site's URL slug

Responses

200

Site data with note summaries

404

Example Response

{
  "id": 42,
  "user_id": 7,
  "site_path": "my-blog",
  "name": "My Blog",
  "headline": "Thoughts on technology",
  "about": "Welcome to my blog",
  "domain": null,
  "created_at": "2024-01-15T10:30:00.000Z",
  "updated_at": "2024-06-20T14:45:00.000Z",
  "notes": [
    {
      "id": 101,
      "site_id": 42,
      "user_id": 7,
      "title": "Getting Started",
      "path": "getting-started",
      "headline": "A beginner's guide",
      "visibility": "public",
      "ordering": 1,
      "tags": [
        "guide",
        "intro"
      ],
      "source": "web",
      "created_at": "2024-03-10T09:00:00.000Z",
      "updated_at": "2024-03-10T09:00:00.000Z"
    }
  ]
}

Notes

get/{site_path}/{note_path}.json

Get note as JSON

Returns a single note with full body content and metadata.

Parameters

site_path

string

path

required

The site's URL slug

note_path

string

path

required

The note's URL slug

Responses

200

Note with body

404

get/{site_path}/{note_path}.md

Get note as Markdown

Returns note content as Markdown with YAML frontmatter.

Parameters

site_path

string

path

required

The site's URL slug

note_path

string

path

required

The note's URL slug

Responses

200

Markdown with frontmatter

404

Example Response

---
title: "Getting Started"
path: "getting-started"
visibility: "public"
created_at: "2024-03-10T09:00:00.000Z"
updated_at: "2024-03-10T09:00:00.000Z"
---

# Getting Started

Content here...

get/{site_path}/{note_path}.txt

Get note as plain text

Returns the note body without formatting.

Parameters

site_path

string

path

required

The site's URL slug

note_path

string

path

required

The note's URL slug

Responses

200

Plain text body

404

get/{site_path}/{note_path}/body

Get rendered note body

Returns the note body rendered as HTML with note metadata.

Parameters

site_path

string

path

required

The site's URL slug

note_path

string

path

required

The note's URL slug

Responses

200

HTML body with metadata

404

Schemas

Site

id

integer

required

user_id

integer

required

site_path

string

required

name

string

headline

string

about

string

domain

string

created_at

string

required

updated_at

string

required

NoteSummary

Note metadata without body

id

integer

required

site_id

integer

required

user_id

integer

required

title

string

required

path

string

required

headline

string

visibility

required

ordering

integer

tags

array

Tags applied to the note

source

string

Where the note was last created/modified (web, ios, cli, api, mcp)

created_at

string

required

updated_at

string

required

Note

NoteBody

body

string

required

HTML-rendered content

note

required

SiteWithNotes

Visibility

Enum Values

public

private

unlisted

public_unlisted

Error

error

string

required