How to create an action for Standard Notes

3 min readJan 2, 2021

Have you recently started to use Standard Notes? Maybe you noticed that it provides few functionalities for your notes. This is not a big problem. Everyone can easily develop extensions like editors, themes, or actions.

In this article, we will look at the basics to develop action for Standard Notes. But first, what is an action?

What is an action?

For this definition, we can use the official documentation.

Actions are menu-based extensions that allow you to build simple APIs that do not require a user interface. Actions have the power to receive the working note and modify it. We use actions for our Note History extension, as well as Listed and File Attachments.
https://docs.standardnotes.org/extensions/actions

Main endpoint

Every action must have a main endpoint that, for each GET request, replies with this body.

{
  "identifier": "com.my.action",
  "name": "My action",
  "content_type": "Extension",
  "url": "my.action.com/main-endpoint",
  "description": "My action description",
  "supported_types": [
    "Note"
  ],
  "actions": [
    {
      "label": "Action 1",
      "url": "action-1-endpoint",
      "verb": "post",
      "context": "Item",
      "content_types": [
        "Note"
      ],
      "access_type": "decrypted"
    },
    {
      "label": "Action 2",
      "url": "action-2-endpoint",
      "verb": "post",
      "context": "Item",
      "content_types": [
        "Note"
      ]
    }  
  ]
}

Body structure:

identifier: action package identifier
name: action public name
content_type: for an action should be set to “Extension”
url: action url, usually is the main endpoint
description: action description shown in extension menu
supported_types: for now, only “Note” type is supported
actions: an array of object that describes the available actions for this call

When the main endpoint is called?

Every time the user clicks on the action menu on the top of the note editor
Every time the user clicks on an action entry

Action description

{
      "label": "Action 1",
      "url": "action-1-endpoint",
      "verb": "post",
      "context": "Item",
      "content_types": [
        "Note"
      ],
      "access_type": "decrypted"
}

label: name of the action shown in the action menu
url: action url which will be called for the request, can be easily customize for each request
verb: indicates the type of request, can be show, post, render and get
context: for now, can be only “Item”
content_types: for now, can be only “Note”

Show

Standard Notes will open the url in a browser.
https://docs.standardnotes.org/extensions/actions/#properties

Standard Notes add automatically to the URL the item_uuid as a query parameter. The item_uuid is the note unique identifier from which the action is called.

Post

Standard Notes will make a POST request to the url with the current item included in the parameters.
https://docs.standardnotes.org/extensions/actions/#properties

Standard Notes inserts the current note in the body of the request with this format:

{
    "items":
    [
        {
            "uuid": "note uuid",
            "content_type": "Note",
            "content":
            {
                "text": "Note text",
                "title": "Note title",
                "references": [],
                "appData":
                {
                    "org.standardnotes.sn":
                    {
                        "client_updated_at": "2021-01-02T09:46:05.815Z",
                        "pinned": true
                    },
                    "org.standardnotes.sn.components":
                    {
                        "component uuid": {}
                    }
                },
                "preview_plain": "### "
            },
            "created_at": "2020-12-28T20:55:17.586Z",
            "updated_at": "2021-01-02T09:46:05.912Z",
            "duplicate_of": null
        }
    ]
}

Now, you should know the basics to develop your actions for Standard Notes. You could also make your extensions public for the community by publishing them on Listed.to. Follow this guide for further information