API Gateway
by @byungkyu
Connect to external services through Maton-managed API routes. Use this skill only after the user names the target app, account, and task. Start with read/li...
clawhub install api-gatewayπ About This Skill
name: api-gateway description: | Connect to external services through Maton-managed API routes. Use this skill only after the user names the target app, account, and task. Start with read/list calls when possible and follow the app-specific reference before any change. compatibility: Requires network access and Maton account setup metadata: author: maton version: "1.0" clawdbot: emoji: π§ homepage: "https://maton.ai"
API Gateway
Managed API routing for third-party services, provided by Maton. Use this only for a user-requested app, account, and task.
Quick Start
# List Slack channels (read-only)
python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://api.maton.ai/slack/api/conversations.list?types=public_channel&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
Routing
Use https://api.maton.ai/ with the app-prefixed routes documented in the examples below or in the matching reference file.
Read-only route examples:
https://api.maton.ai/slack/api/conversations.list?types=public_channel&limit=10
https://api.maton.ai/google-mail/gmail/v1/users/me/messages
The first path segment is the app identifier listed in Supported Services. For Gmail, use /google-mail/gmail/v1/users/me/messages.
Authentication
Use MATON_API_KEY from the environment when constructing the request's Authorization header, as shown in the examples. Never print or copy the key.
IMPORTANT: Treat MATON_API_KEY as a secret. Do not log it, paste it into prompts, or expose it in shared files or command output. Authorize only the services and scopes needed for the current task, revoke unused connections, and rotate the key if exposed.
Environment Variable: You can set your API key as the MATON_API_KEY environment variable:
export MATON_API_KEY="YOUR_API_KEY"
Getting Your API Key
1. Sign in or create an account at maton.ai 2. Go to maton.ai/settings 3. Click the copy button on the right side of API Key section to copy it
Connection Management
Connection management uses a separate base URL: https://api.maton.ai
List Connections
python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://api.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
Query Parameters (optional):
app - Filter by service name (e.g., slack, hubspot, salesforce)status - Filter by connection status (ACTIVE, PENDING, FAILED)Response:
{
"connections": [
{
"connection_id": "{connection_id}",
"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": {}
}
]
}
Create Connection
python <<'EOF'
import urllib.request, os, json
data = json.dumps({'app': 'slack'}).encode()
req = urllib.request.Request('https://api.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
Request Body:
app (required) - Service name (e.g., slack, notion)method (optional) - Connection method (API_KEY, BASIC, OAUTH1, OAUTH2, MCP)Get Connection
python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://api.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
Response:
{
"connection": {
"connection_id": "{connection_id}",
"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": {}
}
}
Open the returned URL in a browser to complete service authorization.
Delete Connection
python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://api.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
Specifying Connection
If you have multiple connections for the same app, you can specify which connection to use by adding the Maton-Connection header with the connection ID:
python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://api.maton.ai/slack/api/conversations.list?types=public_channel&limit=10')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
req.add_header('Maton-Connection', '{connection_id}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF
If you have multiple connections, always include this header to ensure requests go to the intended account.
Security & Permissions
Maton-Connection header to ensure requests go to the intended account, especially when the user has multiple connections for the same service.Supported Services
| Service | App Name | Service API Host |
|---------|----------|------------------|
| ActiveCampaign | active-campaign | {account}.api-us1.com |
| Acuity Scheduling | acuity-scheduling | acuityscheduling.com |
| Airtable | airtable | api.airtable.com |
| Apify | apify | api.apify.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 |
| Brave Search | brave-search | api.search.brave.com |
| Buffer | buffer | api.buffer.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 | api.clickup.com |
| Clio | clio | app.clio.com |
| Clockify | clockify | api.clockify.me |
| Coda | coda | coda.io |
| Confluence | confluence | api.atlassian.com |
| CompanyCam | companycam | api.companycam.com |
| Cognito Forms | cognito-forms | www.cognitoforms.com |
| Constant Contact | constant-contact | api.cc.email |
| Dropbox | dropbox | api.dropboxapi.com |
| Dropbox Business | dropbox-business | api.dropboxapi.com |
| ElevenLabs | elevenlabs | api.elevenlabs.io |
| Eventbrite | eventbrite | www.eventbriteapi.com |
| Exa | exa | api.exa.ai |
| Facebook Page | facebook-page | graph.facebook.com |
| fal.ai | fal-ai | queue.fal.run |
| Fathom | fathom | api.fathom.ai |
| Firecrawl | firecrawl | api.firecrawl.dev |
| Firebase | firebase | firebase.googleapis.com |
| Fireflies | fireflies | api.fireflies.ai |
| Front | front | api2.frontapp.com |
| GetResponse | getresponse | api.getresponse.com |
| Grafana | grafana | User's Grafana instance |
| GitHub | github | api.github.com |
| Gumroad | gumroad | api.gumroad.com |
| Granola MCP | granola | mcp.granola.ai |
| Google Ads | google-ads | googleads.googleapis.com |
| Google BigQuery | google-bigquery | bigquery.googleapis.com |
| Google Analytics Admin | google-analytics-admin | analyticsadmin.googleapis.com |
| Google Analytics Data | google-analytics-data | analyticsdata.googleapis.com |
| Google Calendar | google-calendar | www.googleapis.com |
| Google Classroom | google-classroom | classroom.googleapis.com |
| Google Contacts | google-contacts | people.googleapis.com |
| Google Docs | google-docs | docs.googleapis.com |
| Google Drive | google-drive | www.googleapis.com |
| Google Forms | google-forms | forms.googleapis.com |
| Gmail | google-mail | gmail.googleapis.com |
| Google Merchant | google-merchant | merchantapi.googleapis.com |
| Google Meet | google-meet | meet.googleapis.com |
| Google Play | google-play | androidpublisher.googleapis.com |
| Google Search Console | google-search-console | www.googleapis.com |
| Google Sheets | google-sheets | sheets.googleapis.com |
| Google Slides | google-slides | slides.googleapis.com |
| Google Tasks | google-tasks | tasks.googleapis.com |
| Google Workspace Admin | google-workspace-admin | admin.googleapis.com |
| GoHighLevel (PIT) | highlevel-pit | services.leadconnectorhq.com |
| HubSpot | hubspot | api.hubapi.com |
| Instantly | instantly | api.instantly.ai |
| Jira | jira | api.atlassian.com |
| Jobber | jobber | api.getjobber.com |
| JotForm | jotform | api.jotform.com |
| Kaggle | kaggle | api.kaggle.com |
| Keap | keap | api.infusionsoft.com |
| Kibana | kibana | User's Kibana instance |
| Kit | kit | api.kit.com |
| Klaviyo | klaviyo | a.klaviyo.com |
| Lemlist | lemlist | api.lemlist.com |
| Linear | linear | api.linear.app |
| LinkedIn | linkedin | api.linkedin.com |
| Mailchimp | mailchimp | {dc}.api.mailchimp.com |
| MailerLite | mailerlite | connect.mailerlite.com |
| Mailgun | mailgun | api.mailgun.net |
| Make | make | {zone}.make.com |
| ManyChat | manychat | api.manychat.com |
| Manus | manus | api.manus.ai |
| Memelord | memelord | www.memelord.com |
| Meta Ads | meta-ads | graph.facebook.com |
| Microsoft Excel | microsoft-excel | graph.microsoft.com |
| Microsoft Teams | microsoft-teams | graph.microsoft.com |
| Microsoft To Do | microsoft-to-do | graph.microsoft.com |
| Monday.com | monday | api.monday.com |
| Motion | motion | api.usemotion.com |
| Netlify | netlify | api.netlify.com |
| Notion | notion | api.notion.com |
| Notion MCP | notion | mcp.notion.com |
| OneNote | one-note | graph.microsoft.com |
| OneDrive | one-drive | graph.microsoft.com |
| Outlook | outlook | graph.microsoft.com |
| PDF.co | pdf-co | api.pdf.co |
| Pipedrive | pipedrive | api.pipedrive.com |
| Podio | podio | api.podio.com |
| PostHog | posthog | {subdomain}.posthog.com |
| QuickBooks | quickbooks | quickbooks.api.intuit.com |
| Quo | quo | api.openphone.com |
| Reducto | reducto | platform.reducto.ai |
| Resend | resend | api.resend.com |
| Salesforce | salesforce | {instance}.salesforce.com |
| Sentry | sentry | {subdomain}.sentry.io |
| SharePoint | sharepoint | graph.microsoft.com |
| SignNow | signnow | api.signnow.com |
| Slack | slack | slack.com |
| Snapchat | snapchat | adsapi.snapchat.com |
| Square | squareup | connect.squareup.com |
| Squarespace | squarespace | api.squarespace.com |
| Stripe | stripe | api.stripe.com |
| Sunsama MCP | sunsama | MCP server |
| Supabase | supabase | {project_ref}.supabase.co |
| Systeme.io | systeme | api.systeme.io |
| Tally | tally | api.tally.so |
| Tavily | tavily | api.tavily.com |
| Telegram | telegram | api.telegram.org |
| TickTick | ticktick | api.ticktick.com |
| Todoist | todoist | api.todoist.com |
| Toggl Track | toggl-track | api.track.toggl.com |
| Trello | trello | api.trello.com |
| Twilio | twilio | api.twilio.com |
| Twenty CRM | twenty | api.twenty.com |
| Typeform | typeform | api.typeform.com |
| Unbounce | unbounce | api.unbounce.com |
| Vercel | vercel | api.vercel.com |
| Vimeo | vimeo | api.vimeo.com |
| WATI | wati | {tenant}.wati.io |
| WhatsApp Business | whatsapp-business | graph.facebook.com |
| WooCommerce | woocommerce | {store-url}/wp-json/wc/v3 |
| WordPress.com | wordpress | public-api.wordpress.com |
| Wrike | wrike | www.wrike.com |
| Xero | xero | api.xero.com |
| YouTube | youtube | www.googleapis.com |
| Zoom | zoom | api.zoom.us |
| Zoom Admin | zoom-admin | api.zoom.us |
| Zoho Bigin | zoho-bigin | www.zohoapis.com |
| Zoho Bookings | zoho-bookings | www.zohoapis.com |
| Zoho Books | zoho-books | www.zohoapis.com |
| Zoho Calendar | zoho-calendar | calendar.zoho.com |
| Zoho CRM | zoho-crm | www.zohoapis.com |
| Zoho Inventory | zoho-inventory | www.zohoapis.com |
| Zoho Mail | zoho-mail | mail.zoho.com |
| Zoho People | zoho-people | people.zoho.com |
| Zoho Projects | zoho-projects | projectsapi.zoho.com |
| Zoho Recruit | zoho-recruit | recruit.zoho.com |
See references/ for detailed routing guides per provider:
Examples
Slack - List Channels (Native API)
# Native Slack API: GET https://slack.com/api/conversations.list
python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://api.maton.ai/slack/api/conversations.list?types=public_channel&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
HubSpot - List Contacts (Native API)
# Native HubSpot API: GET https://api.hubapi.com/crm/v3/objects/contacts
python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://api.maton.ai/hubspot/crm/v3/objects/contacts?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
Google Sheets - Get Spreadsheet Values (Native API)
# Native Sheets API: GET https://sheets.googleapis.com/v4/spreadsheets/{id}/values/{range}
python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://api.maton.ai/google-sheets/v4/spreadsheets/{spreadsheet_id}/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 Query (Native API)
# Native 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://api.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 - List Tables (Native API)
# Native Airtable API: GET https://api.airtable.com/v0/meta/bases/{id}/tables
python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://api.maton.ai/airtable/v0/meta/bases/{base_id}/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 - Query Database (Native API)
# Native 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://api.maton.ai/notion/v1/data_sources/{data_source_id}/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 - List Customers (Native API)
# Native Stripe API: GET https://api.stripe.com/v1/customers
python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://api.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
Code Examples
JavaScript (Node.js)
const response = await fetch('https://api.maton.ai/slack/api/conversations.list?types=public_channel&limit=10', {
headers: {
'Authorization': Bearer ${process.env.MATON_API_KEY}
}
});
const data = await response.json();
Python
import os
import requestsresponse = requests.get(
'https://api.maton.ai/slack/api/conversations.list?types=public_channel&limit=10',
headers={'Authorization': f'Bearer {os.environ["MATON_API_KEY"]}'}
)
data = response.json()
Error Handling
| Status | Meaning | |--------|---------| | 400 | Missing connection for the requested app | | 401 | Invalid or missing Maton API key | | 429 | Rate limited (10 requests/second per account) | | 500 | Internal Server Error | | 4xx/5xx | Passthrough error from the target API |
Errors from the target API are passed through with their original status codes and response bodies.
Troubleshooting: API Key Issues
1. Check that the MATON_API_KEY environment variable is set:
echo $MATON_API_KEY
2. Verify the API key is valid by listing connections:
python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://api.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
Troubleshooting: Invalid App Name
1. Verify your URL path starts with the correct app name. The path must begin with /google-mail/. For example:
https://api.maton.ai/google-mail/gmail/v1/users/me/messageshttps://api.maton.ai/gmail/v1/users/me/messages2. Ensure you have an active connection for the app. List your connections to verify:
python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://api.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
Troubleshooting: Server Error
A 500 error may indicate expired service authorization. Try creating a new connection via the Connection Management section above and completing service authorization. If the new connection is "ACTIVE", delete the old connection to ensure Maton uses the new one.
Rate Limits
Notes
fields[], sort[], records[]), use the -g flag to disable glob parsingjq, environment variables may not expand correctly in some shells, which can cause "Invalid API key" errorswww.linkedin.com upload URLs while API calls use api.linkedin.com). These upload URLs are pre-signed and do NOT require an Authorization header. Upload the binary directly to the returned URL. You MUST use Python urllib for these uploads because the URLs contain encoded characters (e.g., %253D) that get corrupted when passed through shell variables or curl. Always parse the JSON response with json.load() and use the URL directly in Python.Tips
1. Use native API docs: Refer to each service's official API documentation for endpoint paths and parameters.
2. Headers are forwarded: Custom headers (except Host and Authorization) are forwarded to the target API.
3. Query params work: URL query parameters are passed through to the target API.
4. HTTP methods: Use the method required by the referenced endpoint. Confirm the exact target and expected outcome before methods that change data.
5. QuickBooks special case: Use :realmId in the path and it will be replaced with the connected realm ID.
Optional
π‘ Examples
Slack - List Channels (Native API)
# Native Slack API: GET https://slack.com/api/conversations.list
python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://api.maton.ai/slack/api/conversations.list?types=public_channel&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
HubSpot - List Contacts (Native API)
# Native HubSpot API: GET https://api.hubapi.com/crm/v3/objects/contacts
python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://api.maton.ai/hubspot/crm/v3/objects/contacts?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
Google Sheets - Get Spreadsheet Values (Native API)
# Native Sheets API: GET https://sheets.googleapis.com/v4/spreadsheets/{id}/values/{range}
python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://api.maton.ai/google-sheets/v4/spreadsheets/{spreadsheet_id}/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 Query (Native API)
# Native 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://api.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 - List Tables (Native API)
# Native Airtable API: GET https://api.airtable.com/v0/meta/bases/{id}/tables
python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://api.maton.ai/airtable/v0/meta/bases/{base_id}/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 - Query Database (Native API)
# Native 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://api.maton.ai/notion/v1/data_sources/{data_source_id}/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 - List Customers (Native API)
# Native Stripe API: GET https://api.stripe.com/v1/customers
python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://api.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
π Tips & Best Practices
1. Use native API docs: Refer to each service's official API documentation for endpoint paths and parameters.
2. Headers are forwarded: Custom headers (except Host and Authorization) are forwarded to the target API.
3. Query params work: URL query parameters are passed through to the target API.
4. HTTP methods: Use the method required by the referenced endpoint. Confirm the exact target and expected outcome before methods that change data.
5. QuickBooks special case: Use :realmId in the path and it will be replaced with the connected realm ID.