Docs

API リファレンス

Abstria の目標データ（YAP / MAP / WAP / DAP）をプログラムから操作する REST API。一覧取得・一括登録・エクスポート・削除に対応します。

最終更新 2026年6月16日

Abstria の REST API を使うと、目標データをプログラムから読み書きできます。自分用のシードデータ投入・バックアップ・外部ツール連携（CLI / ChatGPT / Zapier など）を想定しています。

概要

すべてのエンドポイントは次のベース URL を基点とします。

https://abstria.app/api/v1

レスポンスは原則 JSON（Content-Type: application/json）です。エクスポートのみ用途に応じて ZIP を返します。

データモデル

Abstria の目標は 4 階層のツリーです。

略称	名称	粒度
YAP	Year Action Plan	年間の目標
MAP	Month Action Plan	月間の目標（YAP に属する）
WAP	Week Action Plan	週間の目標（MAP に属する）
DAP	Day Action Plan（task）	日次タスク（WAP に紐付く）

YAP → MAP → WAP は親が NOT NULL の厳密な木構造です。DAP（タスク）は独立したテーブルで、task_wap_links を介して複数の WAP に紐付けられます。

認証

すべてのエンドポイントは認証が必要です。2 通りの方法があります。

API キー（外部ツール向け）

Authorization ヘッダーに Bearer トークンとして API キーを渡します。

Authorization: Bearer abs_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

API キーの 発行・ローテート・失効は設定画面の「API」セクション（設定 → API、Pro プラン限定）から行えます。生成されたキーは発行直後に 1 度だけ表示され、サーバーには SHA-256 ハッシュのみが保存されます。紛失した場合は再発行してください。

1 ユーザーあたり有効なキーは最大 10 個です。
有効期限は無期限・30 日・90 日・365 日から選べます。

Cookie セッション

ブラウザ内から fetch(..., { credentials: "include" }) で呼ぶ場合は、ログイン済みのセッション Cookie がそのまま使われます。外部ツールからは API キーを使ってください。

認証エラー

Status	error	意味
401	`unauthorized`	セッションが無効、または未ログイン
401	`invalid_api_key_format`	`abs_live_` 形式でない
401	`invalid_api_key`	キーが存在しない／失効済み
401	`expired_api_key`	キーの有効期限切れ

レート制限

API キー経由のリクエストには per-key の固定ウィンドウ制限を適用します（Cookie セッションは対象外）。

項目	値
上限	60 リクエスト / 60 秒（キーごと）
方式	固定ウィンドウ
超過時	`429 { "error": "rate_limited" }`

上限を超えると 429 を返し、Retry-After ヘッダーに再試行までの秒数を入れます。クライアント側ではこの値だけ待って再送してください。

エラー

エラー応答はすべて JSON で、error フィールドにエラーコードが入ります。

{ "error": "validation_failed", "details": { "...": "..." } }

Status	主な error	意味
400	`invalid_json`, `invalid_id`	リクエストの形式が不正
401	（認証セクション参照）	認証失敗
404	`not_found`	対象が存在しない／自分のものでない
422	`validation_failed`	入力バリデーション失敗（`details` に詳細）
422	`constraint_violation`	DB 制約違反（上限超過・重複など）
429	`rate_limited`	レート上限超過
500	`query_failed`, `rpc_failed`, `export_failed`	サーバー側エラー

書き込み系（登録・削除）はエラー時に 全レコードがロールバックされ、中途半端な状態は残りません（all-or-nothing）。

一覧を取得 — GET /api/v1/yaps

認証ユーザーの YAP を返します。削除に渡す id の確認や、エクスポートの軽量版として使えます。

クエリ	値	説明
`include`	`tree`	配下の MAP / WAP / DAP をネストして返す

# フラット（YAP のみ）
curl -sS "https://abstria.app/api/v1/yaps" \
  -H "Authorization: Bearer $ABSTRIA_API_KEY"

