ホーム
Notemod-selfhosted ヘルプ（v1.3.0）

Notemod-selfhosted ヘルプ（v1.3.0）

Notemod-selfhosted ウェブ用マニュアル v1.3.0

Notemod-selfhosted の導入後に使う、実運用向けの詳細マニュアルです。

この文書では、画面ごとの役割に加えて、api.php / read_api.php / cleanup_api.php の利用方法を詳しく説明します。特に v1.3.0 では、従来のテキスト連携に加えて画像と ファイル のコピー＆ペースト運用に対応した点が大きな更新点です。

1. 概要

Notemod-selfhosted は、本家 Notemod（静的UI/ブラウザのローカルストレージに保存）をベースに「自分のサーバーに置いて、JSONを単一データソースとして運用する」ことに特化した自己ホスト版です。
外部サービスに依存せず、Windows PC と iPhone 間のテキストのやり取りを円滑にする目的で開発されています。また、simplenote.com などのノートサービスを代替できるものだと思います

README との違い

README.ja.md
GitHub 上で最初に読む概要
何ができるか、どう導入するか、主要機能は何かを短く案内する入口
ウェブ用マニュアル（この文書）
導入後に実際に使うための説明書
各画面で何をするか、どの設定が何を意味するか、API をどう呼ぶかを詳しく説明する

2. v1.3.0 の主なポイント

v1.3.0 では、Notemod-selfhosted 全体として扱えるデータ種別が広がりました。

テキストに加え、画像とファイルのコピー＆ペーストに対応
画像のアップロード / 最新画像取得 API に対応
ファイルのアップロード / 最新ファイル取得 API に対応
media_files.php による画像・ファイル管理に対応
cleanup_api.php によるメディア / バックアップ / ログ整理に対応
bak_settings.php によるバックアップ設定・手動バックアップ・リストアに対応

3. 画面別の役割

`index.php`

通常の Notemod 本体画面です。ノートの閲覧・編集・カテゴリ管理の中心です。

`account.php`

ユーザー名の変更やパスワードの変更が可能です。

`clipboard_sync.php`

クリップボード連携設定用の画面です。Windows アプリ（ClipboardSync）や iPhone ショートカットのダウンロードリンクを提供し、さらに各種設定を容易にします。API URL や TOKEN を確認・コピーできます。

`media_files.php`

画像とファイルの管理画面です。画像とファイルのアップロード、個別削除、全削除が可能です。また。サーバーのアップロード/ダウンロード関連設定を確認できます。

主な機能:

サーバーのファイル設定の確認
画像一覧の表示
ファイル一覧の表示
ドラッグ＆ドロップアップロード
画像 / ファイルのダウンロード
画像 / ファイルの整理
チェックボックス選択削除
全選択 / 全解除

`bak_settings.php`

データ（data.json）のバックアップ設定画面です。

主な機能:

バックアップの有効 / 無効
保持数設定
今すぐバックアップ
古いバックアップ削除
バックアップからのリストア

`log_settings.php`

アクセスログの保持・削除設定画面です。IPアクセス通知の設定（メールアドレス）

主な機能:

アクセスログの有効 / 無効
アクセスログを Notemod のカテゴリーに保存の有効 / 無効
アクセスログの最大行数の設定
初めてのIPアクセスからのアクセスの際に通知の有効 / 無効
IPアクセス通知のメールアドレスを設定

4. 生成される主な JSON ファイル

テキスト系

data.json
Notemod 本体のノートデータ
note_latest.json
最新テキストの時刻情報などを保持

画像系

image_latest.json
最新画像 1 件のメタ情報

ファイル系

file_latest.json
最新ファイル 1 件のメタ情報
file.json
ファイル履歴ログ（JSON Lines）
file_index.json
現存ファイル一覧。media_files.php 表示用

補足

画像側には image_index.json はありません。画像一覧は images/ ディレクトリを直接見て表示する前提です。

5. API 全体の考え方

Notemod-selfhosted では、役割ごとに API が分かれています。

