API Documentation

The NotePost API is extremely simple to use. Requests can be sent via GET or POST, and responses are sent in JSON.

Request Structure

API URLs are typically of the form http(s)://notepost-url/api/<action>/?args.

Clients can authenticate to the API by using HTTP Basic Authentication or by including username and password arguments.

Response Structure

Responses to well-formed requests will have a status field containing the string OK or ERROR.
If status is ERROR, there will also be a field named msg containing a human-readable localized error message suitable for display to the user.
If status is OK, there may or may not be additional fields sent, depending on the action.

If the request is not well-formed (missing required arguments, invalid credentials, or invalid action), the API will send a 4xx HTTP code and some plain text, such as "400 Bad Request", "403 Unauthorized", or "404 Action not defined".

Note JSON Format

    {
        "noteid": 10,
        "color": "673AB7",
        "content": "#Note\ncontent",
        "html": "<h1>Note</h1><p>content</p>",
        "title": "Note",
        "modified": 1547271000,
        "favorite": false,
        "owner": {
            "uid": 1,
            "username": "someone",
            "name": "Some One"
        }
    }

Actions

Action	Additional Arguments	Description
`ping`	None	Used to check if the server is online and responding. Responds with `{"status":"OK"}`.
`getnotes`	None	Returns all the notes that are readable with the sent credentials, as an array named `notes`. See note format above.
`getnote`	`id`	Get one note by its ID.
`savenote`	`text`, `id` (optional), `color` (optional), `modified` (optional), `favorite` (optional), `archived` (optional)	Update a note and return the updated note in `note`. If `id` is not set, creates a new note. Returns the saved note as JSON, along with a `msg` containing a translated "Note saved" message. If `color` is set to six hexadecimal digits, the note's background color will be set. If `modified` is set to a string parsable by PHP `strtotime`, the note's last modified date will be set accordingly, otherwise the current date and time will be used. If `favorite` is set to either `0` (no) or `1` (yes), the note's favorite/starred status will be updated. `archived` is ignored for now, but will operate the same as `favorite` in the future as a non-destructive form of deletion.
`deletenote`	`id`	Delete a note by its ID. This is not reversible.
`favoritenote`	`id`, `favorite` (optional)	If `favorite` is not set, the favorite status of the note will be toggled. If `favorite` is set to either `0` (no) or `1` (yes), the note will be set as favorited or not.
`tolist`	`id`	Convert a note to a list by prepending a checkbox (`- [ ]`) to each line of text. Returns the updated note as `note`.
`togglelist`	`id`, `text`	Toggle the checked/crossed out state of the given line of text in the given note.

Nextcloud Notes API

A subset of NotePost's functionality can also be accessed via a server implementation the Nextcloud Notes API. Use it via https://notepost-url/lib/nextcloudnotes.php, or if your webserver is configured correctly (see the .htaccess file in the NotePost root folder), at https://notepost-url/index.php/apps/notes/api/v0.2. See the linked Nextcloud documentation for usage information.