📦 API Gateway — 百款API一站调用

---
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 Gateway

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

快速开始

# Native Slack API call
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

Base 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 密钥

• 登录或创建账户 maton.ai
• 转到 maton.ai/settings
• 点击 API Key 区域右侧的复制按钮进行复制

连接管理

连接管理使用单独的 base 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

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

请参阅 references/ 获取每个提供商的详细路由指南：

• ActiveCampaign - 联系人、交易、标签、列表、自动化、营销活动
• Acuity Scheduling - 预约、日历、客户、可用性
• Airtable - 记录、基础表、表格
• Apify - Actors、运行、数据集、键值存储、请求队列、定时任务
• Apollo - 人员搜索、数据丰富、联系人
• Asana - 任务、项目、工作区、Webhooks
• Attio - 人员、公司、记录、任务
• Basecamp - 项目、待办事项、消息、日程安排、文档
• Baserow - 数据库行、字段、表格、批量操作
• beehiiv - 出版物、订阅、帖子、自定义字段
• Box - 文件、文件夹、协作、共享链接
• Brevo - 联系人、电子邮件营销、交易邮件、模板
• Brave Search - 网页搜索、图片搜索、新闻搜索、视频搜索
• Buffer - 社交媒体帖子、频道、组织、定时发布
• Calendly - 事件类型、预定事件、可用性、Webhooks
• Cal.com - 事件类型、预订、日程安排、可用时段、Webhooks
• CallRail - 电话、追踪器、公司、标签、分析
• Chargebee - 订阅、客户、发票
• ClickFunnels - 联系人、产品、订单、课程、Webhooks
• ClickSend - 短信、多媒体消息、语音消息、联系人、列表
• ClickUp - 任务、列表、文件夹、空间、Webhooks
• Clockify - 时间追踪、项目、客户、任务、工作区
• Coda - 文档、页面、表格、行、公式、控件
• Confluence - 页面、空间、博客文章、评论、附件
• CompanyCam - 项目、照片、用户、标签、群组、文档
• Cognito Forms - 表单、条目、文档、文件
• Constant Contact - 联系人、电子邮件营销、列表、细分
• Dropbox - 文件、文件夹、搜索、元数据、版本历史、标签

• Dropbox Business - 团队成员、群组、团队文件夹、设备、审计日志
• ElevenLabs - 文本转语音、语音克隆、音效、音频处理
• Eventbrite - 活动、场馆、门票、订单、参会者
• Exa - 神经网页搜索、内容提取、相似页面、AI 答案、研究任务
• fal.ai - AI 模型推理（图像生成、视频、音频、放大）
• Fathom - 会议录音、转录、摘要、webhooks
• Firecrawl - 网页抓取、爬取、站点地图、网页搜索
• Firebase - 项目、Web 应用、Android 应用、iOS 应用、配置
• Fireflies - 会议转录、摘要、AskFred AI、频道
• Front - 对话、消息、联系人、标签、收件箱、团队成员
• GetResponse - 营销活动、联系人、新闻通讯、自动回复器、标签、细分
• Grafana - 仪表板、数据源、文件夹、注释、告警、团队
• GitHub - 仓库、问题、pull requests、提交
• Gumroad - 产品、销售、订阅者、许可证、webhooks
• Granola MCP - 基于 MCP 的会议笔记、转录、查询界面
• Google Ads - 营销活动、广告组、GAQL 查询
• Google Analytics Admin - 报告、维度、指标
• Google Analytics Data - 报告、维度、指标
• Google BigQuery - 数据集、表、作业、SQL 查询
• Google Calendar - 事件、日历、忙闲状态
• Google Classroom - 课程、作业、学生、教师、公告
• Google Contacts - 联系人、联系人组、人员搜索
• Google Docs - 文档创建、批量更新
• Google Drive - 文件、文件夹、权限
• Google Forms - 表单、问题、响应
• Gmail - 消息、线程、标签
• Google Meet - 空间、会议记录、参与者
• Google Merchant - 产品、库存、促销、报告
• Google Play - 应用内产品、订阅、评论
• Google Search Console - 搜索分析、站点地图
• Google Sheets - 值、范围、格式
• Google Slides - 演示文稿、幻灯片、格式
• Google Tasks - 任务列表、任务、子任务
• Google Workspace Admin - 用户、群组、组织单位、域、角色
• HubSpot - 联系人、公司、交易
• Instantly - 营销活动、潜在客户、账户、电子邮件推广
• Jira - 问题、项目、JQL 查询
• Jobber - 客户、工作、发票、报价 (GraphQL)
• JotForm - 表单、提交、webhooks
• Kaggle - 数据集、模型、竞赛、内核
• Keap - 联系人、公司、标签、任务、机会、营销活动
• Kibana - 保存的对象、仪表板、数据视图、空间、告警、fleet
• Kit - 订阅者、标签、表单、序列、广播
• Klaviyo - 档案、列表、营销活动、流程、事件
• Lemlist - 营销活动、潜在客户、活动、日程、取消订阅
• Linear - 问题、项目、团队、周期 (GraphQL)
• LinkedIn - 个人资料、帖子、分享、媒体上传
• Mailchimp - 受众、营销活动、模板、自动化
• MailerLite - 订阅者、群组、营销活动、自动化、表单
• Mailgun - 邮件发送、域、路由、模板、邮件列表、抑制
• Make - 场景、组织、团队、连接、数据存储、hooks
• ManyChat - 订阅者、标签、流程、消息
• Manus - AI 代理任务、项目、文件、webhooks
• Memelord - AI 表情包生成、视频表情包、模板编辑
• Microsoft Excel - 工作簿、工作表、范围、表格、图表
• Microsoft Teams - 团队、频道、消息、成员、聊天
• Microsoft To Do - 任务列表、任务、检查项、链接资源
• Monday.com - 看板、项、列、群组 (GraphQL)
• Motion - 任务、项目、工作区、日程
• Netlify - 站点、部署、构建、DNS、环境变量
• Notion - 页面、数据库、块
• Notion MCP - 基于 MCP 的页面、数据库、评论、团队、用户界面
• OneNote - 笔记本、分区、分区组、页面（通过 Microsoft Graph）
• OneDrive - 文件、文件夹、驱动器、共享
• Outlook - 邮件、日历、联系人
• PDF.co - PDF 转换、合并、分割、编辑、文本提取、条形码
• Pipedrive - 交易、人员、组织、活动
• Podio - 组织、工作区、应用、项、任务、评论
• PostHog - 产品分析、功能标志、会话录制、实验、HogQL 查询
• QuickBooks - 客户、发票、报告
• Quo - 通话、消息、联系人、对话、webhooks
• Reducto - 文档解析、提取、分割、编辑
• Resend - 事务性邮件、域、受众、联系人、广播、webhooks
• Salesforce - SOQL、sObjects、CRUD
• SignNow - 文档、模板、邀请、电子签名
• SendGrid - 邮件发送、联系人、模板、抑制、统计
• Sentry - 问题、事件、项目、团队、版本
• SharePoint - 站点、列表、文档库、文件、文件夹、版本
• Slack - 消息、频道、用户
• Snapchat - 广告账户、营销活动、广告组、广告、创意、受众
• Square - 支付、客户、订单、目录、库存、发票
• Squarespace - 产品、库存、订单、资料、交易
• Stripe - 客户、订阅、支付
• Sunsama MCP - 基于 MCP 的任务、日历、积压、目标、时间追踪界面
• Supabase - 数据库表、认证用户、存储桶
• Systeme.io - 联系人、标签、课程、社区、webhooks
• Tally - 表单、提交、工作区、webhooks
• Tavily - AI 网页搜索、内容提取、爬取、研究任务
• Telegram - 消息、聊天、机器人、更新、投票
• TickTick - 任务、项目、任务列表
• Todoist - 任务、项目、 section、标签、评论
• Toggl Track - 时间条目、项目、客户、标签、工作区
• Trello - 看板、列表、卡片、检查清单
• Twilio - 短信、语音通话、电话号码、消息
• Twenty CRM - 公司、人员、机会、笔记、任务
• Typeform - 表单、响应、洞察
• Unbounce - 落地页、潜在客户、账户、子账户、域
• Vercel - 项目、部署、域、环境变量
• Vimeo - 视频、文件夹、专辑、评论、点赞
• WATI - WhatsApp 消息、联系人、模板、交互式消息
• WhatsApp Business - 消息、模板、媒体
• WooCommerce - 产品、订单、客户、优惠券
• WordPress.com - 文章、页面、站点、用户、设置
• Wrike - 任务、文件夹、项目、空间、评论、时间日志、工作流
• Xero - 联系人、发票、报告
• YouTube - 视频、播放列表、频道、订阅
• Zoho Bigin - 联系人、公司、管道、产品

