name: api-gateway
description: |
通过托管的 OAuth 连接，接入 100 多个 API（Google Workspace、Microsoft 365、GitHub、Notion、Slack、Airtable、HubSpot 等）。
当用户需要与外部服务交互时，请使用此技能。
安全性：MATON_API_KEY 用于向 Maton.ai 进行身份验证，但其本身不授予对第三方服务的访问权限。每个服务都需要用户通过 Maton 的连接流程明确进行 OAuth 授权。访问权限严格限定在用户已授权的连接范围内。由 Maton (https://maton.ai) 提供。
compatibility: 需要网络访问权限和有效的 Maton API 密钥
metadata:
author: maton
version: "1.0"
clawdbot:
emoji: 🧠
homepage: "https://maton.ai"
requires:
env:
- MATON_API_KEY

API 网关

由 Maton 提供的直连第三方 API 的透传代理，使用托管的 OAuth 连接。API 网关允许您直接调用原生 API 端点。

快速开始

# 原生 Slack API 调用示例
python <<'EOF'
import urllib.request, os, json
data = json.dumps({'channel': 'C0123456', 'text': '来自网关的问候！'}).encode()
req = urllib.request.Request('https://gateway.maton.ai/slack/api/chat.postMessage', data=data, method='POST')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
req.add_header('Content-Type', 'application/json')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

基础 URL

https://gateway.maton.ai/{app}/{native-api-path}

将 {app} 替换为服务名称，将 {native-api-path} 替换为实际的 API 端点路径。

重要提示：URL 路径必须以连接的应用名称开头（例如 /google-mail/...）。此前缀告知网关使用哪个应用连接。例如，原生 Gmail API 路径以 gmail/v1/ 开头，因此完整路径应类似 /google-mail/gmail/v1/users/me/messages。

身份验证

所有请求都需要在 Authorization 请求头中包含 Maton API 密钥：

Authorization: Bearer $MATON_API_KEY

API 网关会自动为目标服务注入相应的 OAuth 令牌。

环境变量：您可以将 API 密钥设置为 MATON_API_KEY 环境变量：

export MATON_API_KEY="您的_API_密钥"

获取您的 API 密钥

1. 登录或在 maton.ai 创建账户。
2. 前往 maton.ai/settings。
3. 点击 API 密钥部分右侧的复制按钮进行复制。

连接管理

连接管理使用独立的基础 URL：https://ctrl.maton.ai

列出连接

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://ctrl.maton.ai/connections?app=slack&status=ACTIVE')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

查询参数（可选）：
- app - 按服务名称过滤（例如 slack、hubspot、salesforce）
- status - 按连接状态过滤（ACTIVE、PENDING、FAILED）

响应示例：

{
  "connections": [
    {
      "connection_id": "21fd90f9-5935-43cd-b6c8-bde9d915ca80",
      "status": "ACTIVE",
      "creation_time": "2025-12-08T07:20:53.488460Z",
      "last_updated_time": "2026-01-31T20:03:32.593153Z",
      "url": "https://connect.maton.ai/?session_token=5e9...",
      "app": "slack",
      "metadata": {}
    }
  ]
}

创建连接

python <<'EOF'
import urllib.request, os, json
data = json.dumps({'app': 'slack'}).encode()
req = urllib.request.Request('https://ctrl.maton.ai/connections', data=data, method='POST')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
req.add_header('Content-Type', 'application/json')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

获取连接详情

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://ctrl.maton.ai/connections/{connection_id}')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

响应示例：

{
  "connection": {
    "connection_id": "21fd90f9-5935-43cd-b6c8-bde9d915ca80",
    "status": "ACTIVE",
    "creation_time": "2025-12-08T07:20:53.488460Z",
    "last_updated_time": "2026-01-31T20:03:32.593153Z",
    "url": "https://connect.maton.ai/?session_token=5e9...",
    "app": "slack",
    "metadata": {}
  }
}

在浏览器中打开返回的 URL 以完成 OAuth 授权。

删除连接

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://ctrl.maton.ai/connections/{connection_id}', method='DELETE')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

指定连接

如果您为同一应用配置了多个连接，可以通过添加 Maton-Connection 请求头并附带连接 ID 来指定使用哪个连接：

python <<'EOF'
import urllib.request, os, json
data = json.dumps({'channel': 'C0123456', 'text': '你好！'}).encode()
req = urllib.request.Request('https://gateway.maton.ai/slack/api/chat.postMessage', data=data, method='POST')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
req.add_header('Content-Type', 'application/json')
req.add_header('Maton-Connection', '21fd90f9-5935-43cd-b6c8-bde9d915ca80')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

如果省略此请求头，网关将使用该应用的默认（最早创建的）活跃连接。

支持的服务

查看 references/ 目录获取每个提供商的详细路由指南：
- ActiveCampaign - 联系人、交易、标签、列表、自动化、营销活动
- Acuity Scheduling - 预约、日历、客户、可用性
- Airtable - 记录、数据库、表格
- Apollo - 人员搜索、信息丰富、联系人
- Asana - 任务、项目、工作区、Webhook
- Attio - 人员、公司、记录、任务
- Basecamp - 项目、待办事项、消息、日程、文档
- beehiiv - 出版物、订阅、帖子、自定义字段
- Box - 文件、文件夹、协作、共享链接
- Brevo - 联系人、邮件营销活动、事务性邮件、模板
- Calendly - 事件类型、已安排事件、可用性、Webhook
- Cal.com - 事件类型、预订、日程、可用时间段、Webhook
- CallRail - 通话、追踪器、公司、标签、分析
- Chargebee - 订阅、客户、发票
- ClickFunnels - 联系人、产品、订单、课程、Webhook
- [ClickSend](