# 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
```js
	{
		"noteid": 10,
		"color": "673AB7",
		"content": "#Note\ncontent",
		"html": "<h1>Note</h1><p>content</p>",
		"title": "Note",
		"modified": "2018-12-28 17:24:58",
		"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`.  <br>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.  <br>If `color` is set to six hexadecimal digits, the note's background color will be set.  <br>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.  <br>If `favorite` is set to either `0` (no) or `1` (yes), the note's favorite/starred status will be updated.  <br>`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](https://github.com/nextcloud/notes/wiki/API-0.2).  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.