api-gateway-zh

name	api-gateway-zh
description	连接 100+ API（Google Workspace、Microsoft 365、GitHub、Notion、Slack、Airtable、HubSpot 等），支持托管 OAuth 认证。 当用户需要与外部服务交互时使用此技能。 安全说明：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 提供的透传代理，可通过托管 OAuth 连接直接访问第三方 API。API 网关让您可以直接调用原生 API 端点。

快速开始

# 原生 Slack API 调用
python <<'EOF'
import urllib.request, os, json
data = json.dumps({'channel': 'C0123456', 'text': 'Hello from gateway!'}).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="YOUR_API_KEY"

获取 API 密钥

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

连接管理

连接管理使用单独的基础 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",
      "method": "OAUTH2",
      "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

请求体：

• app（必需）- 服务名称（例如 slack、notion）
• method（可选）- 连接方式（API_KEY、BASIC、OAUTH1、OAUTH2、MCP）

获取连接

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

指定连接

如果您对同一应用有多个连接，可以通过添加带有连接 ID 的 Maton-Connection 头来指定使用哪个连接：

python <<'EOF'
import urllib.request, os, json
data = json.dumps({'channel': 'C0123456', 'text': 'Hello!'}).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

如果省略，网关将使用该应用的默认（最早）活动连接。

支持的服务

服务	应用名称	代理的基础 URL
ActiveCampaign	active-campaign	{account}.api-us1.com
Acuity Scheduling	acuity-scheduling	acuityscheduling.com
Airtable	airtable	api.airtable.com
Apollo	apollo	api.apollo.io
Asana	asana	app.asana.com
Attio	attio	api.attio.com
Basecamp	basecamp	3.basecampapi.com
Baserow	baserow	api.baserow.io
beehiiv	beehiiv	api.beehiiv.com
Box	box	api.box.com
Brevo	brevo	api.brevo.com
Calendly	calendly	api.calendly.com
Cal.com	cal-com	api.cal.com
CallRail	callrail	api.callrail.com
Chargebee	chargebee	{subdomain}.chargebee.com
ClickFunnels	clickfunnels	{subdomain}.myclickfunnels.com
ClickSend	clicksend	rest.clicksend.com
ClickUp	clickup

查看 references/ 获取每个提供商的详细路由指南：

• ActiveCampaign - 联系人、交易、标签、列表、自动化、营销活动
• Acuity Scheduling - 预约、日历、客户、可用性
• Airtable - 记录、基地、表格
• Apollo - 人员搜索、数据增强、联系人
• Asana - 任务、项目、工作区、Webhook
• Attio - 人员、公司、记录、任务
• Basecamp - 项目、待办事项、消息、日程、文档
• Baserow - 数据库行、字段、表格、批量操作
• beehiiv - 出版物、订阅、帖子、自定义字段
• Box - 文件、文件夹、协作、共享链接
• Brevo - 联系人、邮件营销、事务性邮件、模板
• Calendly - 事件类型、已安排事件、可用性、Webhook
• Cal.com - 事件类型、预订、日程、可用时段、Webhook
• CallRail - 通话、跟踪器、公司、标签、分析
• Chargebee - 订阅、客户、发票
• ClickFunnels - 联系人、产品、订单、课程、Webhook
• ClickSend - 短信、彩信、语音消息、联系人、列表
• ClickUp - 任务、列表、文件夹、空间、Webhook
• Clockify - 时间跟踪、项目、客户、任务、工作区
• Coda - 文档、页面、表格、行、公式、控件
• Confluence - 页面、空间、博客文章、评论、附件
• CompanyCam - 项目、照片、用户、标签、组、文档
• Cognito Forms - 表单、条目、文档、文件
• Constant Contact - 联系人、邮件营销、列表、细分
• Dropbox - 文件、文件夹、搜索、元数据、版本、标签
• Dropbox Business - 团队成员、组、团队文件夹、设备、审计日志
• ElevenLabs - 文本转语音、语音克隆、音效、音频处理
• Eventbrite - 活动、场地、门票、订单、参与者
• Fathom - 会议录音、转录、摘要、Webhook
• Firebase - 项目、Web应用、Android应用、iOS应用、配置
• Fireflies - 会议转录、摘要、AskFred AI、频道

示例

Slack - 发送消息（原生 API）

# 原生 Slack API: POST https://slack.com/api/chat.postMessage
python <<'EOF'
import urllib.request, os, json
data = json.dumps({'channel': 'C0123456', 'text': 'Hello!'}).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; charset=utf-8')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

HubSpot - 创建联系人（原生 API）

