Home
Notemod-selfhosted Help (v1.3.0)

Notemod-selfhosted Help (v1.3.0)

Notemod-selfhosted Web Manual v1.3.0

This is a detailed practical manual for real-world use after installing Notemod-selfhosted.

In addition to explaining the role of each screen, this document also provides detailed usage instructions for api.php, read_api.php, and cleanup_api.php. In particular, the major update in v1.3.0 is support for copy-and-paste workflows for images and files in addition to conventional text synchronization.

1. Overview

Notemod-selfhosted is a self-hosted edition based on the original Notemod (static UI / browser local storage), specialized for “placing it on your own server and operating it with JSON as the single data source.”
It was developed to facilitate smooth text exchange between Windows PCs and iPhones without relying on external services. It can also be considered a replacement for note services such as simplenote.com.

Difference from the README

README.ja.md
A brief overview to read first on GitHub
An entry point that briefly explains what it can do, how to install it, and its main features
Web Manual (this document)
A guide for actual use after installation
Explains in detail what each screen does, what each setting means, and how to call the APIs

2. Main Points of v1.3.0

In v1.3.0, the range of data types handled by Notemod-selfhosted as a whole has been expanded.

Support for copying and pasting images and files in addition to text
Support for image upload / latest image retrieval APIs
Support for file upload / latest file retrieval APIs
Support for image and file management via media_files.php
Support for organizing media / backups / logs via cleanup_api.php
Support for backup settings, manual backup, and restore via bak_settings.php

3. Role of Each Screen

`index.php`

This is the main Notemod screen. It is the central place for viewing and editing notes and managing categories.

`account.php`

Allows you to change your username and password.

`clipboard_sync.php`

This is the clipboard integration settings screen. It provides download links for the Windows app (ClipboardSync) and iPhone Shortcuts, and also makes various settings easier to configure. You can check and copy API URLs and tokens.

`media_files.php`

This is the management screen for images and files. It allows uploading images and files, deleting them individually, and deleting them all. It also lets you check the server’s upload/download-related settings.

Main features:

Check server file settings
Display image list
Display file list
Drag-and-drop upload
Download images / files
Organize images / files
Delete selected items with checkboxes
Select all / clear all

`bak_settings.php`

This is the backup settings screen for data (data.json).

Main features:

Enable / disable backups
Set retention count
Back up now
Delete old backups
Restore from backup

`log_settings.php`

This is the settings screen for retaining and deleting access logs. It also handles IP access notification settings (email address).

Main features:

Enable / disable access logging
Enable / disable saving access logs to a Notemod category
Set the maximum number of log lines
Enable / disable notifications for access from a first-time IP address
Set the email address for IP access notifications

4. Main JSON Files That Are Generated

Text-related

data.json
The main note data for Notemod
note_latest.json
Stores timestamp information for the latest text item, etc.

Image-related

image_latest.json
Metadata for the latest single image

File-related

file_latest.json
Metadata for the latest single file
file.json
File history log (JSON Lines)
file_index.json
List of currently existing files, used by media_files.php

Note

There is no image_index.json on the image side. Image lists are displayed by directly reading the images/ directory.

5. Overall API Design

In Notemod-selfhosted, APIs are separated by role.

api.php
API for adding data
Add text, upload images, upload files
read_api.php
API for reading data
Category list, note list, latest note, latest image, latest file, latest clip type, etc.
cleanup_api.php
API for organizing and deleting
Delete notes within a category, organize media, delete backups, delete logs, create backups

Authentication uses config/config.api.php.

api.php / read_api.php
EXPECTED_TOKEN
cleanup_api.php
ADMIN_TOKEN (if not set, EXPECTED_TOKEN is used)

6. `api.php` Manual

6-1. Overview

api.php is the API used to add data to Notemod.

Supported type values:

text
image
file

6-2. Accepted Request Formats

GET
POST (application/x-www-form-urlencoded / multipart/form-data)
POST (application/json)

However, images and files are expected to use multipart/form-data.

6-3. Common Parameters

Parameter	Required	Example	Description
`token`	Required	`your_token`	Must match `EXPECTED_TOKEN`
`type`	Optional	`text`	`text` / `image` / `file`. Defaults to `text` if omitted
`pretty`	Optional	`1`	Returns formatted JSON when `1` or `true`

6-4. Add Text (`type=text`)

Additional Parameters

Parameter	Required	Example	Description
`text`	Required	`hello`	Body text to add
`title`	Optional	`Memo`	Note title. Defaults to the current time if omitted
`category`	Optional	`INBOX`	Category name. Defaults to `INBOX` if omitted