• Zoho Bookings - 预约、服务、员工、工作区
• Zoho Books - 发票、联系人、账单、费用
• Zoho Calendar - 日历、事件、参与者、提醒
• Zoho CRM - 潜在客户、联系人、账户、交易、搜索
• Zoho Inventory - 物料、销售订单、发票、采购订单、账单
• Zoho Mail - 消息、文件夹、标签、附件
• Zoho People - 员工、部门、职位、考勤、请假
• Zoho Projects - 项目、任务、里程碑、任务列表、评论
• Zoho Recruit - 候选人、职位空缺、面试、申请

示例

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': 'john@example.com', '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!'}
)

错误处理

故障排除：API 密钥问题

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

echo $MATON_API_KEY

• 通过列出连接来验证 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

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

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

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

• 确保你有一个该应用的活跃连接。列出你的连接以验证：

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 中使用包含方括号（fields[]、sort[]、records[]）的 URL 时，使用 -g 标志禁用 glob 解析
• 当将 curl 输出通过管道传输到 jq 时，在某些 shell 中环境变量可能无法正确展开，这可能导致"无效 API 密钥"错误
• 媒体上传 URL（LinkedIn 等）： 某些 API 返回的预签名上传 URL 指向与网关代理不同的主机（例如，LinkedIn 返回 www.linkedin.com 上传 URL，但网关代理 api.linkedin.com）。这些上传 URL 是预签名的，不需要 Authorization 标头 — 直接将二进制文件上传到返回的 URL，无需通过网关。对于这些上传必须使用 Python urllib，因为 URL 包含编码字符（例如 %253D），通过 shell 变量或 curl 传递时会损坏。始终使用 json.load() 解析 JSON 响应，并在 Python 中直接使用 URL。

技巧

• 使用原生 API 文档：请参考每个服务的官方 API 文档以了解端点路径和参数。
• 标头会被转发：自定义标头（Host 和 Authorization 除外）会被转发到目标 API。
• 查询参数有效：URL 查询参数会被传递到目标 API。
• 支持所有 HTTP 方法：GET、POST、PUT、PATCH、DELETE 都支持。
• QuickBooks 特殊情况：在路径中使用 :realmId，它将被替换为连接的 realm ID。

可选

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