将您的系统接入 Marcomm AI

1. 1
   申请访问权限

   描述您的系统并选择所需数据。我们会逐一审核申请。

2. 2
   创建密钥

   获批后，在“设置 → API”中创建密钥。密钥只显示一次，请将其保存到您的系统中。

3. 3
   发送请求

   在 Authorization 请求头中携带密钥，然后调用下方任一端点。

请求示例

curl https://app.marcomm.works/api/v1/news/digest?days=7 \
  -H "Authorization: Bearer mc_live_..."

每次请求都以 Bearer 令牌的形式发送密钥。个人密钥以创建者本人的身份操作，因此可以以其名义读取并处理审批。工作区密钥由管理员创建，只能读取。密钥可以设置过期时间、限制 IP 地址，也可以轮换：轮换后旧密钥仍可使用 24 小时。

每个密钥只带有您的申请获批的权限范围。

news

新闻摘要、文章和媒体。

crisis

重要新闻和危机事件。

approvals

待审批事项，以及使用个人密钥批准或驳回。

content

读取新闻稿和博客文章。

路径以 /api/v1 开头。读取端点使用 GET 并接受查询参数。响应为 JSON，格式为 {"data": ...}。

向该条目发送 {"decision": "approve"} 或 {"decision": "reject", "comment": "..."}。驳回时必须附上说明。决定遵循与应用和 Slack 相同的规则，并记录在密钥所有者名下。当正文包含需要确认的措辞时，您会收到带有警告的 409 confirmation_required，此时可加上 "force": true 重新发送请求。

curl -X POST https://app.marcomm.works/api/v1/approvals/press-releases/<id> \
  -H "Authorization: Bearer mc_live_..." \
  -H "Content-Type: application/json" \
  -d '{"decision":"reject","comment":"Please fix the headline."}'

限制按工作区设置，分为每分钟和每天（UTC）。响应都会带有下列请求头。超出限制时，您会收到 429 和 Retry-After。如需提高限制，请在“设置 → API”中申请，由我们的团队审核。

X-RateLimit-Limit

每分钟允许的请求数。

X-RateLimit-Remaining

当前分钟内剩余的请求数。

X-RateLimit-Reset

分钟窗口重置时的 Unix 时间。

X-RateLimit-Day-Limit

每天允许的请求数。

X-RateLimit-Day-Remaining

今天剩余的请求数。

Retry-After

重试前需等待的秒数。仅在 429 时返回。

错误以 JSON 返回，格式为 {"error": {"code": ..., "message": ...}}。

警报、审批请求和早间简报也可以推送到您的系统。在“设置 → API → Webhook”中添加接收地址。每个请求都是 JSON，包含字段 event（alert、approval 或 briefing）、workspace、title、text、url、data 和 sentAt。审批请求带有 data.kind（press_release、blog 或 event）和 data.id，可据此通过 API 读取并处理。

每个请求都带有签名。使用您的签名密钥对原始请求体计算 HMAC-SHA256，并与格式为 sha256=<hex> 的 X-Marcomm-Signature 请求头比对。不匹配的请求应予拒绝。

在 Node.js 中验证 Webhook

import { createHmac, timingSafeEqual } from 'node:crypto';

export function isFromMarcomm(rawBody: string, signature: string, secret: string) {
  const expected = 'sha256=' + createHmac('sha256', secret).update(rawBody).digest('hex');
  const a = Buffer.from(expected);
  const b = Buffer.from(signature);
  return a.length === b.length && timingSafeEqual(a, b);
}