# 原生 HubSpot API: POST https://api.hubapi.com/crm/v3/objects/contacts
python <<'EOF'
import urllib.request, os, json
data = json.dumps({'properties': {'email': '[e-mail]', 'firstname': 'John', 'lastname': 'Doe'}}).encode()
req = urllib.request.Request('https://gateway.maton.ai/hubspot/crm/v3/objects/contacts', 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

Google Sheets - 获取电子表格值（原生 API）

# 原生 Sheets API: GET https://sheets.googleapis.com/v4/spreadsheets/{id}/values/{range}
python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://gateway.maton.ai/google-sheets/v4/spreadsheets/122BS1sFN2RKL8AOUQjkLdubzOwgqzPT64KfZ2rvYI4M/values/Sheet1!A1:B2')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

Salesforce - SOQL 查询（原生 API）

# 原生 Salesforce API: GET https://{instance}.salesforce.com/services/data/v64.0/query?q=...
python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://gateway.maton.ai/salesforce/services/data/v64.0/query?q=SELECT+Id,Name+FROM+Contact+LIMIT+10')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

Airtable - 列出表格（原生 API）

# 原生 Airtable API: GET https://api.airtable.com/v0/meta/bases/{id}/tables
python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://gateway.maton.ai/airtable/v0/meta/bases/appgqan2NzWGP5sBK/tables')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

Notion - 查询数据库（原生 API）

# 原生 Notion API: POST https://api.notion.com/v1/data_sources/{id}/query
python <<'EOF'
import urllib.request, os, json
data = json.dumps({}).encode()
req = urllib.request.Request('https://gateway.maton.ai/notion/v1/data_sources/23702dc5-9a3b-8001-9e1c-000b5af0a980/query', 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('Notion-Version', '2025-09-03')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

Stripe - 列出客户（原生 API）

# 原生 Stripe API: GET https://api.stripe.com/v1/customers
python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://gateway.maton.ai/stripe/v1/customers?limit=10')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

代码示例

JavaScript (Node.js)

const response = await fetch('https://gateway.maton.ai/slack/api/chat.postMessage', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': `Bearer ${process.env.MATON_API_KEY}`
  },
  body: JSON.stringify({ channel: 'C0123456', text: 'Hello!' })
});

Python

import os
import requests

response = requests.post(
    'https://gateway.maton.ai/slack/api/chat.postMessage',
    headers={'Authorization': f'Bearer {os.environ["MATON_API_KEY"]}'},
    json={'channel': 'C0123456', 'text': 'Hello!'}
)

错误处理

状态码	含义
400	缺少请求应用的连接
401	Maton API 密钥无效或缺失
429	限流（每账户每秒 10 个请求）
500	内部服务器错误
4xx/5xx	来自目标 API 的透传错误

来自目标 API 的错误会以其原始状态码和响应体透传。

故障排除：API 密钥问题

1. 检查 MATON_API_KEY 环境变量是否已设置：

echo $MATON_API_KEY

2. 通过列出连接验证 API 密钥是否有效：

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

故障排除：无效的应用名称

1. 验证您的 URL 路径以正确的应用名称开头。路径必须以 /google-mail/ 开头。例如：

• 正确：https://gateway.maton.ai/google-mail/gmail/v1/users/me/messages
• 错误：https://gateway.maton.ai/gmail/v1/users/me/messages

2. 确保您有该应用的活动连接。列出您的连接以验证：

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://ctrl.maton.ai/connections?app=google-mail&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

故障排除：服务器错误

500 错误可能表示 OAuth 令牌已过期。尝试通过上面的连接管理部分创建新连接并完成 OAuth 授权。如果新连接状态为 "ACTIVE"，请删除旧连接以确保网关使用新连接。

速率限制

• 每账户每秒 10 个请求
• 目标 API 的速率限制同样适用

注意事项

• 使用 curl 处理包含括号的 URL（fields[]、sort[]、records[]）时，请使用 -g 标志禁用 glob 解析
• 将 curl 输出管道到 jq 时，环境变量可能在某些 shell 中无法正确展开，这可能导致"Invalid API key"错误

提示

1. 使用原生 API 文档：参考每个服务的官方 API 文档了解端点路径和参数。

2. 请求头会被转发：自定义请求头（除了 Host 和 Authorization）会被转发到目标 API。

3. 查询参数有效：URL 查询参数会被透传到目标 API。

4. 支持所有 HTTP 方法：GET、POST、PUT、PATCH、DELETE 均受支持。

5. QuickBooks 特殊情况：在路径中使用 :realmId，它将被替换为已连接的 realm ID。

可选资源

• Github
• API 参考
• Maton 社区
• Maton 支持