#tvote(項目1,項目2,項目3...)

• 同一セッションでは同項目の2重投稿禁止
• 投票数が多い項目順からソート表示
• 項目追加が可能

#tvote(項目1,項目2,項目3)

共通のきまりについて

• ベースURLは `https://w.atwiki.jp/_api/v1/wikis/{wikiid}` 。`{wikiid}` は自分のwikiのID
• 認証は `Authorization: Bearer <アクセストークン>` だけで行う。クエリパラメータやリクエストボディにトークンを入れると、400 `invalid_request` になる
• やり取りはJSON・UTF-8。書き込み（POST・PUT）は `Content-Type: application/json` が必須で、これ以外だと415になる
• 応答には毎回 `Cache-Control: no-store` が付く。クライアント側で応答をキャッシュしない前提で作ること
• 登録したアプリは、登録時に紐付けた1つのwikiでしか使えない。URLの `{wikiid}` に別のwikiのIDを入れると401になる
• スクリプトを書くときは、既定のUser-Agent（curlのものなど）のままにせず、自分のアプリを表す独自のUser-Agentを設定する

エンドポイント一覧

アカウント情報

GET /whoami

curl -s -H "Authorization: Bearer ${ACCESS}" \
  --max-time 15 \
  "https://w.atwiki.jp/_api/v1/wikis/${WIKIID}/whoami"

{
  "subject": "yourwiki:1001",
  "client_id": "3f29a1c2-4b5d-4e6f-8a9b-0c1d2e3f4a5b",
  "wikiid": "yourwiki",
  "scopes": ["user:read"],
  "grant_generation": 1
}

• トークンに `user:read` scopeが無いと403 `insufficient_scope` になる

GET /me

curl -s -H "Authorization: Bearer ${ACCESS}" \
  --max-time 15 \
  "https://w.atwiki.jp/_api/v1/wikis/${WIKIID}/me"

{
  "subject": "yourwiki:1001",
  "wikiid": "yourwiki",
  "user_id": "1001",
  "username": "yourname",
  "role": {
    "is_admin": true,
    "is_sub_admin": false,
    "is_member": true
  },
  "scopes": ["user:read"]
}

• `role` は現在のロールを表す。`is_admin`（管理者かどうか）・`is_sub_admin`（副管理者かどうか）・`is_member`（有効なメンバー登録があるかどうか）はそれぞれ独立した値。管理者だからといって `is_member` が必ずtrueになるとは限らない

ページの読み取り

GET /pages

curl -s -H "Authorization: Bearer ${ACCESS}" \
  --max-time 15 \
  "https://w.atwiki.jp/_api/v1/wikis/${WIKIID}/pages?limit=20"

curl -s -H "Authorization: Bearer ${ACCESS}" \
  --max-time 15 \
  "https://w.atwiki.jp/_api/v1/wikis/${WIKIID}/pages?limit=20&cursor=${CURSOR}"

{
  "items": [
    { "pageid": 1042, "pagename": "サンプルページ", "updated_at": "2026-07-20T03:15:00Z", "permission_read": 0 },
    { "pageid": 1041, "pagename": "サンプルページ（旧）", "updated_at": "2026-07-19T10:02:31Z", "permission_read": 0 }
  ],
  "next_cursor": "MTc4NDQ1NTM1MToxMDQx"
}

• `limit` は既定20・最大100。それより大きい値を指定しても100に切り詰められる
• `next_cursor` を次の呼び出しの `cursor` に渡すと続きが取れる。中身を解釈しようとせず、そのまま渡すこと
• `next_cursor` が `null` なら、それが最後のページ。`next_cursor` のキー自体は最後のページでも必ず入っている（値が `null` になる）ので、キーの有無ではなく値が `null` かどうかで判定する。`null` をそのまま `cursor` に渡すと先頭ページに戻り、繰り返しが終わらなくなる

GET /pages/{pageid}

curl -s -H "Authorization: Bearer ${ACCESS}" \
  --max-time 15 \
  "https://w.atwiki.jp/_api/v1/wikis/${WIKIID}/pages/${PAGEID}"

{
  "pageid": 1042,
  "pagename": "サンプルページ",
  "source": "*見出し\n\n本文の内容がここに入る。",
  "updated_at": "2026-07-20T03:15:00Z",
  "permission_read": 0,
  "tags": "サンプル,メモ",
  "description": "",
  "etag": "\"1042-1784517300\""
}