Specifications

If the specified category does not exist, it is created automatically
Newlines are converted and saved in HTML format compatible with Notemod
note_latest.json is also updated when text is added successfully

Request Example (form format)

curl -X POST "https://example.com/notemod/api/api.php" \
  -d "token=YOUR_TOKEN" \
  -d "type=text" \
  -d "title=Quick Memo" \
  -d "category=INBOX" \
  --data-urlencode "text=Line 1
Line 2"

Example Success Response

{
  "status": "ok",
  "category": {
    "id": 1234567890,
    "name": "INBOX",
    "noteCount": 5
  },
  "note": {
    "title": "Quick Memo"
  }
}

6-5. Upload Image (`type=image`)

Additional Parameters

Parameter	Required	Example	Description
`image`	Recommended	multipart file	Image file. The recommended field name is `image`

Specifications

$_FILES['image'] is read with priority
Even if the field name is not image, the first uploaded file can still be used
Save destination is notemod-data//images/
Latest image information is stored in image_latest.json
WebP is converted to PNG on the server side
Supported MIME types:
image/png
image/jpeg
image/webp
image/gif
image/heic
image/heif
image/tiff
image/bmp

Request Example

curl -X POST "https://example.com/notemod/api/api.php" \
  -F "token=YOUR_TOKEN" \
  -F "type=image" \
  -F "image=@/path/to/sample.png"

Example Success Response

{
  "status": "ok",
  "mode": "image",
  "user": "your_user",
  "image": {
    "v": 1,
    "type": "image",
    "image_id": "20260312T000000Z_ab12cd34",
    "filename": "20260312T000000Z_ab12cd34.png",
    "ext": "png",
    "mime": "image/png",
    "size": 12345,
    "sha256": "...",
    "created_at": "2026-03-12T00:00:00+00:00",
    "created_at_unix": 1773273600
  }
}

6-6. Upload File (`type=file`)

Additional Parameters

Parameter	Required	Example	Description
`file`	Recommended	multipart file	General file. The recommended field name is `file`

Specifications

$_FILES['file'] is read with priority
Even if the field name is not file, the first uploaded file can still be used
Save destination is notemod-data//files/
Latest file information is stored in file_latest.json
History log is file.json
Display index is file_index.json
Preserves the original filename as original_name
Dangerous extensions are blocked, and the extension is supplemented from the MIME type when necessary

Request Example

curl -X POST "https://example.com/notemod/api/api.php" \
  -F "token=YOUR_TOKEN" \
  -F "type=file" \
  -F "file=@/path/to/manual.pdf"

Example Success Response

{
  "status": "ok",
  "mode": "file",
  "user": "your_user",
  "file": {
    "v": 1,
    "type": "file",
    "file_id": "20260312T000000Z_ab12cd34",
    "filename": "20260312T000000Z_ab12cd34.pdf",
    "ext": "pdf",
    "mime": "application/pdf",
    "size": 34567,
    "sha256": "...",
    "original_name": "manual.pdf",
    "created_at": "2026-03-12T00:00:00+00:00",
    "created_at_unix": 1773273600
  }
}

6-7. Main Errors

HTTP	Example	Meaning
`400`	`text is required`	Missing required parameter
`400`	`image file is required`	No image attached
`400`	`file is required`	No file attached
`403`	`Forbidden`	Token mismatch
`415`	`Unsupported image type`	Unsupported image format
`500`	`Failed to write image_latest.json`	Server-side save failure

7. `read_api.php` Manual

7-1. Overview

read_api.php is the API used to read Notemod data and latest clip information.

7-2. Accepted Request Formats

GET
POST (form)
POST (JSON)

7-3. Common Parameters

Parameter	Required	Example	Description
`token`	Required	`your_token`	Must match `EXPECTED_TOKEN`
`action`	Optional	`list_categories`	Operation to execute. Defaults to `list_categories`
`pretty`	Optional	`2`	`1/true` for formatted JSON, `0/false` for compact JSON, and unspecified defaults to behavior equivalent to `2`

7-4. Meaning of `pretty`

In read_api.php, pretty has a somewhat special meaning.

Value	Behavior
Omitted	Equivalent to `pretty=2`
`2`	For `latest_note` / `get_note`, returns the body as `text/plain`
`1` / `true`	Readable formatted JSON
`0` / `false`	Compact JSON

7-5. List of Actions

