clarify-api

Clarify API

**注意：**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/* — 可用对象：company、deal、meeting、meeting_recording、person、task、user

每个实体都在 attributes 字段中包含其 JSON Schema 定义。

获取记录

GET /objects/{object}/resources

参数：

• sortOrder — 用于排序的字段，可选指定方向
• filters — 一个或多个记录筛选条件
• include — 要包含的关联字段，以逗号分隔的列表

创建记录

POST /objects/{object}/records

请求正文：

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

用于更新或插入行为的唯一字段：

对象	唯一字段
Person	email_addresses（任意一个）
Company	domains（任意一个）
Deal	name
Meeting	不适用
Meeting Recording	不适用
User	不适用

获取记录

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