• 本文は `source` フィールドに入っている（書き込み時のフィールド名 `body` とは違う。詳しくは「読み取りと書き込みでフィールド名が違う」を参照）
• `etag` の値は、そのまま更新（PUT）・削除（DELETE）の `If-Match` に使う。引用符（`"`）も含めて丸ごと控えておく
• `pageid` に数字以外を入れると404になる

ページの書き込み

POST /pages

curl -s -X POST \
  -H "Authorization: Bearer ${ACCESS}" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: ${IDEMPOTENCY_KEY}" \
  --max-time 15 \
  -d '{
  "pagename": "新しいページ",
  "body": "*見出し\n\n本文の内容"
}' \
  "https://w.atwiki.jp/_api/v1/wikis/${WIKIID}/pages"

{
  "data": {
    "pageid": 1050,
    "pagename": "新しいページ",
    "source": "*見出し\n\n本文の内容",
    "updated_at": "2026-07-31T01:00:00Z",
    "etag": "\"1050-1785459600\""
  },
  "meta": {
    "wikiid": "yourwiki",
    "request_id": "A1B2C3D4E5F6A7B8C9D0E1F2A3"
  }
}

• リクエストのボディは `{"pagename": "...", "body": "..."}` の形（応答側の `source` とは名前が違う点に注意）
• 同名のページがすでにあると409 `conflict` になる
• `Idempotency-Key` ヘッダを付けると、同じキーで再送しても二重にページが作られない（ネットワーク断などでの再送に安全）。ただし同じキーで前回と違うボディを送ると422になる。この仕組みはPOSTだけでなくPUT・DELETEでも同様に使える
• 同じキーで再送したときの応答は、`pageid` と `etag`（DELETEでは `deleted`）だけの簡略形になり、`meta` も本文（`pagename`・`source`）も含まれない。再送を前提にするスクリプトでは、`data.pagename` や `meta.request_id` が無い場合を想定して書くこと

PUT /pages/{pageid}

curl -s -X PUT \
  -H "Authorization: Bearer ${ACCESS}" \
  -H "Content-Type: application/json" \
  -H "If-Match: ${ETAG}" \
  --max-time 15 \
  -d '{
  "body": "*見出し（更新後）\n\n更新した本文"
}' \
  "https://w.atwiki.jp/_api/v1/wikis/${WIKIID}/pages/${PAGEID}"

{
  "data": {
    "pageid": 1050,
    "pagename": "新しいページ",
    "source": "*見出し（更新後）\n\n更新した本文",
    "updated_at": "2026-07-31T02:00:00Z",
    "etag": "\"1050-1785463200\""
  },
  "meta": {
    "wikiid": "yourwiki",
    "request_id": "B2C3D4E5F6A7B8C9D0E1F2A3B4"
  }
}

• `body` は本文の全文。送った内容で既存の本文をまるごと置き換える（追記にはならない）
• タグと概要（`tags`・`description`）はPUTでは変更されず、そのまま保持される
• `If-Match` に、更新前に控えたetagを入れる。合わないと409 `conflict` になる（自分が読んだ後に、他の誰かが先に更新したということ）
• `If-Match` はPUTでは省略できる（DELETEとは違い必須ではない）。ただし省略すると、他の誰かが先に更新していても検証されずにそのまま上書きしてしまう。基本的には毎回付けること
• `pagename` の変更は422になる（v1はページ名の変更に対応していない）。リクエストの `body` は必須
• 更新に成功すると `etag` の値も変わる。次に更新するときは、この新しい `etag` を使う
• `Idempotency-Key` ヘッダを付けると再送保護が効く（POSTの節を参照）

DELETE /pages/{pageid}

curl -s -X DELETE \
  -H "Authorization: Bearer ${ACCESS}" \
  -H "If-Match: ${ETAG}" \
  --max-time 15 \
  "https://w.atwiki.jp/_api/v1/wikis/${WIKIID}/pages/${PAGEID}"

{
  "data": {
    "pageid": 1050,
    "deleted": true
  },
  "meta": {
    "wikiid": "yourwiki",
    "request_id": "C3D4E5F6A7B8C9D0E1F2A3B4C5"
  }
}

• `If-Match` は必須。付けずに呼ぶと428 `precondition_required` になる
• 削除は元に戻せない。実行前に本当に消してよいか確認すること
• トップページとメニューページは削除できない（422）
• `Idempotency-Key` ヘッダを付けると再送保護が効く（POSTの節を参照）

ページの検索

GET /search

curl -s -G \
  -H "Authorization: Bearer ${ACCESS}" \
  --max-time 15 \
  --data-urlencode "q=検索したい語句" \
  "https://w.atwiki.jp/_api/v1/wikis/${WIKIID}/search"

