CloudX API

了解如何认证请求并使用 CloudX API 参考。

CloudX API

使用 CloudX API 获取报表指标、检查竞价、管理任务，并读取或写入账号配置。

基础 URL

https://provisioning.cloudx.io/api/v1

认证

在 Settings > API Keys 中创建 API key，然后将它作为 bearer token 发送：

curl https://provisioning.cloudx.io/api/v1/auth/status \
  -H "Authorization: Bearer $CLOUDX_API_KEY"

只有管理员可以创建、管理和撤销 API key。

权限

根据集成需要调用的端点选择权限。

权限	允许访问
`reports:read`	`/report/` 下的报表端点和 `/export/` 下的活动导出端点
`auctions:read`	`/auction/*` 下的竞价检查端点
`configuration:read`	`/config/*` 下的配置端点和任务读取端点
`configuration:write`	`/config/*` 下的配置写入端点和任务写入端点

活动导出

通过 POST /export/impressions、POST /export/requests 或 POST /export/bids 创建异步的全天活动导出报表，然后轮询对应的 GET 端点，直到导出就绪。

大多数报表会在 5–45 分钟内准备好供下载。处理时间取决于所选日期和过滤条件对应的数据量。导出就绪后，状态响应会包含一个短期有效的下载 URL。

请参阅活动导出，了解 API 和 CLI 共用的请求正文、轮询示例和 CSV 架构。

配置写入

使用 POST /config/edit 为应用、广告单元、广告单元组、列表、标签、测试设备、网络映射和订单项创建或更新配置草稿。该端点也支持 A/B 测试操作；创建 A/B 测试会返回草稿，更新、开始、结束、提升和删除会发布生成的配置。

请求使用带类型的操作键，例如 create_app、update_ad_unit、upsert_network_mapping 和 update_line_item。广告单元和订单项的 bidfloor 使用十进制 USD CPM，因此 1.5 表示 $1.50 CPM。

任务

使用 /scheduled-agents 端点管理定期运行的 CloudX 分析。为保持兼容性，API 端点路径使用 scheduled-agents，产品和 CLI 中则称为任务。

使用提示词和五字段 cron 计划创建任务：

curl https://provisioning.cloudx.io/api/v1/scheduled-agents \
  -X POST \
  -H "Authorization: Bearer $CLOUDX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "每周收入回顾",
    "prompt": "检查每周收入并标记重大变化",
    "schedule": "0 9 * * 1",
    "timezone": "Asia/Shanghai",
    "access_mode": "workspace"
  }'

任务端点支持完整生命周期：

方法	端点	操作
`GET`	`/scheduled-agents`	列出任务。
`POST`	`/scheduled-agents`	创建任务。
`GET`	`/scheduled-agents/{scheduled_agent_id}`	获取一个任务。
`PATCH`	`/scheduled-agents/{scheduled_agent_id}`	更新一个或多个字段。
`DELETE`	`/scheduled-agents/{scheduled_agent_id}`	删除任务。
`POST`	`/scheduled-agents/{scheduled_agent_id}/run`	立即将已启用的任务加入队列。

读取操作需要 configuration:read 权限；变更操作需要 configuration:write 权限。使用用户身份认证进行变更时，还需要编辑者权限。账号必须已启用 Tasks 功能。

将 access_mode 设置为 private 或 workspace。私有任务必须有最终用户创建者，并且仅对该用户可见。使用 API key 创建的任务没有最终用户创建者，对整个工作区可见，且不能更改为私有任务。

任务响应包含 cron 表达式、IANA 时区、可读计划、启用状态、访问模式、可选的创建者用户 ID、下次运行时间、时间戳和创建来源。

API 参考

API 参考由 CloudX 托管的实时 OpenAPI schema 生成。