action	Purpose	Main Return Type
`list_categories`	Get category list	JSON
`list_notes`	Get note list	JSON
`latest_clip_type`	Determine whether the latest item is note / image / file	JSON
`latest_image`	Retrieve binary data of the latest image	Image binary
`latest_file`	Retrieve binary data of the latest file	File binary
`latest_note`	Retrieve latest note	JSON or text/plain
`get_note`	Retrieve a specified note	JSON or text/plain

7-6. `list_categories`

Additional Parameters

None

Example

curl "https://example.com/notemod/api/read_api.php?token=YOUR_TOKEN&action=list_categories&pretty=1"

7-7. `list_notes`

Additional Parameters

Parameter	Required	Example	Description
`category`	Optional	`INBOX`	Filter by category name
`category_id`	Optional	`123`	Filter by category ID
`limit`	Optional	`20`	Maximum number of items
`summary`	Optional	`1`	Adds `preview` when `1/true`

Specifications

category_id takes priority
summary=1 adds a preview string
Sorting order is newest first

7-8. `latest_clip_type`

Determines whether the latest clip is text / image / file.

Objects checked:

note_latest.json
image_latest.json
file_latest.json

Priority when timestamps are the same:

image > file > note

Additional Parameters

None

Example Return

{
  "status": "ok",
  "type": "image",
  "latest_unix": 1773273600,
  "image": {
    "filename": "20260312T000000Z_ab12cd34.png"
  }
}

7-9. `latest_image`

Returns the binary data of the latest image.

Additional Parameters

None

Specifications

Reads image_latest.json and returns the image file recorded there
If the file does not exist, returns JSON with exists=false
No download filename is attached because it is intended for paste use

Example

curl -L "https://example.com/notemod/api/read_api.php?token=YOUR_TOKEN&action=latest_image" --output latest_image.bin

7-10. `latest_file`

Returns the binary data of the latest file.

Additional Parameters

None

Specifications

Reads file_latest.json
If original_name exists, that name is used as the download filename
Otherwise, the saved filename is used

Example

curl -L "https://example.com/notemod/api/read_api.php?token=YOUR_TOKEN&action=latest_file" --output latest_file.bin

7-11. `latest_note`

Returns the latest note. If category is omitted, the latest note in the INBOX category is returned.

Additional Parameters

Parameter	Required	Example	Description
`category`	Optional	`INBOX`	Latest note within the specified category
`category_id`	Optional	`123`	Latest note within the specified category ID

Specifications

The Logs category is always excluded
If pretty=2 or omitted, the body is returned as text/plain
Otherwise, JSON is returned

Example

curl "https://example.com/notemod/api/read_api.php?token=YOUR_TOKEN&action=latest_note"

7-12. `get_note`

Retrieves one note by category name and title.

Additional Parameters

Parameter	Required	Example	Description
`category`	Required	`INBOX`	Category name
`title`	Required	`Quick Memo`	Note title

Specifications

If pretty=2 or omitted, the body is returned as text/plain
Otherwise, JSON is returned

Example

curl "https://example.com/notemod/api/read_api.php?token=YOUR_TOKEN&action=get_note&category=INBOX&title=Quick%20Memo&pretty=1"

7-13. Main Errors

HTTP	Example	Meaning
`400`	`unknown action`	Invalid action
`400`	`category and title are required`	Missing required parameters for `get_note`
`403`	`Forbidden`	Token mismatch
`500`	`invalid image_latest.json`	Latest image metadata is corrupted
`500`	`invalid file_latest.json`	Latest file metadata is corrupted

8. `cleanup_api.php` Manual

8-1. Overview

cleanup_api.php is the API for deletion and cleanup operations.

Supported operations:

Delete all notes in a specified category
Organize images
Organize files
Organize all media at once
Delete .bak files
Delete .log files
Create .bak files (GET allowed)

8-2. Accepted Request Formats

POST only
Form format or JSON

It cannot be used via GET.

8-3. Common Parameters

Parameter	Required	Example	Description
`token`	Required	`admin_token`	Must match `ADMIN_TOKEN`
`confirm`	Conditionally required	`YES`	Required for actual deletion. Not required when `dry_run=1/2`
`dry_run`	Optional	`0`	`0`=execute, `1`=preview list, `2`=count only
`pretty`	Optional	`1`	Returns formatted JSON when `1/true`

8-4. Meaning of `dry_run`

Value	Behavior
`0`	Actually deletes
`1`	Does not delete; returns a list of targets
`2`	Does not delete; returns counts only