{
  "yaps": [
    {
      "id": "uuid",
      "title": "2026年の目標",
      "description": null,
      "start_date": "2026-01-01",
      "end_date": "2026-12-31",
      "status": "in_progress",
      "sort_order": 0,
      "created_at": "2026-01-01T00:00:00.000Z"
    }
  ]
}

?include=tree を付けると、各 YAP の下に maps → waps → daps がネストされます。各階層は sort_order → created_at の昇順です。複数の WAP に紐付くタスクは、それぞれの WAP の下に重複して現れます。

件数を取得 — GET /api/v1/stats

認証ユーザーの全エンティティ件数を返します。削除後の検証などに使えます。

curl -sS "https://abstria.app/api/v1/stats" \
  -H "Authorization: Bearer $ABSTRIA_API_KEY"

{
  "ok": true,
  "counts": {
    "yaps": 1,
    "maps": 12,
    "waps": 48,
    "tasks": 120,
    "tasks_unlinked": 8
  }
}

maps / waps は親が NOT NULL + cascade のため孤児が発生しません。
tasks_unlinked は、どの WAP にも紐付かないタスク（雑務や共有解除後のタスク）の件数です。YAP 起点の一覧では見えないので、ここで確認します。

エクスポート — GET /api/v1/export

認証ユーザーの全データ（YAP / MAP / WAP / タスク / 紐付け）をダウンロード形式で返します。

クエリ	値	説明
`format`	`json`（既定）	復元可能な単一 JSON。`imports` の復元形式と互換
`format`	`csv`	テーブルごとの CSV をまとめた ZIP

# JSON（インポートで復元できる形式）
curl -sS "https://abstria.app/api/v1/export?format=json" \
  -H "Authorization: Bearer $ABSTRIA_API_KEY" \
  -o abstria-export.json

# CSV（ZIP）
curl -sS "https://abstria.app/api/v1/export?format=csv" \
  -H "Authorization: Bearer $ABSTRIA_API_KEY" \
  -o abstria-export.zip

レスポンスは Content-Disposition: attachment 付きで返ります。format=json の出力はそのまま POST /api/v1/imports の復元形式として読み込めます。

一括登録 — POST /api/v1/imports

ネストした JSON を 1 リクエストで一括登録します。リクエストボディの形によって 2 つのモードを自動判別します。

ツリー形式 … 新規作成。maps → waps → daps をネストして渡す。
復元形式 … エクスポート JSON をそのまま渡してバックアップから復元する（id を含むフラット配列）。

以下はツリー形式の例です。

{
  "yaps": [
    {
      "title": "2026年の目標",
      "start_date": "2026-01-01",
      "end_date": "2026-12-31",
      "status": "pending",
      "maps": [
        {
          "title": "5月",
          "start_date": "2026-05-01",
          "end_date": "2026-05-31",
          "waps": [
            {
              "title": "第3週",
              "start_date": "2026-05-11",
              "end_date": "2026-05-17",
              "is_important": true,
              "daps": [
                {
                  "title": "資料作成",
                  "scheduled_date": "2026-05-15",
                  "start_time": "09:00",
                  "end_time": "11:00"
                },
                { "title": "レビュー" }
              ]
            }
          ]
        }
      ]
    }
  ]
}

フィールド

レベル	必須	省略可
yap	`title`, `start_date`	`end_date`（省略時は `start_date` の年の 12/31）, `description`, `sort_order`, `status`, `maps`
map	`title`, `start_date`, `end_date`	`description`, `sort_order`, `status`, `waps`
wap	`title`, `start_date`, `end_date`	`description`, `sort_order`, `status`, `is_urgent`, `is_important`, `daps`
dap（task）	`title`	`description`, `status`, `scheduled_date`, `start_time`, `end_time`, `sort_order`, `due_date`, `recurrence_*`, `is_urgent`, `is_important`

日付は YYYY-MM-DD、時刻は HH:MM または HH:MM:SS の文字列のみ。
status は pending / in_progress / done。
ペイロード内の user_id は無視され、認証から解決した user_id が常に使われます。
sort_order を省略すると自動採番されます（MAP は start_date の月インデックス 0–11、WAP / DAP / YAP は配列の並び順）。明示すればその値が優先されます。