{
  "results": [
    { "pageid": 1042, "pagename": "サンプルページ" },
    { "pageid": 1038, "pagename": "サンプルページ（旧）" }
  ],
  "query": "検索したい語句"
}

• 受け付けるクエリは `q` だけ。`q` は必須で、付け忘れたり空文字を渡すと422になる
• `cursor` は使えない。付けると422になる
• 返る件数は最大20件で、それ以上は絞り込みが必要

読み取りと書き込みでフィールド名が違う

次に読むページ

• はじめかた
• エラーと制限

外部連携APIでできること

• ページの取得
• ページの新規作成
• ページの更新
• ページの削除 (※将来対応予定)
• ページの検索

• ページ名の変更
• 添付ファイルの操作

使うための条件

• 対象wikiの管理者であること
• 管理画面の基本設定に「OAuth アプリ管理」が表示されていること（表示されていない場合は現時点で利用できない）
• ページの削除には `wiki:delete` スコープが必要だが、将来対応予定。

アプリを登録する

• アプリ名
• リダイレクト URI（1行に1件、HTTPS必須）
• スコープ（使う権限にチェックする。あとから変更できないので、必要なものは登録時に選ぶ）
• offline_access（リフレッシュトークンを使うならチェックする）

アクセストークンを取得する

1. PKCE の値を作る

VERIFIER=$(openssl rand -base64 96 | tr -d '\n=+/' | cut -c1-64)
CHALLENGE=$(printf '%s' "$VERIFIER" | openssl dgst -sha256 -binary | openssl base64 | tr '+/' '-_' | tr -d '=\n')
STATE=$(openssl rand -hex 16)
echo "VERIFIER=$VERIFIER"
echo "CHALLENGE=$CHALLENGE"
echo "STATE=$STATE"

2. ブラウザで認可画面を開く

https://auth.atwiki.jp/oauth2/auth?response_type=code&client_id=${CID}&redirect_uri=${REDIRECT}&scope=user:read%20wiki:read%20wiki:write%20wiki:search%20offline_access&audience=https://w.atwiki.jp/_api/v1&code_challenge=${CHALLENGE}&code_challenge_method=S256&state=${STATE}

3. 同意する

4. トークンと交換する

curl -s -u "${CID}:${CSECRET}" \
  -d grant_type=authorization_code \
  -d code="${CODE}" \
  --data-urlencode redirect_uri="${REDIRECT}" \
  -d code_verifier="${VERIFIER}" \
  --max-time 15 \
  "https://auth.atwiki.jp/oauth2/token"

{
  "access_token": "<アクセストークン>",
  "refresh_token": "<リフレッシュトークン>",
  "expires_in": 3600,
  "scope": "user:read wiki:read wiki:write wiki:search offline_access",
  "token_type": "bearer"
}

最初のリクエストを送る

curl -s -H "Authorization: Bearer ${ACCESS}" \
  --max-time 15 \
  "https://w.atwiki.jp/_api/v1/wikis/${WIKIID}/whoami"

{
  "subject": "yourwiki:1001",
  "client_id": "3f29a1c2-4b5d-4e6f-8a9b-0c1d2e3f4a5b",
  "wikiid": "yourwiki",
  "scopes": ["user:read", "wiki:read", "wiki:write", "wiki:search"],
  "grant_generation": 1
}

トークンの有効期限と更新

curl -s -u "${CID}:${CSECRET}" \
  -d grant_type=refresh_token \
  -d refresh_token="${REFRESH}" \
  --max-time 15 \
  "https://auth.atwiki.jp/oauth2/token"

次に読むページ

• APIリファレンス
• エラーと制限

外部連携API

[外部連携API]で設定できること

• APIリファレンス
• はじめかた
• エラーと制限

エラーの形

{"error":{"code":"not_found","message":"page not found"}}

エラーコード一覧

• 401 `unauthorized` の応答では、`WWW-Authenticate` レスポンスヘッダーに `error="invalid_token"` のような値が入っていることがある。本文の `code` は常に `unauthorized` なので、エラー判定には本文の`code`を使うこと

リクエストの上限（レート制限）

アプリのエラーと手前の層のエラーを見分ける

安全な取り扱い

• `client_secret` とトークンを公開リポジトリやブラウザで動くJavaScriptに置かない
• 削除は元に戻せないので、`GET` で対象を確かめてから `DELETE`
• scopeは必要なものだけ要求する。ただしアプリ登録後にscopeは変更できないので、使う予定のあるものは登録時に選んでおく
• トークンが漏れたら、管理画面でアプリを無効化する

次に読むページ

• はじめかた
• APIリファレンス