メインコンテンツまでスキップ

外部クライアント向けAPIの仕様

APIのベースURLは以下のとおりです。

環境URL
本番環境https://metatell.app

すべてのリクエストに、認証とアクセストークンの取得で取得したアクセストークンが必要です。

Authorization: Bearer <access-token>

レート制限​

外部クライアント向けAPIでは、外部APIクライアントごとに1秒あたり10リクエストのレート制限が適用されます。一時的なバーストは最大20リクエストまで許可されます。GETとPATCHのどちらも1リクエストとして数えられます。

レート制限に関する情報は、次のレスポンスヘッダーで確認できます。

ヘッダー説明
RateLimit-Limitバーストを含めて連続して実行できる最大リクエスト数
RateLimit-Remainingすぐに実行できる残りのリクエスト数
RateLimit-Reset次のリクエストを実行できるようになるまでの秒数

レート制限を超えると、429 rate_limit_exceededが返ります。Retry-Afterヘッダーに指定された秒数を待ってから再試行してください。

{
  "error": "rate_limit_exceeded",
  "message": "Rate limit exceeded"
}

ルームロールAPI​

ルームロール割当取得API​

対象のルームロールの直接割当を取得します。

対象メソッドパス
ユーザーGET/api/v3/organizations/{organizationId}/rooms/{roomId}/room-role-assignments/users/{userId}
グループGET/api/v3/organizations/{organizationId}/rooms/{roomId}/room-role-assignments/groups/{groupId}
ログインユーザーの既定ロールGET/api/v3/organizations/{organizationId}/rooms/{roomId}/room-role-assignments/authenticated-default
未ログインユーザーのロールGET/api/v3/organizations/{organizationId}/rooms/{roomId}/room-role-assignments/anonymous

レスポンス​

対象にルームロールが直接割り当てられていない場合、roleはnullです。subjectIdには、ユーザーを対象とする場合はユーザーID、グループを対象とする場合はグループIDが入ります。

{
  "requestId": "request-id",
  "assignment": {
    "target": "user",
    "roomId": "room-id",
    "subjectId": "user-id",
    "role": {
      "id": 3,
      "name": "ルーム管理者"
    }
  }
}

ルームロール割当変更API​

対象のルームロールの直接割当を変更します。

対象メソッドパス
ユーザーPATCH/api/v3/organizations/{organizationId}/rooms/{roomId}/room-role-assignments/users/{userId}
グループPATCH/api/v3/organizations/{organizationId}/rooms/{roomId}/room-role-assignments/groups/{groupId}
ログインユーザーの既定ロールPATCH/api/v3/organizations/{organizationId}/rooms/{roomId}/room-role-assignments/authenticated-default
未ログインユーザーのロールPATCH/api/v3/organizations/{organizationId}/rooms/{roomId}/room-role-assignments/anonymous

リクエスト​

フィールド必須説明
roleId必須設定するルームロールID。直接割当を解除する場合はnull
ifRoleId任意現在のロールがこの値の場合だけ変更する。省略した場合は現在のロールを条件にしない
{
  "roleId": 3,
  "ifRoleId": 2
}

更新に成功するとstatusはupdated、すでに同じロールの場合はunchanged、割当を解除した場合はclearedになります。

{
  "status": "updated",
  "requestId": "request-id",
  "assignment": {
    "target": "user",
    "roomId": "room-id",
    "subjectId": "user-id",
    "role": {
      "id": 3,
      "name": "ルーム管理者"
    }
  }
}

ifRoleIdと現在のロールが一致しない場合、HTTP 200で次の結果が返り、変更されません。

{
  "status": "unchanged",
  "reason": "role_changed_by_other",
  "requestId": "request-id",
  "assignment": {
    "target": "user",
    "roomId": "room-id",
    "subjectId": "user-id",
    "role": {
      "id": 2,
      "name": "一般ユーザー"
    }
  }
}

組織ロールAPI​

組織ロールは、対象組織に所属済みのユーザーだけ取得・変更できます。ユーザーの招待や追加、削除には使用できません。

組織ロール割当取得API​

GET /api/v3/organizations/{organizationId}/organization-role-assignments/users/{userId}

レスポンスの形式はルームロール割当取得APIと同様です。assignmentにはorganizationIdとsubjectId（ユーザーID）が含まれ、roomIdは含まれません。

{
  "requestId": "request-id",
  "assignment": {
    "target": "user",
    "organizationId": "organization-id",
    "subjectId": "user-id",
    "role": {
      "id": 2,
      "name": "一般ユーザー"
    }
  }
}

組織ロール割当変更API​

PATCH /api/v3/organizations/{organizationId}/organization-role-assignments/users/{userId}

リクエストのフィールドはルームロール割当変更APIと同じですが、roleIdは必須であり、nullは指定できません。組織ロールの解除には対応していません。

{
  "roleId": 0,
  "ifRoleId": 2
}

エラーレスポンス​

エラーはerrorとmessageを持つJSONで返ります。

{
  "error": "forbidden",
  "message": "Request is not permitted"
}
HTTPステータスerror対処
401invalid_tokenclient assertion、登録済みkid、トークンの有効期限を確認する
403forbiddenクライアントのAPI権限、対象ルーム、設定可能なロールを確認する
404not_found組織、ルーム、対象ユーザー／グループ、ロールIDを確認する
422invalid_requestJSONとroleIdを確認する
429rate_limit_exceededRetry-Afterヘッダーに指定された秒数を待ってから再試行する
503service_unavailableリクエストを再試行する
503rate_limit_unavailableリクエストを再試行する

認証基盤を利用できない場合、503 authentication_unavailableを返すことがあります。

に最終更新