組織
orgs カテゴリの API 操作 14 件を説明します。
| メソッド | パス | 説明 |
|---|---|---|
| GET | /v1/orgs | — |
| POST | /v1/orgs | org を作成する |
| PATCH | /v1/orgs/{orgSlug} | org の表示名の変更（runlot org rename） |
| DELETE | /v1/orgs/{orgSlug} | org の削除（runlot org delete） |
| GET | /v1/orgs/{orgSlug}/notifications | 最近の通知 |
| GET | /v1/orgs/{orgSlug}/members | 組織メンバーの一覧（runlot org members） |
| POST | /v1/orgs/{orgSlug}/members | 既存のユーザーをメンバーとして追加します（運用・自動化向け） |
| GET | /v1/orgs/{orgSlug}/invites | 保留中の招待（runlot member invites） |
| POST | /v1/orgs/{orgSlug}/invites | メールで招待します（runlot member invite） |
| DELETE | /v1/orgs/{orgSlug}/invites/{inviteId} | 招待を取り消します（runlot member uninvite） |
| GET | /v1/invites/{token} | 招待をプレビューします（認証不要） |
| POST | /v1/invites/{token}/accept | 招待を承諾します |
| PUT | /v1/orgs/{orgSlug}/members/{userId} | ロールを変更する（runlot org set-role） |
| DELETE | /v1/orgs/{orgSlug}/members/{userId} | メンバーを削除する、または自分から脱退します（runlot member rm、runlot member leave） |
GET /v1/orgs
operationId listOrgs
| ステータスコード | 説明 | レスポンスボディ |
|---|---|---|
| 200 | 所属している組織 | object |
| 401 | — | — |
POST /v1/orgs
作成者はadminになります。個人アカウントは単に1人だけの組織なので、専用のパスはありません。
operationId createOrg
リクエストボディ: application/json ・ object
| ステータスコード | 説明 | レスポンスボディ |
|---|---|---|
| 201 | 作成された組織 | Org |
| 401 | — | — |
| 409 | — | — |
PATCH /v1/orgs/{orgSlug}
admin 以上が必要です。org.rename として監査されます。
ここで変更できるのは表示名のみです。 スラッグはアドレスの一部であり——<project>.<slug>.runlot.app、証明書のSAN、クローンURL、リポジトリにコミットされたrunlot.json内の"org"フィールド——名前を変更することはできません。
operationId updateOrg
リクエストボディ: application/json ・ object
| ステータスコード | 説明 | レスポンスボディ |
|---|---|---|
| 200 | 更新後の org | OrgMembership |
| 400 | — | — |
| 403 | — | — |
| 404 | — | — |
DELETE /v1/orgs/{orgSlug}
admin 以上が必要です。これは取り消せません。
confirmフィールドには組織のスラッグを正確に指定する必要があります（先頭と末尾の空白は削除されます）。
削除には2つの段階があり、待つ必要があるのは最初の段階だけです。 レスポンスは組織を削除済みとしてマークします：組織一覧から消え、組織スコープのすべてのルートは404を返し、保留中の招待は機能しなくなり、スラッグはすぐに再利用可能になります。データは保持期間（デフォルトでは1か月）の経過後に消去されます。レスポンス内のpurgeAfterがその時点です——保持期間は変更される可能性があるため、自分で計算せずレスポンスから読み取ってください。
削除は組織が空の場合にのみ成功します。 プロジェクト、ドメイン、リポジトリ、またはDNSゾーンが残っている場合、レスポンスは409 org_not_emptyとなり、エンベロープのdetails.holdingsに種類ごとの件数といくつかの名前が一覧表示されます。すでに削除したプロジェクトはカウントされません——それらは組織より先に、独自の保持期間のタイミングで消えます。
他に2つの拒否理由があります。個人組織の場合はpersonal_orgが返されます（初回ログイン時に作成された組織で、削除できません）。有効な有料サブスクリプションがある場合はactive_subscriptionが返されます——先にサブスクリプションを解約してください。
org.delete監査イベントは組織より長く残り、targetにスラッグを保持し続けます。
operationId deleteOrg
リクエストボディ: application/json ・ object
| ステータスコード | 説明 | レスポンスボディ |
|---|---|---|
| 202 | 削除済みとしてマークされます——現時点であらゆる画面から消え、データはpurgeAfter後に消去されます | OrgDeleted |
| 400 | — | — |
| 403 | — | — |
| 404 | — | — |
| 409 | 空でない（org_not_empty）・個人 org（personal_org）・有効なサブスクリプション（active_subscription） | Error |
GET /v1/orgs/{orgSlug}/notifications
組織の上限・バックアップ・リストアイベントを新しい順に表示します。
sentAtが設定されている場合、メールも送信済みです。設定されていない行は、まだキューにあるか、送信先アドレスがないかのいずれかです——GitHubの非公開メールでサインインしたアカウントには登録メールアドレスがなく、この一覧が唯一の通知手段になります。
viewer 以上が必要です。
operationId listNotifications
| パラメーター | 場所 | 必須 | 型 | 説明 |
|---|---|---|---|---|
limit | query | 不可 | integer | — |
| ステータスコード | 説明 | レスポンスボディ |
|---|---|---|
| 200 | 通知一覧 | object |
| 403 | — | — |
| 404 | — | — |
GET /v1/orgs/{orgSlug}/members
member 以上が必要です。
operationId listMembers
| ステータスコード | 説明 | レスポンスボディ |
|---|---|---|
| 200 | メンバー一覧 | object |
| 403 | — | — |
| 404 | — | — |
POST /v1/orgs/{orgSlug}/members
これは招待ではありません。 ユーザーはすでに一度はサインインしている必要があり、provider + subjectで識別されます。該当するユーザーが存在しない場合は404 user_not_foundが返されます。すでにメンバーである場合は409 already_memberが返されます——ロールを変更するにはPUTを使用してください。
メールで招待するには、代わりにPOST …/invitesを使用してください。このエンドポイントは、プロバイダーのsubject idをすでに把握している自動化処理向けです。
admin以上のロールが必要です。監査ログにはmember.addとして記録されます。
operationId addMember
リクエストボディ: application/json ・ object
| ステータスコード | 説明 | レスポンスボディ |
|---|---|---|
| 201 | メンバーが追加されました | Member |
| 400 | — | — |
| 403 | — | — |
| 404 | 組織が存在しない、またはユーザーが存在しません(user_not_found) | Error |
| 409 | 既にメンバーです(already_member) | Error |
GET /v1/orgs/{orgSlug}/invites
admin以上のロールが必要です。 招待一覧にはまだ組織に参加していない人のメールアドレスが含まれるため、メンバー一覧よりも高いロールが必要です。
承諾済みまたは取り消し済みの招待は表示されません——その履歴は監査ログにあります。期限切れの招待は表示されるため、管理者は再送信できます。
operationId listInvites
| ステータスコード | 説明 | レスポンスボディ |
|---|---|---|
| 200 | 招待の一覧 | object |
| 403 | — | — |
| 404 | — | — |
POST /v1/orgs/{orgSlug}/invites
admin以上のロールが必要です。メールは即時送信ではなくキューに入れられます——sentAtが空の場合はまだ送信されていないことを意味します。
同じアドレスでこれを再度呼び出すと招待が再送されます：既存の招待が新しいトークンと有効期限で更新され（ロールが変わることもあります）、200 を返します。まったく新しい招待の場合は 201 を返します。
すでにメンバーであるアドレスの場合は 409 already_member を返します。保留中の招待が多すぎる場合は 409 too_many_invites を返します。
招待の有効期間は 7 日間で、1 回限り使用可能で、いつでも取り消せます。監査ログには member.invite として記録されます。
operationId createInvite
リクエストボディ: application/json ・ object
| ステータスコード | 説明 | レスポンスボディ |
|---|---|---|
| 200 | 既存の招待を再送しました | Invite |
| 201 | 新規の招待 | Invite |
| 400 | — | — |
| 403 | — | — |
| 404 | — | — |
| 409 | すでにメンバーです（already_member）、または保留中の招待が多すぎます（too_many_invites） | Error |
DELETE /v1/orgs/{orgSlug}/invites/{inviteId}
admin 以上が必要です。まだ送信されていないメールは送信されません——取り消すと送信キューからも削除されます。すでに承諾済みまたは取り消し済みの招待は 404 を返します。監査ログには member.uninvite として記録されます。
operationId revokeInvite
| ステータスコード | 説明 | レスポンスボディ |
|---|---|---|
| 204 | 取り消し済み | — |
| 403 | — | — |
| 404 | — | — |
GET /v1/invites/{token}
認証は不要です。 招待リンクを受け取った人はまだサインインしておらず、招待の内容を確認する必要があります。トークンは 32 バイトのランダムな値であるため推測できず、開いても org 名しか表示されません。
招待の状態はエラーではなく値です（state）。これにより、クライアントは期限切れのリンクと誤ったリンクを区別できます。
不明なトークンは 404 を返します — ずっと前に取り消されたトークンと同じ応答です。
operationId getInvite
| ステータスコード | 説明 | レスポンスボディ |
|---|---|---|
| 200 | 招待 | InviteView |
| 404 | — | — |
POST /v1/invites/{token}/accept
ログインが必要です。サインイン中のアカウントのメールアドレスは、招待先のアドレスと一致している必要はありません——非公開の GitHub メールでサインインしたアカウントには、そもそもメールアドレスが登録されていません。その代わり、招待の有効期間は 7 日間で、1 回限り使用可能で、いつでも取り消すことができ、監査記録には招待先アドレスと承諾したアカウントの両方が保持されます。
すでにメンバーである場合、そのロールは変更されません（alreadyMember: true）。
監査ログには member.accept として記録されます。
operationId acceptInvite
| ステータスコード | 説明 | レスポンスボディ |
|---|---|---|
| 200 | 承諾済み | object |
| 401 | — | — |
| 404 | — | — |
| 409 | すでに承諾済み(invite_used)、取り消し済み(invite_revoked)、または期限切れ(invite_expired) | Error |
PUT /v1/orgs/{orgSlug}/members/{userId}
admin 以上が必要です。最後の admin を降格させることはできません（409 last_admin）。自分自身であっても同様です——org には常に管理できる人が必要です。監査ログには member.role として記録されます。
operationId setMemberRole
リクエストボディ: application/json ・ object
| ステータスコード | 説明 | レスポンスボディ |
|---|---|---|
| 200 | 変更されたメンバー | Member |
| 400 | — | — |
| 403 | — | — |
| 404 | — | — |
| 409 | これは最後の admin です(last_admin) | Error |
DELETE /v1/orgs/{orgSlug}/members/{userId}
他のメンバーを削除するには admin 以上が必要ですが、自分自身を削除することは誰にでも許可されています——userId が自分自身のものである場合、これは org からの脱退になります。
最後の admin は削除できず、脱退することもできません（409 last_admin）。監査ログには、削除は member.remove、脱退は member.leave として記録されます。
operationId removeMember
| ステータスコード | 説明 | レスポンスボディ |
|---|---|---|
| 204 | 削除済み | — |
| 403 | — | — |
| 404 | — | — |
| 409 | これは最後の admin です(last_admin) | Error |