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

metatell外部クライアント向けAPI (1.0.0)

Download OpenAPI specification:Download

外部APIクライアントから、ルームロール、組織ロール、グループ、グループ所属を操作するAPIです。

認証

すべてのリクエストにAuthorization: Bearer <アクセストークン>を付けます。アクセストークンは、管理画面に表示されるtoken endpointから、client_credentialsとprivate_key_jwt(ES256)で取得します。手順は認証とアクセストークンの取得を参照してください。

各APIには、説明に記載したスコープをクライアントに付与しておく必要があります。organization_idには、クライアントが所属する組織のIDを指定します。

レート制限

外部APIクライアントごとにレート制限があります。レスポンスのratelimit-limit、ratelimit-remaining、ratelimit-resetヘッダーで状況を確認できます。上限を超えると429を返し、retry-afterヘッダーに再試行までの秒数が入ります。

再試行

429、503、通信エラーのときは同じリクエストを再送できます。ロールの変更は値の設定、所属の変更は状態の設定、グループの作成は同じ名前の既存グループを返すため、再送しても結果は変わりません。ただし、最初のリクエストが反映済みだった場合、再送の応答は次のように初回と異なります。

  • ifRoleId付きのロール変更:status: unchanged、reason: role_changed_by_otherを返します。assignment.roleが指定したロール(解除の場合はnull)になっていれば、変更は反映済みです。
  • グループの削除:404を返します。削除済みとして扱えます。

リクエストID

すべてのレスポンスにx-request-idヘッダーが付きます(20〜200文字の値をリクエストで指定することもできます)。成功時のレスポンスには同じ値がrequestIdとして入ります。問い合わせの際はこの値をお知らせください。

ルームロール

未ログインユーザーのルームロールを取得

直接割り当てられていない場合、roleはnullです。

必要なスコープ:room_roles:anonymous:read

Authorizations:
bearerAuth
path Parameters
organization_id
required
string

クライアントが所属する組織のID。

room_id
required
string

ルームID(ルームURLに含まれるID)。

Responses

Response samples

Content type
application/json
{
  • "assignment": {
    },
  • "requestId": "string"
}

未ログインユーザーのルームロールを変更

roleIdにnullを指定すると直接割当を解除します。ifRoleIdを指定すると、現在のロールが一致する場合だけ変更します。一致しない場合はHTTP 200でstatus: unchanged、reason: role_changed_by_otherを返し、変更しません。

必要なスコープ:room_roles:anonymous:write

Authorizations:
bearerAuth
path Parameters
organization_id
required
string

クライアントが所属する組織のID。

room_id
required
string

ルームID(ルームURLに含まれるID)。

Request Body schema: application/json
required

変更内容

ifRoleId
integer or null <int64> [ 0 .. 9223372036854776000 ]

現在の直接割当のロールIDがこの値の場合だけ変更する。一致しない場合はHTTP 200でstatus: unchanged、reason: role_changed_by_otherを返し、変更しない。

roleId
required
integer or null <int64> [ 0 .. 9223372036854776000 ]

設定するルームロールID。nullを指定すると直接割当を解除する。

Responses

Request samples

Content type
application/json
{
  • "ifRoleId": 0,
  • "roleId": 0
}

Response samples

Content type
application/json
{
  • "assignment": {
    },
  • "reason": "role_changed_by_other",
  • "requestId": "string",
  • "status": "updated"
}

ログインユーザーの既定ルームロールを取得

直接割り当てられていない場合、roleはnullです。

必要なスコープ:room_roles:authenticated_default:read

Authorizations:
bearerAuth
path Parameters
organization_id
required
string

クライアントが所属する組織のID。

room_id
required
string

ルームID(ルームURLに含まれるID)。

Responses

Response samples

Content type
application/json
{
  • "assignment": {
    },
  • "requestId": "string"
}

ログインユーザーの既定ルームロールを変更

roleIdにnullを指定すると直接割当を解除します。ifRoleIdを指定すると、現在のロールが一致する場合だけ変更します。一致しない場合はHTTP 200でstatus: unchanged、reason: role_changed_by_otherを返し、変更しません。

必要なスコープ:room_roles:authenticated_default:write

Authorizations:
bearerAuth
path Parameters
organization_id
required
string

クライアントが所属する組織のID。

room_id
required
string

ルームID(ルームURLに含まれるID)。

Request Body schema: application/json
required

