Collected Notes

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.

Contents

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: your@email.com 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://photos.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: your@email.com 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: your@email.com 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: your@email.com 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: your@email.com 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: your@email.com 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: your@email.com 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: your@email.com 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: your@email.com 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: your@email.com 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: your@email.com 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: your@email.com 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: your@email.com 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: your@email.com your-secret-token" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
https://collectednotes.com/accounts/me

Response:

{
  "id": 14,
  "email": "your@email.com",
  "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? support@collectednotes.com

almost 4 years ago

Collected Notes
Links on this note ↗