8-5. Delete Notes (by Category)

Additional Parameters

Parameter	Required	Example	Description
`category`	Optional	`INBOX`	Target category name. Defaults to `INBOX` if omitted

Example

curl -X POST "https://example.com/notemod/api/cleanup_api.php" \
  -d "token=ADMIN_TOKEN" \
  -d "category=INBOX" \
  -d "confirm=YES"

8-6. Organize Images (`purge_images`)

Additional Parameters

Parameter	Required	Example	Description
`purge_images`	Required	`1`	Executes image cleanup

Specifications

Reads image_latest.json
The actual latest file is protected
Supports dry_run=1/2
If image_latest.json is corrupted, it stops for safety

Example

curl -X POST "https://example.com/notemod/api/cleanup_api.php" \
  -d "token=ADMIN_TOKEN" \
  -d "purge_images=1" \
  -d "confirm=YES"

8-7. Organize Files (`purge_files`)

Additional Parameters

Parameter	Required	Example	Description
`purge_files`	Required	`1`	Executes file cleanup

Specifications

Reads file_latest.json
The actual latest file is protected
Regenerates file_index.json after actual deletion
Corrects file_latest.json after actual deletion when necessary
Supports dry_run=1/2

Example

curl -X POST "https://example.com/notemod/api/cleanup_api.php" \
  -d "token=ADMIN_TOKEN" \
  -d "purge_files=1" \
  -d "confirm=YES"

8-8. Organize All Media (`purge_media`)

Additional Parameters

Parameter	Required	Example	Description
`purge_media`	Required	`1`	Organizes images and files together

Specifications

Internally equivalent to purge_images=1 and purge_files=1

Example

curl -X POST "https://example.com/notemod/api/cleanup_api.php" \
  -d "token=ADMIN_TOKEN" \
  -d "purge_media=1" \
  -d "confirm=YES"

8-9. Delete Backups (`purge_bak`)

Additional Parameters

Parameter	Required	Example	Description
`purge_bak`	Required	`1`	Deletes `.bak`-related files

Specifications

Targets .bak-related files in the notemod-data directory
The main data.json itself is not a deletion target

8-10. Delete Logs (`purge_log`)

Additional Parameters

Parameter	Required	Example	Description
`purge_log`	Required	`1`	Deletes `.log` files

Specifications

Gives priority to LOGGER_LOGS_DIRNAME in config/config.php
If not present, targets logs/

8-11. Create Backup (`action=backup_now`)

Additional Parameters

Parameter	Required	Example	Description
`action`	Required	`backup_now`	Creates a `.bak` backup file

Specifications

Allows GET with action=backup_now

Example

curl "https://example.com/notemod/api/cleanup_api.php?action=backup_now"

8-12. Main Errors

HTTP	Example	Meaning
`400`	`Add confirm=YES`	No confirm parameter for actual deletion
`403`	`Forbidden`	Token mismatch
`405`	`POST only`	Called via GET
`500`	`invalid image_latest.json`	Stopped to protect the latest item
`500`	`invalid file_latest.json`	Stopped to protect the latest item

9. Notes When Using the API

Using Tokens Separately

Normal add / fetch operations:
EXPECTED_TOKEN
Dangerous operations:
ADMIN_TOKEN

Using a separate ADMIN_TOKEN is safer.

About Latest Protection

Media cleanup in cleanup_api.php is designed to protect the actual latest image / latest file.

In other words, even if the UI says “Delete All,” the actual behavior may be to clean up everything except the latest item.

Differences in `pretty`

api.php and cleanup_api.php
pretty=1 returns formatted JSON
read_api.php
pretty=2 is special and returns the latest note body as text/plain

Character Encoding

Filenames and note bodies are expected to use UTF-8.
Even when some clients send filenames in RFC2047 format, the implementation attempts to decode them.

10. Common Usage Patterns

Add text and read the latest note

Send to api.php with type=text
Read with read_api.php?action=latest_note

Send an image and read the latest image

Send to api.php with type=image
Read with read_api.php?action=latest_image

Send a file and read the latest file

Send to api.php with type=file
Read with read_api.php?action=latest_file

Determine the latest type and branch processing

Call read_api.php?action=latest_clip_type
Check the returned type and branch to:

note
image
file

Organize backups and logs

Use cleanup_api.php with purge_bak=1
Use cleanup_api.php with purge_log=1

It is recommended to check first with dry_run=1 or dry_run=2 before running the actual cleanup.

11. Troubleshooting

`Forbidden` appears

