ロールを取得・変更・削除する

対象IDを指定する

各操作では共有URL末尾のUUIDを {id} に指定します。APIキーのアカウントが所有するロールだけを操作できます。

https://ror.jp/api/v1/pins/{id}

以下の例では、実際のUUIDを PIN_ID に設定してから実行してください。

PIN_ID='<uuid>'

GETで状態を取得する

curl --fail-with-body --silent --show-error \
  "https://ror.jp/api/v1/pins/$PIN_ID" \
  -H "Authorization: Bearer $ROR_API_KEY"

成功すると、タイトル、状態、共有URL、合言葉保護の有無、ピン留め状態、公開日時、期限、ファイル数、サイズなどを含む pin を返します。

PATCHで1項目だけ変更する

1回のPATCHには、title、reset_expiration、password のうち正確に1つだけを指定します。複数の操作や未知の項目を送ると、変更せずに 422 invalid_update を返します。

操作	値と動作
title	255文字以内の文字列。空文字または null で消去
reset_expiration	true のみ。リクエスト時点から正確に7日後へ変更
password	8文字以上・UTF-8で72バイト以下。空文字または null で解除

期限をリセットする例です。

curl --fail-with-body --silent --show-error \
  -X PATCH "https://ror.jp/api/v1/pins/$PIN_ID" \
  -H "Authorization: Bearer $ROR_API_KEY" \
  -H 'Content-Type: application/json' \
  --data '{"reset_expiration":true}'

reset_expirationを利用できるのは、公開中・期限内・未ピン留めのロールだけです。ピン留め中や期限切れのロールには利用できず、期限切れの共有URLは復元できません。期限のリセットや合言葉の変更・解除を行うと、それまでに発行された閲覧grantは失効します。

DELETEで公開を停止する

curl --fail-with-body --silent --show-error \
  -X DELETE "https://ror.jp/api/v1/pins/$PIN_ID" \
  -H "Authorization: Bearer $ROR_API_KEY"

成功は本文なしの 204 No Content です。共有URLへのアクセスは直ちに無効になり、保存データは後続のクリーンアップで物理削除されます。すでに削除済みなど、現在の状態から削除できない場合は 409 invalid_state です。

APIではできない変更

APIからピン留め、ピン留め解除、公開済みロールのコンテンツ差し替えはできません。ピン留めは管理画面で操作します。コンテンツを変える場合は、新しいZIPを POST /api/v1/pins で公開し、新しい共有URLを使用してください。