API

Collected Notes API makes it easy for you to plug into your notes. Use it to create a writing tool, integrate into an external site, or anything else you can think of.

Overview
Authentication
Resources
- Notes
  - Fetch latest notes from a site
  - [Notes in different formats](#you-can-get-a-note-in-different formats)
  - Note properties
  - Create a note
  - Create a Note simplified
  - Update a note
  - Delete a note
  - Search notes
  - Reorder notes
  - Get the list of links from a note
  - Get the list of references to a note
  - Get the rendered body of a note
- Sites
- User
  - Fetch your user
Webhook
Limits

Overview

The Collected Notes API is (mostly) a JSON-based API. All requests are made to endpoints beginning: https://collectednotes.com/

All requests must be secure, i.e. https, not ~~http~~.

Developer agreement By using our API, you agree to our terms of service.

Authentication

In order to publish on behalf of a Collected Notes account, you will need an API token. An API token grants limited access to a user’s account. If you have a premium account you can obtain yours in your profile page.

You can then send the token as part of every http request: curl -H 'Authorization: email token' https://collectednotes.com/...

Resources

The API is RESTful and arranged around resources. All requests must be made with an API token. All requests must be made using https.

Notes

Fetch latest notes from a site

curl -H "Authorization: [email protected] your-secret-token" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
https://collectednotes.com/sites/1/notes?page=1

Response:

[
  
  {
    "id": 157,
    "site_id": 1,
    "user_id": 1,
    "body": "# Collected Notes tech stack..",
    "path": "collected-notes-tech-stack",
    "headline": "Swift\nNative experiences are superior in many ways. Using Swift was the right choice. I did try to implement it ...",
    "title": "Collected Notes tech stack",
    "created_at": "2020-05-21T04:15:12.491Z",
    "updated_at": "2020-05-25T17:17:56.034Z",
    "visibility": "public_site",
    "url": "https://alejandrocrosa.com/collected-notes-tech-stack"
  },
  {
    "id": 18,
    "site_id": 1,
    "user_id": 1,
    "body": "# roadmap...",
    "path": "roadmap",
    "headline": "Collected Notes https://images.collectednotes.com/photos/1/f7ca8230-b4cb-49b9-9294-4de10192ccb5\nHere’s a complete list of features ...",
    "title": "roadmap",
    "created_at": "2020-05-16T20:23:59.721Z",
    "updated_at": "2020-06-02T06:22:07.371Z",
    "visibility": "public",
    "url": "https://alejandrocrosa.com/roadmap"
  }
]

You can get a note in different formats:

curl https://collectednotes.com/blog/premium.json as JSON curl https://collectednotes.com/blog/premium.text as Text curl https://collectednotes.com/blog/premium.md as Markdown

Notes properties

Property	Description
id	Integer
site_id	Integer
body	String (markdown)
path	String (from collectednotes.com/path)
headline	String (Summary of the note's body)
visibility	String (private, public, public_site)
url	String (FQDN of the note)
created_at	Date Time
updated_at	Date Time

Sample JSON

{
  "id": 1072,
  "site_id": 13,
  "user_id": 14,
  "body": "# ⚡️ Premium \n\nPersonalize your Collected Notes experience, remove limits and unlock the power of your notes. **It's just $5/month or $50/year.**\n\n###Custom domains with SSL\nYou can use your own domain to host your notes. The branding is removed and additional features are enabled (ex. RSS feed). Update your blog using your notes!",
  "path": "premium",
  "headline": "Personalize your Collected Notes experience, remove limits and unlock the power of your notes. It's just $5/month or $50/year.\n...",
  "title": "⚡️ Premium",
  "created_at": "2020-06-05T07:29:05.471Z",
  "updated_at": "2020-06-05T07:43:16.986Z",
  "visibility": "private",
  "url": "https://collectednotes.com/blog/premium"
}

Create a note

curl -H "Authorization: [email protected] your-secret-token" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
https://collectednotes.com/sites/1/notes \
-d '{"note": {"body": "# My new note title\nThis is the body", "visibility": "private"}}'

Remember to prepend the body with “# your title”, that way the title and path is extracted correctly.

Response:

{
  "id": 2,
  "site_id": 1,
  "user_id": 1,
  "body": "# My new note title\nThis is the body",
  "path": "my-new-note-title",
  "headline": "This is the body",
  "title": "My new note title",
  "created_at": "2020-06-05T09:42:25.695Z",
  "updated_at": "2020-06-05T09:42:25.695Z",
  "visibility": "private",
  "url": "https://collectednotes.com/blog/my-new-note-title"
}

Create a Note simplified

You can also create notes by calling the endpoint /notes/add this endpoint doesn't require a site_id and it will automatically add the note to the first site you have configured.

curl -H "Authorization: [email protected] your-secret-token" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
https://collectednotes.com/notes/add \
-d '{"note": {"body": "# My new note title\nThis is the body", "visibility": "private"}}'

Update a note

curl -X PUT -H "Authorization: [email protected] your-secret-token" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
https://collectednotes.com/sites/1/notes/2 \
-d '{"note": {"body": "# My new note title\nThis is the body", "visibility": "public"}}'

Delete a note

curl -X DELETE -H "Authorization: [email protected] your-secret-token" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
https://collectednotes.com/sites/1/notes/2

Search notes

curl -X GET -H "Authorization: [email protected] your-secret-token" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
https://collectednotes.com/sites/1/notes/search?term=your+term&page=1

Reorder notes

Send the sorted array of Note ids:

curl -X GET -H "Authorization: [email protected] your-secret-token" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
https://collectednotes.com/sites/1/notes/reorder?ids=[1,2,3]

Note Links

Get the list of links that are contained in a note

curl -X GET -H "Authorization: [email protected] your-secret-token" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
https://collectednotes.com/sites/1/notes/2/links.json

Sample JSON for links:

[
  {
    "id": 1,
    "note_id": 2,
    "url": "https://google.com",
    "kind": "external",
    "host": "google.com",
    "title": "",
    "created_at": "2020-07-01T17:30:51.287Z",
    "updated_at": "2020-07-01T17:30:51.287Z"
  },
  {
    "id": 2,
    "note_id": 2,
    "url": "https://collectednotes.com/blog",
    "kind": "internal",
    "host": "collectednotes.com",
    "title": "",
    "created_at": "2020-07-01T17:30:51.288Z",
    "updated_at": "2020-07-01T17:30:51.288Z"
  }
]

You can get the list of links in HTML too:

curl https://collectednotes.com/sites/1/notes/2/links

Note References

Get the list of notes that contain a link that references a particular note.

curl -X GET -H "Authorization: [email protected] your-secret-token" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
https://collectednotes.com/sites/1/notes/2/references.json

This endpoint returns a list of Notes.

Get the rendered body of a note

Sometimes you just want the rendered body of a note to inject the HTML into your static website for example.

curl -X GET -H "Authorization: [email protected] your-secret-token" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
https://collectednotes.com/sites/1/notes/2/body

{  
  "note": {"..."},
   "body": "rendered HTML of your note"
}

Sites

Fetch your sites

curl -H "Authorization: [email protected] your-secret-token" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
https://collectednotes.com/sites

Response

[
  {
    "id": 13,
    "user_id": 14,
    "name": "Collected Notes",
    "headline": "Simply your thoughts.",
    "about": "",
    "host": null,
    "created_at": "2020-05-20T00:21:15.627Z",
    "updated_at": "2020-06-05T07:44:13.909Z",
    "site_path": "blog",
    "published": true,
    "tinyletter": "",
    "domain": ""
  }
]

Currently only one site per account is supported. This might change in the future.

You can get your site represented in different formats too: curl https://collectednotes.com/blog.json as JSON curl https://collectednotes.com/blog.rss as an RSS feed containing the site info, plus the latest posts. curl https://collectednotes.com/blog.md as Markdown

Fetch a site

curl -H "Authorization: [email protected] your-secret-token" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
https://collectednotes.com/alejandro

Response

{
  "site": {
    "id": 1,
    "user_id": 1,
    "name": "Alejandro’s Notes",
    "headline": "This is my personal website",
    "about": "I’m a Software Engineer",
    "host": null,
    "created_at": "2020-05-17T04:58:32.571Z",
    "updated_at": "2020-06-02T22:10:29.429Z",
    "site_path": "alejandro",
    "published": true,
    "tinyletter": "",
    "domain": "alejandrocrosa.com"
  },
  "notes": [
    {
      "id": 144,
      "site_id": 1,
      "user_id": 1,
      "body": "# ⚡️ Premium \n\nPersonalize your Collected Notes experience...",
      "path": "premium",
      "headline": "Personalize your Collected Notes experience, remove limits and unlock the power of your notes. It's just $5/month or $50/year.\n...",
      "title": "⚡️ Premium",
      "created_at": "2020-06-05T08:55:53.459Z",
      "updated_at": "2020-06-05T08:57:28.069Z",
      "visibility": "public",
      "url": "https://alejandrocrosa.com/premium"
    }
  ]
}

Create a site

curl -H "Authorization: [email protected] your-secret-token" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
https://collectednotes.com/sites\
-d '{"site": {"name": "My new Site", "site_path": "my-site-path"}}'

Response:

{
  "id": 2,
  "user_id": 1,
  "name": "My new Site",
  "headline": null,
  "about": null,
  "host": null,
  "created_at": "2021-02-06T18:10:58.601Z",
  "updated_at": "2021-02-06T18:10:58.601Z",
  "site_path": "my-site-path",
  "published": true,
  "tinyletter": null,
  "domain": null,
  "webhook_url": null,
  "payment_platform": null,
  "is_premium": true,
  "total_notes": 1
}

Site properties

Property	Description
id	Integer
user_id	Integer
name	String
headline	String (shown below title)
domain	String (used for premium accounts with a custom domain)
site_path	String (collectednotes.com/site_path)
tinyletter	String (prensent if you configured newsletter display)
created_at	Date Time
updated_at	Date Time

User

Fetch your user

curl -H "Authorization: [email protected] your-secret-token" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
https://collectednotes.com/accounts/me

Response:

{
  "id": 14,
  "email": "[email protected]",
  "name": "",
  "role": "premium",
  "banned": false,
  "avatar_key": "1/avatar",
  "created_at": "2020-05-19T23:39:05.496Z",
  "updated_at": "2020-06-05T09:23:27.062Z"
}

webhook

Learn all about web hooks here

Limits

We'll do a best effort to allow you a reasonable number of requests to our service. We track each API request you make and might suspend your API access if we see it's using more than it should. We are going to define more strict SLA's to our API's in the future.

Questions? [email protected]

API

Contents

Overview

Authentication

Resources

Notes

Fetch latest notes from a site

You can get a note in different formats:

Notes properties

Sample JSON

Create a note

Create a Note simplified

Update a note

Delete a note

Search notes

Reorder notes

Note Links

Note References

Get the rendered body of a note

Sites

Fetch your sites

Fetch a site

Create a site

Site properties

User

Fetch your user

webhook

Limits