The token is incorrect
Check whether ADMIN_TOKEN and EXPECTED_TOKEN are being used correctly

`Unsupported image type` when uploading an image

The MIME type is unsupported
Convert the image format to PNG / JPEG or similar and try again

`latest_image` / `latest_file` is not returned

image_latest.json / file_latest.json does not exist
The actual file referenced in the latest metadata has been deleted

`cleanup_api.php` does not delete

confirm=YES is missing
dry_run is 1 or 2
It is being skipped because of latest-item protection

Backups or logs are not deleted

Insufficient permissions
The target folder name does not match the configuration

12. Appendix: API Quick Reference

`api.php`

Purpose	Required Keys
Add text	`token`, `type=text`, `text`
Upload image	`token`, `type=image`, `image`
Upload file	`token`, `type=file`, `file`

`read_api.php`

action	Main Additional Keys
`list_categories`	None
`list_notes`	`category`, `category_id`, `limit`, `summary`
`latest_clip_type`	None
`latest_image`	None
`latest_file`	None
`latest_note`	`category`, `category_id`
`get_note`	`category`, `title`

`cleanup_api.php`

Purpose	Main Keys
Delete category	`category`, `confirm=YES`
Organize images	`purge_images=1`, `confirm=YES`
Organize files	`purge_files=1`, `confirm=YES`
Organize media	`purge_media=1`, `confirm=YES`
Delete backups	`purge_bak=1`, `confirm=YES`
Delete logs	`purge_log=1`, `confirm=YES`
Preview	`dry_run=1` or `dry_run=2`
Create backup	`action=backup_now`

That is all.

Language

Notemod-selfhosted Help (v1.3.0)

Notemod-selfhosted Web Manual v1.3.0

1. Overview

Difference from the README

2. Main Points of v1.3.0

3. Role of Each Screen

index.php

account.php

clipboard_sync.php

media_files.php

bak_settings.php

log_settings.php

4. Main JSON Files That Are Generated

Text-related

Image-related

File-related

Note

5. Overall API Design

6. api.php Manual

6-1. Overview

6-2. Accepted Request Formats

6-3. Common Parameters

6-4. Add Text (type=text)

Additional Parameters

Specifications

Request Example (form format)

Example Success Response

6-5. Upload Image (type=image)

Additional Parameters

Specifications

Request Example

Example Success Response

6-6. Upload File (type=file)

Additional Parameters

Specifications

Request Example

Example Success Response

6-7. Main Errors

7. read_api.php Manual

7-1. Overview

7-2. Accepted Request Formats

7-3. Common Parameters

7-4. Meaning of pretty

7-5. List of Actions

7-6. list_categories

Additional Parameters

Example

7-7. list_notes

Additional Parameters

Specifications

7-8. latest_clip_type

Additional Parameters

Example Return

7-9. latest_image

Additional Parameters

Specifications

Example

7-10. latest_file

Additional Parameters

Specifications

Example

7-11. latest_note

Additional Parameters

Specifications

Example

7-12. get_note

Additional Parameters

Specifications

Example

7-13. Main Errors

8. cleanup_api.php Manual

8-1. Overview

8-2. Accepted Request Formats

8-3. Common Parameters

8-4. Meaning of dry_run

8-5. Delete Notes (by Category)

Additional Parameters

Example

8-6. Organize Images (purge_images)

Additional Parameters

`index.php`

`account.php`

`clipboard_sync.php`

`media_files.php`

`bak_settings.php`

`log_settings.php`

6. `api.php` Manual

6-4. Add Text (`type=text`)

6-5. Upload Image (`type=image`)

6-6. Upload File (`type=file`)

7. `read_api.php` Manual

7-4. Meaning of `pretty`

7-6. `list_categories`

7-7. `list_notes`

7-8. `latest_clip_type`

7-9. `latest_image`

7-10. `latest_file`

7-11. `latest_note`

7-12. `get_note`

8. `cleanup_api.php` Manual

8-4. Meaning of `dry_run`

8-6. Organize Images (`purge_images`)

8-7. Organize Files (`purge_files`)

8-8. Organize All Media (`purge_media`)

8-9. Delete Backups (`purge_bak`)

8-10. Delete Logs (`purge_log`)

8-11. Create Backup (`action=backup_now`)

Differences in `pretty`

`Forbidden` appears

`Unsupported image type` when uploading an image

`latest_image` / `latest_file` is not returned

`cleanup_api.php` does not delete

`api.php`

`read_api.php`

`cleanup_api.php`