API网关

提供直通式代理，通过托管的OAuth连接直接访问第三方API，由Maton提供。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、待处理,失败)

响应：

{
  "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

请求体：

• 应用（必需）- 服务名称（例如：slack,notion）
• 方法（可选）- 连接方法（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

指定连接

如果您为同一个应用有多个连接，可以通过添加

Maton-Connection请求头并附带连接ID来指定使用哪个连接：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- 记录、数据库、表格
• Apollo- 人员搜索、信息丰富化、联系人
• Asana- 任务、项目、工作空间、网络钩子
• 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、频道
• GetResponse- 营销活动、联系人、新闻简报、自动回复器、标签、细分
• Grafana- 仪表板、数据源、文件夹、注释、警报、团队
• GitHub- 仓库、议题、拉取请求、提交
• Gumroad- 产品、销售、订阅者、许可证、Webhooks
• Granola MCP- 基于MCP的会议笔记、转录、查询界面
• Google Ads- 营销活动、广告组、GAQL查询
• Google Analytics Admin- 报告、维度、指标
• Google Analytics Data- 报告、维度、指标
• Google BigQuery- 数据集、表、作业、SQL查询
• Google Calendar- 事件、日历、忙/闲状态
• Google Classroom- 课程、课堂作业、学生、教师、公告
• Google Contacts- 联系人、联系人组、人员搜索
• Google 文档- 文档创建、批量更新
• Google 云端硬盘- 文件、文件夹、权限
• Google 表单- 表单、问题、回复
• Gmail- 邮件、会话、标签
• Google Meet- 空间、会议记录、参与者
• Google Merchant- 产品、库存、促销活动、报告
• Google Play- 应用内产品、订阅、评价
• Google Search Console- 搜索分析、站点地图
• Google 表格- 数值、范围、格式设置
• Google 幻灯片- 演示文稿、幻灯片、格式设置
• Google 任务- 任务列表、任务、子任务
• Google Workspace 管理- 用户、群组、组织单元、域名、角色
• HubSpot- 联系人、公司、交易
• Instantly- 营销活动、销售线索、客户账户、邮件推广
• Jira- 问题、项目、JQL查询
• Jobber- 客户、任务、发票、报价单 (GraphQL)
• JotForm- 表单、提交记录、网络钩子
• Kaggle- 数据集、模型、竞赛、内核
• Keap- 联系人、公司、标签、任务、商机、营销活动
• Kibana- 已保存对象、仪表板、数据视图、空间、警报、Fleet
• Kit- 订阅者、标签、表单、序列、广播
• Klaviyo- 用户画像、列表、营销活动、流程、事件
• Lemlist- 营销活动、销售线索、活动记录、日程安排、退订记录
• Linear- 问题、项目、团队、周期 (GraphQL)
• LinkedIn- 个人资料、帖子、分享内容、媒体上传
• Mailchimp- 受众群体、营销活动、模板、自动化流程
• MailerLite- 订阅者、分组、营销活动、自动化流程、表单
• Mailgun- 邮件发送、域名、路由、模板、邮件列表、退订管理
• ManyChat- 订阅者、标签、流程、消息
• Manus- AI 代理任务、项目、文件、Webhooks
• 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- 邮件发送、联系人、模板、抑制列表、统计
• 哨兵- 问题、事件、项目、团队、发布
• SharePoint- 站点、列表、文档库、文件、文件夹、版本
• Slack- 消息、频道、用户
• Snapchat- 广告账户、广告系列、广告小组、广告、创意、受众
• Square- 支付、客户、订单、目录、库存、发票
• Squarespace- 产品、库存、订单、个人资料、交易
• Sunsama MCP- 基于MCP的任务、日历、待办事项、目标、时间追踪界面
• Stripe- 客户、订阅、支付
• Systeme.io- 联系人、标签、课程、社区、Webhooks
• Tally- 表单、提交、工作区、Webhooks
• Tavily- AI网络搜索、内容提取、爬虫、研究任务
• Telegram- 消息、聊天、机器人、更新、投票
• TickTick- 任务、项目、任务列表
• Todoist- 任务、项目、分区、标签、评论
• Toggl Track- 时间记录、项目、客户、标签、工作空间
• Trello- 看板、列表、卡片、检查清单
• Twilio- 短信、语音通话、电话号码、消息传递
• Twenty CRM- 公司、人员、商机、备注、任务
• Typeform- 表单、回复、洞察报告
• Unbounce- 落地页、潜在客户、账户、子账户、域名
• 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 的错误会以其原始状态码和响应体直接透传。

故障排除：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授权。如果新连接显示为"活跃"状态，请删除旧连接以确保网关使用新连接。

速率限制

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

注意事项

• 当使用curl处理包含方括号的URL时（fields[]、sort[]、records[]），请使用-g参数来禁用通配符解析
• 当通过管道将curl输出传递给jq时，某些shell中环境变量可能无法正确展开，这可能导致"无效API密钥"错误

使用技巧

1. 查阅原生API文档：请参考各服务的官方API文档以获取端点路径和参数信息。

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

3. 查询参数运作方式：URL查询参数会透传至目标API。

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

5. QuickBooks特殊情况：在路径中使用:realmId时，该占位符将替换为已连接的领域ID。

可选

• Github
• API参考文档
• Maton社区
• Maton技术支持