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 * 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 * Fetch your sites * Fetch a site * Create a Site * 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/ [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 [https://collectednotes.com/terms]. -------------------------------------------------------------------------------- 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 [https://collectednotes.com/blog/premium] you can obtain yours in your profile page [https://collectednotes.com/accounts/me/token]. 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://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: 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 [https://collectednotes.com/blog/webhooks] -------------------------------------------------------------------------------- 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 [support@collectednotes.com]