clarify-api

Clarify API

Note: Clarify API は現在開発中であり、破壊的変更が行われる可能性があります。ご質問がある場合は [email protected] までお問い合わせください。

ルート URL

https://api.clarify.ai/v1/workspaces/{slug}/*

slug は、顧客の組織に割り当てられたワークスペース ID です。ログイン時の URL で確認するか、アプリケーション内でアバターをクリックして確認できます。

認証

API キー認証

1. ワークスペースの設定から新しい API キーを生成します。生成されたキーには、ワークスペースに対する管理者レベルの権限が付与されます。

   • ワークスペース内のレコードにアクセスでき、データの読み取り、書き込み、削除が可能です
   • アクセスできるのは、マスキングされたメールのメタデータのみです。本文などの機密フィールドにはアクセスできません
   • 会議データの閲覧権限は、他のユーザーと同じです

2. api-key スキームを使用して、この API キーを Authorization ヘッダーに含めます。

curl --header "Authorization: api-key $APIKEY" \
  https://api.clarify.ai/v1/workspaces/$WORKSPACE_SLUG/schemas

パートナー OAuth 2.0 認証

Clarify は OAuth を使用し、認可コード、PKCE を使用した認可コード、およびリフレッシュトークンのグラントをサポートしています。

OAuth エンドポイント：

• 認可：https://auth1.clarify.ai/oauth2/authorize
• トークン：https://auth1.clarify.ai/oauth2/token
• リフレッシュトークン：https://auth1.clarify.ai/oauth2/token
• スコープ：openid profile email offline_access

OAuth フロー：

1. 認可コードを取得します。

GET https://auth1.clarify.ai/oauth2/authorize?response_type=code&client_id={your_client_id}&scope=openid%20profile%20email%20offline_access&redirect_uri={your_redirect_url}

2. トークンと交換します。

POST https://auth1.clarify.ai/oauth2/token
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code
code={your-code}
redirect_uri={your_redirect_uri}
client_id={your_client_id}
client_secret={your_client_secret}

3. API 呼び出しでアクセストークンを使用します。

Authorization: Bearer {access-token}

API 構成

API は JSON:API 仕様に準拠しています。

ページネーション

レスポンスの最大サイズは 1000 件です。

リクエスト：

• page[limit]={number} — 返す項目の最大数

レスポンスフィールド：

• data — 返された項目の配列
• meta — ページネーションのメタデータ：total_records、total_pages、offset、limit
• links — URL 参照：prev（利用可能な場合）、next（利用可能な場合）

並べ替え

sortOrder クエリパラメーターでレコードの順序を制御します。

• sortOrder[column] — 並べ替えの基準となるフィールド名
• sortOrder[dir] — 方向：ASC または DESC

フィルタリング

filter クエリパラメーターでレコードをフィルタリングします。条件は常に AND で結合されます（OR はサポートされていません）。

基本構文：

filter[{field_name}]={field_value}

演算子を使用した高度な構文：

filter[{field_name}][{operator}]={field_value}

フィールドタイプごとのサポート演算子：

フィールドタイプ	演算子
テキスト、複数行テキスト	Is、Is not、Contains、Does not contain、Starts with、Ends with
数値、通貨	Is、Greater than、Less than、Greater than or equal、Less than or equal
日付	Is、Is after、Is before、Is on or after、Is on or before
単一選択	Is、Is not、One of、Not one of
複数選択	Contains、Does not contain
チェックボックス	Is、Is not
位置情報	Contains、Does not contain
レコード ID	Is、Is not
コレクション（メール、ドメイン）	Contains、Does not contain

エンドポイント

オブジェクトとスキーマの取得

GET /schemas

スキーマ JSON の配列を返します。

• core/* — 他のスキーマから参照される内部スキーマ
• entities/* — 利用可能なオブジェクト：会社、取引、会議、会議録画、人物、タスク、ユーザー

各エンティティには、attributes フィールドに JSON Schema 定義があります。

レコードの取得

GET /objects/{object}/resources

パラメーター：

• sortOrder — 並べ替えるフィールドと、任意の方向
• filters — レコードをフィルタリングする 1 つ以上の条件
• include — 含める関連フィールドをコンマ区切りで指定したリスト

レコードの作成

POST /objects/{object}/records

リクエストボディ：

{
  "data": {
    "type": "{object}",
    "attributes": {
      "{field-name}": "{field-value}"
    }
  }
}

アップサート動作に使用する一意のフィールド：

オブジェクト	一意のフィールド
人物	email_addresses（いずれか 1 つ）
会社	domains（いずれか 1 つ）
取引	name
会議	該当なし
会議録画	該当なし
ユーザー	該当なし

レコードの取得

GET /objects/{object}/records/{id}

パラメーター：

• include — 含める関連フィールドをコンマ区切りで指定したリスト

レコードの更新

PATCH /objects/{object}/records/{id}

リクエストボディ：

{
  "data": {
    "id": "{id}",
    "type": "{object}",
    "attributes": {
      "{field-name}": "{field-value}"
    }
  }
}

レコードの一括アップサート

POST /objects/{object}/records/bulk

リクエストボディ：

{
  "data": [{
    "type": "{entity}",
    "attributes": {
      "{field-name}": "{field-value}"
    }
  }]
}

レコードの一括削除

現在、レコードを一括削除する方法はありません。

Set Relationship

PATCH /objects/{object}/records/{id}/relationships/{field-name}

Request body:

{
  "data": [
    {
      "id": "{id-of-record-to-associate}",
      "type": "{object}"
    }
  ]
}

Unset Relationship

DELETE /objects/{object}/records/{id}/relationships/{field-name}

Request body:

{
  "data": [
    {
      "id": "{id-of-record-to-disassociate}",
      "type": "{object}"
    }
  ]
}

Get Recording Artifacts

POST /meetings/{id}/recordings/{id}/artifacts

Response:

{
  "data": {
    "videoUrl": "{signed-video-url}",
    "transcriptionUrl": "{signed-transcription-url}"
  }
}

Swagger Documentation

Full API documentation: https://api.clarify.ai/swagger