api.php
追加する API
テキスト追加、画像アップロード、ファイルアップロード
read_api.php
読む API
カテゴリ一覧、ノート一覧、最新ノート、最新画像、最新ファイル、最新クリップ種別など
cleanup_api.php
整理・削除する API
カテゴリ内ノート削除、メディア整理、バックアップ削除、ログ削除、バックアップ作成

認証は config/config.api.php を使います。

api.php / read_api.php
EXPECTED_TOKEN
cleanup_api.php
ADMIN_TOKEN（未設定時は EXPECTED_TOKEN を使用）

6. `api.php` マニュアル

6-1. 概要

api.php は、Notemod にデータを追加するための API です。

対応する type:

text
image
file

6-2. 受け付け形式

GET
POST（application/x-www-form-urlencoded / multipart/form-data）
POST（application/json）

ただし、画像とファイルは multipart/form-data が前提 です。

6-3. 共通パラメータ

パラメータ	必須	例	説明
`token`	必須	`your_token`	`EXPECTED_TOKEN` と一致する必要があります
`type`	任意	`text`	`text` / `image` / `file`。省略時は `text`
`pretty`	任意	`1`	`1` または `true` で JSON を整形して返します

6-4. テキスト追加 (`type=text`)

追加パラメータ

パラメータ	必須	例	説明
`text`	必須	`hello`	追加する本文
`title`	任意	`Memo`	ノートタイトル。省略時は現在時刻
`category`	任意	`INBOX`	カテゴリ名。省略時は `INBOX`

仕様

指定カテゴリが存在しなければ自動作成されます
改行は Notemod 互換の HTML 形式へ変換して保存されます
テキスト追加成功時に note_latest.json も更新されます

リクエスト例（フォーム形式）

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=1行目
2行目"

成功レスポンス例

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

6-5. 画像アップロード (`type=image`)

追加パラメータ

パラメータ	必須	例	説明
`image`	推奨	multipart file	画像ファイル。フィールド名の推奨は `image`

仕様

$_FILES['image'] を優先して読みます
image という名前でなくても、最初のアップロードファイルを利用可能です
保存先は notemod-data//images/
最新画像情報は image_latest.json に保存されます
WebP はサーバー側で PNG に変換されます
対応 MIME:
image/png
image/jpeg
image/webp
image/gif
image/heic
image/heif
image/tiff
image/bmp

リクエスト例

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

成功レスポンス例