上限

1 リクエストあたり YAP は 10 件まで。
1 YAP に MAP 12 件、1 MAP に WAP 8 件、1 WAP に DAP 200 件まで。
同じ YAP 内で (yap_id, start_date) が重複する MAP は弾かれます。
プランごとの保有上限（Free 3 件 / Pro 上限あり）は別途適用されます。

レスポンス

{
  "ok": true,
  "mode": "tree",
  "result": {
    "yap_ids": ["uuid"],
    "map_ids": ["uuid"],
    "wap_ids": ["uuid"],
    "dap_ids": ["uuid", "uuid"],
    "counts": { "yaps": 1, "maps": 1, "waps": 1, "daps": 2 }
  }
}

成功時は 201 Created。返された yap_ids は、そのまま一括削除に渡せます。

YAP を削除 — DELETE /api/v1/yaps/{id}

YAP を 1 件削除します。配下の MAP / WAP は cascade で消え、その subtree 専用の DAP タスクも一緒に削除されます（複数の AP に紐付くタスクは紐付けのみ外れ、本体は残ります）。

クエリ	値	説明
`dry_run`	`true`	削除せず影響件数だけを返す（プレビュー）

dry-run（プレビュー）

破壊的操作なので、消す前に影響件数を確認できます。

curl -X DELETE "https://abstria.app/api/v1/yaps/<id>?dry_run=true" \
  -H "Authorization: Bearer $ABSTRIA_API_KEY"

{
  "ok": true,
  "dry_run": true,
  "yap": { "id": "...", "title": "..." },
  "impact": { "maps": 12, "waps": 72, "tasks_to_delete": 0, "tasks_to_unlink": 0 }
}

tasks_to_delete — この YAP の subtree にしか紐付かないタスク（本体が削除される）
tasks_to_unlink — subtree 外の WAP にも紐付くタスク（紐付けのみ外れ、本体は残る）

実削除

curl -X DELETE "https://abstria.app/api/v1/yaps/<id>" \
  -H "Authorization: Bearer $ABSTRIA_API_KEY" -w "\n[HTTP %{http_code}]\n"

Status	意味
204 No Content	削除成功
400 `invalid_id`	UUID 形式が不正
404 `not_found`	存在しない／他人の YAP（存在有無は区別しません）

YAP を一括削除 — DELETE /api/v1/yaps

複数の YAP をまとめて削除します。挙動は単体版と同じで、全 id を 1 トランザクションで削除します（all-or-nothing）。インポートが返した yap_ids をそのまま渡せます。

curl -X DELETE "https://abstria.app/api/v1/yaps" \
  -H "Authorization: Bearer $ABSTRIA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"ids":["<uuid1>","<uuid2>"]}'

{ "ok": true, "deleted": ["<uuid1>", "<uuid2>"] }

?dry_run=true を付けると、削除せず合計と YAP ごとの内訳を返します。

Status	意味
200	成功（`{ok,deleted}` または `{ok,dry_run,...}`）
404 `not_found`	不在／他人の id を含む（`missing` に列挙。何も削除しません）
422 `validation_failed`	`ids` が不正（1〜100 件の UUID 配列）

1 件でも所有外・不在の id が混ざると、安全のため全体を中止して 404 を返します（部分削除はしません）。

クイックスタート

API キーを発行したら、まず件数を確認してみましょう。

export ABSTRIA_API_KEY="abs_live_..."

# 現在の件数を確認
curl -sS "https://abstria.app/api/v1/stats" \
  -H "Authorization: Bearer $ABSTRIA_API_KEY"

# JSON ファイルから一括登録
curl -X POST "https://abstria.app/api/v1/imports" \
  -H "Authorization: Bearer $ABSTRIA_API_KEY" \
  -H "Content-Type: application/json" \
  -d @goals.json