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 (#overview) Authentication (#authentication) Resources (#resources) Notes (#notes) Fetch latest notes from a site (#fetch-latest-notes-from-a-site) Notes in different formats (#you-can-get-a-note-in-different formats) Note properties (#notes-properties) Create a note (#create-a-note) Create a Note simplified (#create-a-note-simplified) Update a note (#update-a-note) Delete a note (#delete-a-note) Search notes (#search-notes) Reorder notes (#reorder-notes) Get the list of links from a note (#note-links) Get the list of references to a note (#note-references) Get the rendered body of a note (#get-the-rendered-body-of-a-note) Sites (#sites) Fetch your sites (#fetch-your-sites) Fetch a site (#fetch-a-site) Create a Site (#create-a-site) User (#user) Fetch your user (#fetch-your-user) Webhook (#webhook) Limits (#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 (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 bash 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: ```json [ { "id": 157, "siteid": 1, "userid": 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", "createdat": "2020-05-21T04:15:12.491Z", "updatedat": "2020-05-25T17:17:56.034Z", "visibility": "publicsite", "url": "https://alejandrocrosa.com/collected-notes-tech-stack" }, { "id": 18, "siteid": 1, "userid": 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", "createdat": "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 | | siteid | Integer | | body | String (markdown) | | path | String (from collectednotes.com/path) | | headline | String (Summary of the note's body) | | visibility | String (private, public, publicsite) | | url | String (FQDN of the note)| | createdat | Date Time | | updatedat | Date Time | Sample JSON 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 bash 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: json { "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. bash 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 bash 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 bash 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 bash 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: bash 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 bash 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: json [ { "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. bash 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. bash 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 json { "note": {"..."}, "body": "rendered HTML of your note" } Sites Fetch your sites bash curl -H "Authorization: your@email.com your-secret-token" \ -H "Accept: application/json" \ -H "Content-Type: application/json" \ https://collectednotes.com/sites Response json [ { "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 bash curl -H "Authorization: your@email.com your-secret-token" \ -H "Accept: application/json" \ -H "Content-Type: application/json" \ https://collectednotes.com/alejandro Response json { "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 bash 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: ```json { "id": 2, "userid": 1, "name": "My new Site", "headline": null, "about": null, "host": null, "createdat": "2021-02-06T18:10:58.601Z", "updatedat": "2021-02-06T18:10:58.601Z", "sitepath": "my-site-path", "published": true, "tinyletter": null, "domain": null, "webhookurl": null, "paymentplatform": null, "ispremium": true, "totalnotes": 1 } ``` Site properties | Property | Description | | ----------- | ----------- | | id | Integer | | userid | Integer | | name | String | | headline | String (shown below title) | | domain | String (used for premium accounts with a custom domain) | | sitepath | String (collectednotes.com/sitepath) | | tinyletter | String (prensent if you configured newsletter display)| | createdat | Date Time | | updated_at | Date Time | User Fetch your user bash curl -H "Authorization: your@email.com your-secret-token" \ -H "Accept: application/json" \ -H "Content-Type: application/json" \ https://collectednotes.com/accounts/me Response: json { "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 ======================= 2020-06-05 07:46:32 UTC