{
  "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. ファイルアップロード (`type=file`)

追加パラメータ

パラメータ	必須	例	説明
`file`	推奨	multipart file	一般ファイル。フィールド名の推奨は `file`

仕様

$_FILES['file'] を優先して読みます
file という名前でなくても、最初のアップロードファイルを利用可能です
保存先は notemod-data//files/
最新ファイル情報は file_latest.json
履歴ログは file.json
表示用インデックスは file_index.json
元ファイル名 original_name を保持します
危険な拡張子はブロックされ、必要に応じて MIME から拡張子を補完します

リクエスト例

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

成功レスポンス例

{
  "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. 主なエラー

HTTP	例	意味
`400`	`text is required`	必須パラメータ不足
`400`	`image file is required`	画像未添付
`400`	`file is required`	ファイル未添付
`403`	`Forbidden`	トークン不一致
`415`	`Unsupported image type`	未対応画像形式
`500`	`Failed to write image_latest.json`	サーバー保存失敗

7. `read_api.php` マニュアル

7-1. 概要

read_api.php は、Notemod のデータや最新クリップ情報を読む API です。

7-2. 受け付け形式

GET
POST（フォーム）
POST（JSON）

7-3. 共通パラメータ

パラメータ	必須	例	説明
`token`	必須	`your_token`	`EXPECTED_TOKEN` と一致する必要があります
`action`	任意	`list_categories`	実行する処理。省略時は `list_categories`
`pretty`	任意	`2`	`1/true` で整形JSON、`0/false` で圧縮JSON、未指定は既定で `2` 相当

7-4. `pretty` の意味

read_api.php では pretty の意味が少し特別です。

値	動作
未指定	`pretty=2` 相当
`2`	`latest_note` / `get_note` は本文を `text/plain` で返す
`1` / `true`	読みやすい整形JSON
`0` / `false`	圧縮JSON

7-5. action 一覧

action	用途	主な返却
`list_categories`	カテゴリ一覧取得	JSON
`list_notes`	ノート一覧取得	JSON
`latest_clip_type`	最新が note / image / file のどれか判定	JSON
`latest_image`	最新画像のバイナリ取得	画像バイナリ
`latest_file`	最新ファイルのバイナリ取得	ファイルバイナリ
`latest_note`	最新ノート取得	JSON または text/plain
`get_note`	指定ノート取得	JSON または text/plain

7-6. `list_categories`

追加パラメータ

なし

例

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

7-7. `list_notes`

追加パラメータ

パラメータ	必須	例	説明
`category`	任意	`INBOX`	カテゴリ名で絞り込み
`category_id`	任意	`123`	カテゴリIDで絞り込み
`limit`	任意	`20`	件数上限
`summary`	任意	`1`	`1/true` で `preview` を付加

仕様

category_id が優先されます
summary=1 でプレビュー文字列を追加します
並び順は新しい順です

7-8. `latest_clip_type`

最新のクリップが テキスト / 画像 / ファイル のどれかを判定します。

判定対象:

note_latest.json
image_latest.json
file_latest.json

同時刻の優先順位:

image > file > note

追加パラメータ

なし

返却例

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

7-9. `latest_image`

最新画像のバイナリを返します。

追加パラメータ

なし

仕様

image_latest.json を読み、そこに記録された画像ファイルを返します
ファイルが無ければ JSON で exists=false を返します
画像は貼り付け用途を想定し、ダウンロード名は付けません

例

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

7-10. `latest_file`

最新ファイルのバイナリを返します。

追加パラメータ

なし

仕様

file_latest.json を読みます
original_name があれば、その名前をダウンロード名として返します
無ければ保存ファイル名を使います

例

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

7-11. `latest_note`

最新ノートを返します。category　が、未指定の場合は、INBOX カテゴリーの最新ノートを返します。

追加パラメータ

パラメータ	必須	例	説明
`category`	任意	`INBOX`	指定カテゴリ内の最新ノート
`category_id`	任意	`123`	指定カテゴリID内の最新ノート

仕様

Logs カテゴリは常に除外されます
pretty=2 または未指定なら本文を text/plain で返します
それ以外は JSON を返します

例

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

7-12. `get_note`

カテゴリ名とタイトルでノートを 1 件取得します。

追加パラメータ

パラメータ	必須	例	説明
`category`	必須	`INBOX`	カテゴリ名
`title`	必須	`Quick Memo`	ノートタイトル

仕様

pretty=2 または未指定なら本文を text/plain で返します
それ以外は JSON を返します

例

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

7-13. 主なエラー

HTTP	例	意味
`400`	`unknown action`	action 不正
`400`	`category and title are required`	`get_note` の必須不足
`403`	`Forbidden`	トークン不一致
`500`	`invalid image_latest.json`	最新画像メタ破損
`500`	`invalid file_latest.json`	最新ファイルメタ破損

8. `cleanup_api.php` マニュアル

8-1. 概要

cleanup_api.php は削除・整理系の API です。

対応内容:

指定カテゴリのノート全削除
画像整理
ファイル整理
メディア一括整理
.bak ファイル削除
.log ファイル削除
.bak ファイル作成 (GET可)

8-2. 受け付け形式

POST 専用
フォーム形式または JSON

GET では使えません。

8-3. 共通パラメータ

パラメータ	必須	例	説明
`token`	必須	`admin_token`	`ADMIN_TOKEN` と一致する必要があります
`confirm`	条件付き必須	`YES`	実削除時に必要。`dry_run=1/2` なら不要
`dry_run`	任意	`0`	`0`=実行、`1`=一覧確認、`2`=件数のみ
`pretty`	任意	`1`	`1/true` で整形 JSON

8-4. `dry_run` の意味

値	動作
`0`	実際に削除する
`1`	削除しない。対象一覧を返す
`2`	削除しない。件数のみ返す

8-5. ノート削除（カテゴリ単位）

追加パラメータ

パラメータ	必須	例	説明
`category`	任意	`INBOX`	対象カテゴリ名。省略時は `INBOX`

例

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

8-6. 画像整理 (`purge_images`)

追加パラメータ

パラメータ	必須	例	説明
`purge_images`	必須	`1`	画像整理を実行

仕様

image_latest.json を読みます
latest 実体は保護されます
dry_run=1/2 に対応します
image_latest.json が壊れている場合は安全のため中止します

例

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

8-7. ファイル整理 (`purge_files`)

追加パラメータ

パラメータ	必須	例	説明
`purge_files`	必須	`1`	ファイル整理を実行

仕様

file_latest.json を読みます
latest 実体は保護されます
実削除後、file_index.json を再生成します
実削除後、必要に応じて file_latest.json を補正します
dry_run=1/2 に対応します

例

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

8-8. メディア一括整理 (`purge_media`)

追加パラメータ

パラメータ	必須	例	説明
`purge_media`	必須	`1`	画像とファイルをまとめて整理

仕様

内部的には purge_images=1 と purge_files=1 と同等です

例

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

8-9. バックアップ削除 (`purge_bak`)

追加パラメータ

パラメータ	必須	例	説明
`purge_bak`	必須	`1`	`.bak` 系ファイルを削除

仕様

notemod-data ディレクトリ内の .bak 系ファイルが対象です
data.json 本体は削除対象になりません

8-10. ログ削除 (`purge_log`)

追加パラメータ

パラメータ	必須	例	説明
`purge_log`	必須	`1`	`.log` ファイルを削除

仕様

config/config.php の LOGGER_LOGS_DIRNAME を優先します
無ければ logs/ を対象にします

8-11. バックアップ作成 (`action=backup_now`)

追加パラメータ

パラメータ	必須	例	説明
`action`	必須	`backup_now`	`.bak` バックアップファイルを作成

仕様

GET action=backup_now を許可

例

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

8-12. 主なエラー

HTTP	例	意味
`400`	`Add confirm=YES`	実削除に confirm が無い
`403`	`Forbidden`	トークン不一致
`405`	`POST only`	GET で呼んでいる
`500`	`invalid image_latest.json`	latest 保護のため中止
`500`	`invalid file_latest.json`	latest 保護のため中止

9. API 利用時の注意

トークンの使い分け

通常の追加・取得:
EXPECTED_TOKEN
危険操作:
ADMIN_TOKEN

ADMIN_TOKEN を分けておくと安全です。

latest 保護について

cleanup_api.php のメディア整理は、最新画像 / 最新ファイルの実体を保護する 設計です。

つまり、画面上で「全削除」と見えていても、実際には latest 以外を整理する 動作になる場合があります。

`pretty` の違い

api.php と cleanup_api.php
pretty=1 で整形 JSON
read_api.php
pretty=2 が特殊で、最新ノート本文を text/plain で返します

文字コード

ファイル名やノート本文は UTF-8 運用を前提にしています。
一部クライアントが RFC2047 形式のファイル名を送る場合でも、復号を試みる実装になっています。

10. よくある使い方

テキストを追加して最新ノートを読む

api.php に type=text で送信
read_api.php?action=latest_note で読む

画像を送って最新画像を読む

api.php に type=image で送信
read_api.php?action=latest_image で読む

ファイルを送って最新ファイルを読む

api.php に type=file で送信
read_api.php?action=latest_file で読む

バックアップやログを整理する

cleanup_api.php に purge_bak=1
cleanup_api.php に purge_log=1

まずは dry_run=1 や dry_run=2 で確認してから本実行するのがおすすめです。

11. トラブルシューティング

`Forbidden` が出る

トークンが違う
ADMIN_TOKEN と EXPECTED_TOKEN の使い分けを確認する

画像アップロードで `Unsupported image type`

MIME が未対応
画像形式を PNG / JPEG などに変換して再試行する

`latest_image` / `latest_file` が返らない

image_latest.json / file_latest.json が無い
latest メタに書かれた実体ファイルが削除されている

`cleanup_api.php` が削除してくれない

confirm=YES が無い
dry_run が 1 または 2
latest 実体保護でスキップされている

バックアップやログが消えない

パーミッション不足
対象フォルダ名が設定と一致していない

12. 付録: API クイックリファレンス

`api.php`

用途	必須キー
テキスト追加	`token`, `type=text`, `text`
画像アップロード	`token`, `type=image`, `image`
ファイルアップロード	`token`, `type=file`, `file`

`read_api.php`

action	主な追加キー
`list_categories`	なし
`list_notes`	`category`, `category_id`, `limit`, `summary`
`latest_clip_type`	なし
`latest_image`	なし
`latest_file`	なし
`latest_note`	`category`, `category_id`
`get_note`	`category`, `title`

`cleanup_api.php`

用途	主なキー
カテゴリ削除	`category`, `confirm=YES`
画像整理	`purge_images=1`, `confirm=YES`
ファイル整理	`purge_files=1`, `confirm=YES`
メディア整理	`purge_media=1`, `confirm=YES`
バックアップ削除	`purge_bak=1`, `confirm=YES`
ログ削除	`purge_log=1`, `confirm=YES`
事前確認	`dry_run=1` または `dry_run=2`
バックアップ作成	`action=backup_now`

以上です。

Language

Notemod-selfhosted ヘルプ（v1.3.0）

Notemod-selfhosted ウェブ用マニュアル v1.3.0

1. 概要

README との違い

2. v1.3.0 の主なポイント

3. 画面別の役割

index.php

account.php

clipboard_sync.php

media_files.php

bak_settings.php

log_settings.php

4. 生成される主な JSON ファイル

テキスト系

画像系

ファイル系

補足

5. API 全体の考え方

6. api.php マニュアル

6-1. 概要

6-2. 受け付け形式

6-3. 共通パラメータ

6-4. テキスト追加 (type=text)

追加パラメータ

仕様

リクエスト例（フォーム形式）

成功レスポンス例

6-5. 画像アップロード (type=image)

追加パラメータ

仕様

リクエスト例

成功レスポンス例

6-6. ファイルアップロード (type=file)

追加パラメータ

仕様

リクエスト例

成功レスポンス例

6-7. 主なエラー

7. read_api.php マニュアル

7-1. 概要

7-2. 受け付け形式

7-3. 共通パラメータ

7-4. pretty の意味

7-5. action 一覧

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

追加パラメータ

仕様

例

7-13. 主なエラー

8. cleanup_api.php マニュアル

8-1. 概要

8-2. 受け付け形式

8-3. 共通パラメータ

8-4. dry_run の意味

8-5. ノート削除（カテゴリ単位）

追加パラメータ

例

8-6. 画像整理 (purge_images)

追加パラメータ

`index.php`

`account.php`

`clipboard_sync.php`

`media_files.php`

`bak_settings.php`

`log_settings.php`

6. `api.php` マニュアル

6-4. テキスト追加 (`type=text`)

6-5. 画像アップロード (`type=image`)

6-6. ファイルアップロード (`type=file`)

7. `read_api.php` マニュアル

7-4. `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` マニュアル

8-4. `dry_run` の意味

8-6. 画像整理 (`purge_images`)

8-7. ファイル整理 (`purge_files`)

8-8. メディア一括整理 (`purge_media`)

8-9. バックアップ削除 (`purge_bak`)

8-10. ログ削除 (`purge_log`)

8-11. バックアップ作成 (`action=backup_now`)

`pretty` の違い

`Forbidden` が出る

画像アップロードで `Unsupported image type`

`latest_image` / `latest_file` が返らない

`cleanup_api.php` が削除してくれない

`api.php`

`read_api.php`

`cleanup_api.php`