変更内容

ifRoleId
integer or null <int64> [ 0 .. 9223372036854776000 ]

現在の直接割当のロールIDがこの値の場合だけ変更する。一致しない場合はHTTP 200でstatus: unchanged、reason: role_changed_by_otherを返し、変更しない。

roleId
required
integer or null <int64> [ 0 .. 9223372036854776000 ]

設定するルームロールID。nullを指定すると直接割当を解除する。

Responses

Request samples

Content type
application/json
{
  • "ifRoleId": 0,
  • "roleId": 0
}

Response samples

Content type
application/json
{
  • "assignment": {
    },
  • "reason": "role_changed_by_other",
  • "requestId": "string",
  • "status": "updated"
}

グループのルームロール割当を取得

直接割り当てられていない場合、roleはnullです。

必要なスコープ:room_roles:group:read

Authorizations:
bearerAuth
path Parameters
organization_id
required
string

クライアントが所属する組織のID。

room_id
required
string

ルームID(ルームURLに含まれるID)。

group_id
required
string

グループID。

Responses

Response samples

Content type
application/json
{
  • "assignment": {
    },
  • "requestId": "string"
}

グループのルームロール割当を変更

roleIdにnullを指定すると直接割当を解除します。ifRoleIdを指定すると、現在のロールが一致する場合だけ変更します。一致しない場合はHTTP 200でstatus: unchanged、reason: role_changed_by_otherを返し、変更しません。

必要なスコープ:room_roles:group:write

Authorizations:
bearerAuth
path Parameters
organization_id
required
string

クライアントが所属する組織のID。

room_id
required
string

ルームID(ルームURLに含まれるID)。

group_id
required
string

グループID。

Request Body schema: application/json
required

変更内容

ifRoleId
integer or null <int64> [ 0 .. 9223372036854776000 ]

現在の直接割当のロールIDがこの値の場合だけ変更する。一致しない場合はHTTP 200でstatus: unchanged、reason: role_changed_by_otherを返し、変更しない。

roleId
required
integer or null <int64> [ 0 .. 9223372036854776000 ]

設定するルームロールID。nullを指定すると直接割当を解除する。

Responses

Request samples

Content type
application/json
{
  • "ifRoleId": 0,
  • "roleId": 0
}

Response samples

Content type
application/json
{
  • "assignment": {
    },
  • "reason": "role_changed_by_other",
  • "requestId": "string",
  • "status": "updated"
}

ユーザーのルームロール割当を取得

直接割り当てられていない場合、roleはnullです。

必要なスコープ:room_roles:user:read

Authorizations:
bearerAuth
path Parameters
organization_id
required
string

クライアントが所属する組織のID。

room_id
required
string

ルームID(ルームURLに含まれるID)。

user_id
required
string

ユーザーID。

Responses

Response samples

Content type
application/json
{
  • "assignment": {
    },
  • "requestId": "string"
}

ユーザーのルームロール割当を変更

roleIdにnullを指定すると直接割当を解除します。ifRoleIdを指定すると、現在のロールが一致する場合だけ変更します。一致しない場合はHTTP 200でstatus: unchanged、reason: role_changed_by_otherを返し、変更しません。

必要なスコープ:room_roles:user:write

Authorizations:
bearerAuth
path Parameters
organization_id
required
string

クライアントが所属する組織のID。

room_id
required
string

ルームID(ルームURLに含まれるID)。

user_id
required
string

ユーザーID。

Request Body schema: application/json
required

変更内容

ifRoleId
integer or null <int64> [ 0 .. 9223372036854776000 ]

現在の直接割当のロールIDがこの値の場合だけ変更する。一致しない場合はHTTP 200でstatus: unchanged、reason: role_changed_by_otherを返し、変更しない。

roleId
required
integer or null <int64> [ 0 .. 9223372036854776000 ]

設定するルームロールID。nullを指定すると直接割当を解除する。

Responses

Request samples

Content type
application/json
{
  • "ifRoleId": 0,
  • "roleId": 0
}

Response samples

Content type
application/json
{
  • "assignment": {
    },
  • "reason": "role_changed_by_other",
  • "requestId": "string",
  • "status": "updated"
}

組織ロール

ユーザーの組織ロールを取得

組織に所属済みのユーザーだけ取得できます。

必要なスコープ:organization_roles:user:read

Authorizations:
bearerAuth
path Parameters
organization_id
required
string

