API Specification

Notesium provides a REST API that accepts and returns JSON-encoded data and uses standard HTTP response codes.

The REST API is served under the /api base path by the CLI web command, alongside the webroot configured at startup.

BASE_URL="http://localhost:PORT/api"

Versioning

The API is currently considered unstable, and no explicit API versioning has been implemented.

Errors

The REST API uses conventional HTTP response codes to indicate the success or failure of an API request. In general: Codes in the 2xx range indicate success. Codes in the 4xx range indicate an error that failed given the information provided (e.g., a required parameter was omitted). Codes in the 5xx range indicate an error with the REST API server.

Error responses may include the Code and Error (description) of the error in the body of the response.

Notes

The /api/notes path can be used to create a new note, update an existing note, retrieve a specific note along with its metadata and content, as well as retrieve a list of all notes.

See Raw command for alternative listing endpoints.

The note object

The note object represents a note in Notesium.

Attributes

Example

{
  "Filename": "64214a1d.md",
  "Title": "richard feynman",
  "IsLabel": false,
  "OutgoingLinks": [
    {
      "Filename": "642146c7.md",
      "Title": "physicist",
      "LineNumber": 3
    },
    {
      "Filename": "64214930.md",
      "Title": "quantum mechanics",
      "LineNumber": 5
    }
  ],
  "IncomingLinks": [
    {
      "Filename": "64218087.md",
      "Title": "surely you're joking mr. feynman",
      "LineNumber": 3
    }
  ],
  "Ctime": "2023-03-27T10:47:41+03:00",
  "Mtime": "2023-11-30T14:22:44+02:00",
  "Lines": 6,
  "Words": 52,
  "Chars": 362,
  "Path": "/home/github/notesium/notesium/tmp/dir/64214a1d.md",
  "Content": "# richard feynman\n\nrichard phillips feynman was an..."
}

Create a note

$ curl -X POST $BASE_URL/notes/ \
  -H 'Content-Type: application/json' \
  -d '{"Content": "# new note\n\nthis is a new note\n",
       "Ctime": "2023-11-30T14:20:00+02:00"}'

A cache update will be triggered automatically upon a successful request.

This endpoint will return a Forbidden error response unless the daemon is started with the --writable option.

Parameters

Returns

The note object.

Update a note

$ curl -X PATCH $BASE_URL/notes/64214a1d.md \
  -H 'Content-Type: application/json' \
  -d '{"Content": "# mr. richard feynman\n...",
       "LastMtime": "2023-11-30T14:22:44+02:00"}'

If the last modified time does not match the current modified time of the note on disk, updating the note will be refused as a fail-safe.

A cache update will be triggered automatically upon a successful request.

This endpoint will return a Forbidden error response unless the daemon is started with the --writable option.

Parameters

Returns

The note object.

Delete a note

$ curl -X DELETE $BASE_URL/notes/64214a1d.md \
  -H 'Content-Type: application/json' \
  -d '{"LastMtime": "2023-11-30T14:22:44+02:00"}'

If the last modified time does not match the current modified time of the note on disk, deleting the note will be refused as a fail-safe.

If the note has incoming links, deleting the note will be refused as to not result in dangling links.

A cache update will be triggered automatically upon a successful request.

This endpoint will return a Forbidden error response unless the daemon is started with the --writable option.

Parameters

Returns

Returns an object with Filename and Deleted parameter on success.

Retrieve a note

$ curl $BASE_URL/notes/64214a1d.md

Parameters

None.

Returns

The note object.

List all notes

$ curl $BASE_URL/notes

Parameters

None.

Returns

A list of note objects (excluding Content and Path fields).

Runtime

The /api/runtime path can be used to retrieve a snapshot of the runtime object.

The runtime object

The runtime object represents the configuration, build details, host platform, and memory usage of the running Notesium binary.

Attributes

Example

{
  "home": "/home/github/notesium/notesium/tmp/dir/",
  "version": "0.1.2",
  "platform": "linux/amd64",
  "web": {
    "webroot": "embedded",
    "writable": true,
    "stop-on-idle": false,
    "daily-version-check": false
  },
  "build": {
    "gitversion": "v0.1.2-0-gda91f63",
    "buildtime": "2024-01-01T12:34:56Z",
    "goversion": "go1.20.5",
    "latest-release-url": "https://api.github.com/...notesium/releases/latest"
  },
  "memory": {
    "alloc": "510.0 KB",
    "total-alloc": "510.0 KB",
    "sys": "3.1 MB",
    "lookups": 0,
    "mallocs": 1866,
    "frees": 61
  }
}

Get runtime

$ curl $BASE_URL/runtime

Parameters

None

Returns

The runtime object.

Raw command

The /api/raw/ path is experimental and provides a passthrough for most of the CLI commands.

The same options as the corresponding CLI commands are supported. Boolean options must have a value of true or false. Responses are returned as plain text.

New

Provides passthrough for the CLI command new.

$ curl "$BASE_URL/raw/new?verbose=true"

Attributes

Returns

Buffered raw text output of the command.

List

Provides passthrough for the CLI command list.

$ curl "$BASE_URL/raw/list?color=true&sort=alpha"

Attributes

Returns

Buffered raw text output of the command.

Links

Provides passthrough for the CLI command links.

$ curl "$BASE_URL/raw/links?filename=64214a1d.md"

Attributes

Returns

Buffered raw text output of the command.

Lines

Provides passthrough for the CLI command lines.

$ curl "$BASE_URL/raw/lines?color=true&prefix=title"

Attributes

Returns

Buffered raw text output of the command.

Stats

Provides passthrough for the CLI command stats.

$ curl "$BASE_URL/raw/stats"

Attributes

Returns

Buffered raw text output of the command.

Version

Provides passthrough for the CLI command version.

$ curl "$BASE_URL/raw/version?verbose=true"

Attributes

Returns

Buffered raw text output of the command.

Heartbeat

The web daemon provides a --stop-on-idle option, which is used to automatically stop the daemon when no activity is detected. Every API request updates resets the idle time, but in order to keep the daemon alive when the web interface is open but not actively being used, a heartbeat must be sent.

This endpoint is only available when the daemon is started with the --stop-on-idle option.

$ curl $BASE_URL/heartbeat