クライアントが所属する組織のID。

user_id
required
string

ユーザーID。

Responses

Response samples

Content type
application/json
{
  • "assignment": {
    },
  • "requestId": "string"
}

ユーザーの組織ロールを変更

roleIdは必須で、nullは指定できません(組織ロールの解除には対応していません)。ifRoleIdを指定すると、現在のロールが一致する場合だけ変更します。一致しない場合はHTTP 200でstatus: unchanged、reason: role_changed_by_otherを返し、変更しません。

必要なスコープ:organization_roles:user:write

Authorizations:
bearerAuth
path Parameters
organization_id
required
string

クライアントが所属する組織のID。

user_id
required
string

ユーザーID。

Request Body schema: application/json
required

変更内容

ifRoleId
integer or null <int64> [ 0 .. 9007199254740991 ]

現在のロールIDがこの値の場合だけ変更する。一致しない場合はHTTP 200でstatus: unchanged、reason: role_changed_by_otherを返し、変更しない。

roleId
required
integer <int64> [ 0 .. 9007199254740991 ]

Responses

Request samples

Content type
application/json
{
  • "ifRoleId": 0,
  • "roleId": 0
}

Response samples

Content type
application/json
{
  • "assignment": {
    },
  • "reason": "role_changed_by_other",
  • "requestId": "string",
  • "status": "updated"
}

グループ

グループ一覧を取得

必要なスコープ:groups:read

Authorizations:
bearerAuth
path Parameters
organization_id
required
string

クライアントが所属する組織のID。

Responses

Response samples

Content type
application/json
{
  • "groups": [
    ],
  • "requestId": "string"
}

グループを作成

組織に同じ名前のグループがすでにある場合は、新しく作成せず、そのグループをHTTP 200、status: existingで返します。

必要なスコープ:groups:write

Authorizations:
bearerAuth
path Parameters
organization_id
required
string

クライアントが所属する組織のID。

Request Body schema: application/json
required

作成するグループ

name
required
string [ 1 .. 128 ] characters

1〜128文字。前後の空白と/を含めない。

Responses

Request samples

Content type
application/json
{
  • "name": "string"
}

Response samples

Content type
application/json
{
  • "group": {
    },
  • "requestId": "string",
  • "status": "created"
}

グループを削除

グループへの所属と、グループに割り当てられたルームロールも削除されます。削除済みのグループを指定すると404を返すため、再送で404を受け取った場合は削除済みとして扱えます。

必要なスコープ:groups:write

Authorizations:
bearerAuth
path Parameters
organization_id
required
string

クライアントが所属する組織のID。

group_id
required
string

グループID。

Responses

Response samples

Content type
application/json
{
  • "group": {
    },
  • "requestId": "string",
  • "status": "deleted"
}

グループ所属

グループのメンバー一覧を取得

必要なスコープ:group_memberships:read

Authorizations:
bearerAuth
path Parameters
organization_id
required
string

クライアントが所属する組織のID。

group_id
required
string

グループID。

Responses

Response samples

Content type
application/json
{
  • "groupId": "string",
  • "members": [
    ],
  • "requestId": "string"
}

グループへの所属を削除

user_idはUUID形式で指定します。

必要なスコープ:group_memberships:write

Authorizations:
bearerAuth
path Parameters
organization_id
required
string

クライアントが所属する組織のID。

group_id
required
string

グループID。

user_id
required
string

ユーザーID。

Responses

Response samples

Content type
application/json
{
  • "membership": {
    },
  • "requestId": "string"
}

グループへの所属を追加

user_idはUUID形式で指定します。まだログインしたことがないユーザーも追加できます。

必要なスコープ:group_memberships:write

Authorizations:
bearerAuth
path Parameters
organization_id
required
string

クライアントが所属する組織のID。

group_id
required
string

グループID。

user_id
required
string

ユーザーID。

Responses

Response samples

Content type
application/json
{
  • "membership": {
    },
  • "requestId": "string"
}

ユーザーの所属グループ一覧を取得

user_idはUUID形式で指定します。

必要なスコープ:group_memberships:read

Authorizations:
bearerAuth
path Parameters
organization_id
required
string

クライアントが所属する組織のID。

user_id
required
string

ユーザーID。

Responses

Response samples

Content type
application/json
{
  • "groups": [
    ],
  • "requestId": "string",
  • "userId": "string"
}