API Gateway#

Passthrough proxy for direct access to third-party APIs using managed OAuth connections, provided by Maton. The API gateway lets you call native API endpoints directly.

Quick Start#

bash

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

text

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

Replace {app} with the service name and {native-api-path} with the actual API endpoint path.

IMPORTANT: The URL path MUST start with the connection's app name (eg. /google-mail/...). This prefix tells the gateway which app connection to use. For example, the native Gmail API path starts with gmail/v1/, so full paths look like /google-mail/gmail/v1/users/me/messages.

Authentication#

All requests require the Maton API key in the Authorization header:

text

Authorization: Bearer $MATON_API_KEY

The API gateway automatically injects the appropriate OAuth token for the target service.

Environment Variable: You can set your API key as the MATON_API_KEY environment variable:

bash

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://ctrl.maton.ai

List Connections#

bash

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

Query Parameters (optional):

• app - Filter by service name (e.g., slack, hubspot, salesforce)
• status - Filter by connection status ( ACTIVE, PENDING, FAILED)

Response:

json

{
  "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": {}
    }
  ]
}

Create Connection#

bash

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

Request Body:

• app (required) - Service name (e.g., slack, notion)
• method (optional) - Connection method ( API_KEY, BASIC, OAUTH1, OAUTH2, MCP)

Get Connection#

bash

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

Response:

json

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

Open the returned URL in a browser to complete OAuth.

Delete Connection#

bash

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

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:

bash

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

If omitted, the gateway uses the default (oldest) active connection for that app.

Supported Services#

ServiceApp NameBase URL ProxiedActiveCampaignactive-campaign``{account}.api-us1.comAcuity Schedulingacuity-scheduling``acuityscheduling.comAirtableairtable``api.airtable.comApolloapollo``api.apollo.ioAsanaasana``app.asana.comAttioattio``api.attio.comBasecampbasecamp``3.basecampapi.comBaserowbaserow``api.baserow.iobeehiivbeehiiv``api.beehiiv.comBoxbox``api.box.comBrevobrevo``api.brevo.comBrave Searchbrave-search``api.search.brave.comBufferbuffer``api.buffer.comCalendlycalendly``api.calendly.comCal.comcal-com``api.cal.comCallRailcallrail``api.callrail.comChargebeechargebee``{subdomain}.chargebee.comClickFunnelsclickfunnels``{subdomain}.myclickfunnels.comClickSendclicksend``rest.clicksend.comClickUpclickup``api.clickup.comClockifyclockify``api.clockify.meCodacoda``coda.ioConfluenceconfluence``api.atlassian.comCompanyCamcompanycam``api.companycam.comCognito Formscognito-forms``www.cognitoforms.comConstant Contactconstant-contact``api.cc.emailDropboxdropbox``api.dropboxapi.comDropbox Businessdropbox-business``api.dropboxapi.comElevenLabselevenlabs``api.elevenlabs.ioEventbriteeventbrite``www.eventbriteapi.comExaexa``api.exa.aifal.aifal-ai``queue.fal.runFathomfathom``api.fathom.aiFirecrawlfirecrawl``api.firecrawl.devFirebasefirebase``firebase.googleapis.comFirefliesfireflies``api.fireflies.aiGetResponsegetresponse``api.getresponse.comGrafanagrafanaUser's Grafana instanceGitHubgithub``api.github.comGumroadgumroad``api.gumroad.comGranola MCPgranola``mcp.granola.aiGoogle Adsgoogle-ads``googleads.googleapis.comGoogle BigQuerygoogle-bigquery``bigquery.googleapis.comGoogle Analytics Admingoogle-analytics-admin``analyticsadmin.googleapis.comGoogle Analytics Datagoogle-analytics-data``analyticsdata.googleapis.comGoogle Calendargoogle-calendar``www.googleapis.comGoogle Classroomgoogle-classroom``classroom.googleapis.comGoogle Contactsgoogle-contacts``people.googleapis.comGoogle Docsgoogle-docs``docs.googleapis.comGoogle Drivegoogle-drive``www.googleapis.comGoogle Formsgoogle-forms``forms.googleapis.comGmailgoogle-mail``gmail.googleapis.comGoogle Merchantgoogle-merchant``merchantapi.googleapis.comGoogle Meetgoogle-meet``meet.googleapis.comGoogle Playgoogle-play``androidpublisher.googleapis.comGoogle Search Consolegoogle-search-console``www.googleapis.comGoogle Sheetsgoogle-sheets``sheets.googleapis.comGoogle Slidesgoogle-slides``slides.googleapis.comGoogle Tasksgoogle-tasks``tasks.googleapis.comGoogle Workspace Admingoogle-workspace-admin``admin.googleapis.comHubSpothubspot``api.hubapi.comInstantlyinstantly``api.instantly.aiJirajira``api.atlassian.comJobberjobber``api.getjobber.comJotFormjotform``api.jotform.comKagglekaggle``api.kaggle.comKeapkeap``api.infusionsoft.comKibanakibanaUser's Kibana instanceKitkit``api.kit.comKlaviyoklaviyo``a.klaviyo.comLemlistlemlist``api.lemlist.comLinearlinear``api.linear.appLinkedInlinkedin``api.linkedin.comMailchimpmailchimp``{dc}.api.mailchimp.comMailerLitemailerlite``connect.mailerlite.comMailgunmailgun``api.mailgun.netManyChatmanychat``api.manychat.comManusmanus``api.manus.aiMemelordmemelord``www.memelord.comMicrosoft Excelmicrosoft-excel``graph.microsoft.comMicrosoft Teamsmicrosoft-teams``graph.microsoft.comMicrosoft To Domicrosoft-to-do``graph.microsoft.comMonday.commonday``api.monday.comMotionmotion``api.usemotion.comNetlifynetlify``api.netlify.comNotionnotion``api.notion.comNotion MCPnotion``mcp.notion.comOneNoteone-note``graph.microsoft.comOneDriveone-drive``graph.microsoft.comOutlookoutlook``graph.microsoft.comPDF.copdf-co``api.pdf.coPipedrivepipedrive``api.pipedrive.comPodiopodio``api.podio.comPostHogposthog``{subdomain}.posthog.comQuickBooksquickbooks``quickbooks.api.intuit.comQuoquo``api.openphone.comReductoreducto``platform.reducto.aiResendresend``api.resend.comSalesforcesalesforce``{instance}.salesforce.comSentrysentry``{subdomain}.sentry.ioSharePointsharepoint``graph.microsoft.comSignNowsignnow``api.signnow.comSlackslack``slack.comSnapchatsnapchat``adsapi.snapchat.comSquaresquareup``connect.squareup.comSquarespacesquarespace``api.squarespace.comStripestripe``api.stripe.comSunsama MCPsunsamaMCP serverSupabasesupabase``{project_ref}.supabase.coSysteme.iosysteme``api.systeme.ioTallytally``api.tally.soTavilytavily``api.tavily.comTelegramtelegram``api.telegram.orgTickTickticktick``api.ticktick.comTodoisttodoist``api.todoist.comToggl Tracktoggl-track``api.track.toggl.comTrellotrello``api.trello.comTwiliotwilio``api.twilio.comTwenty CRMtwenty``api.twenty.comTypeformtypeform``api.typeform.comUnbounceunbounce``api.unbounce.comVercelvercel``api.vercel.comVimeovimeo``api.vimeo.comWATIwati``{tenant}.wati.ioWhatsApp Businesswhatsapp-business``graph.facebook.comWooCommercewoocommerce``{store-url}/wp-json/wc/v3WordPress.comwordpress``public-api.wordpress.comWrikewrike``www.wrike.comXeroxero``api.xero.comYouTubeyoutube``www.googleapis.comZoho Biginzoho-bigin``www.zohoapis.comZoho Bookingszoho-bookings``www.zohoapis.comZoho Bookszoho-books``www.zohoapis.comZoho Calendarzoho-calendar``calendar.zoho.comZoho CRMzoho-crm``www.zohoapis.comZoho Inventoryzoho-inventory``www.zohoapis.comZoho Mailzoho-mail``mail.zoho.comZoho Peoplezoho-people``people.zoho.comZoho Projectszoho-projects``projectsapi.zoho.comZoho Recruitzoho-recruit``recruit.zoho.com

See references/ for detailed routing guides per provider:

• ActiveCampaign - Contacts, deals, tags, lists, automations, campaigns
• Acuity Scheduling - Appointments, calendars, clients, availability
• Airtable - Records, bases, tables
• Apollo - People search, enrichment, contacts
• Asana - Tasks, projects, workspaces, webhooks
• Attio - People, companies, records, tasks
• Basecamp - Projects, to-dos, messages, schedules, documents
• Baserow - Database rows, fields, tables, batch operations
• beehiiv - Publications, subscriptions, posts, custom fields
• Box - Files, folders, collaborations, shared links
• Brevo - Contacts, email campaigns, transactional emails, templates
• Brave Search - Web search, image search, news search, video search
• Buffer - Social media posts, channels, organizations, scheduling
• Calendly - Event types, scheduled events, availability, webhooks
• Cal.com - Event types, bookings, schedules, availability slots, webhooks
• CallRail - Calls, trackers, companies, tags, analytics
• Chargebee - Subscriptions, customers, invoices
• ClickFunnels - Contacts, products, orders, courses, webhooks
• ClickSend - SMS, MMS, voice messages, contacts, lists
• ClickUp - Tasks, lists, folders, spaces, webhooks
• Clockify - Time tracking, projects, clients, tasks, workspaces
• Coda - Docs, pages, tables, rows, formulas, controls
• Confluence - Pages, spaces, blogposts, comments, attachments
• CompanyCam - Projects, photos, users, tags, groups, documents
• Cognito Forms - Forms, entries, documents, files
• Constant Contact - Contacts, email campaigns, lists, segments
• Dropbox - Files, folders, search, metadata, revisions, tags
• Dropbox Business - Team members, groups, team folders, devices, audit logs
• ElevenLabs - Text-to-speech, voice cloning, sound effects, audio processing
• Eventbrite - Events, venues, tickets, orders, attendees
• Exa - Neural web search, content extraction, similar pages, AI answers, research tasks
• fal.ai - AI model inference (image generation, video, audio, upscaling)
• Fathom - Meeting recordings, transcripts, summaries, webhooks
• Firecrawl - Web scraping, crawling, site mapping, web search
• Firebase - Projects, web apps, Android apps, iOS apps, configurations
• Fireflies - Meeting transcripts, summaries, AskFred AI, channels
• GetResponse - Campaigns, contacts, newsletters, autoresponders, tags, segments
• Grafana - Dashboards, data sources, folders, annotations, alerts, teams
• GitHub - Repositories, issues, pull requests, commits
• Gumroad - Products, sales, subscribers, licenses, webhooks
• Granola MCP - MCP-based interface for meeting notes, transcripts, queries
• Google Ads - Campaigns, ad groups, GAQL queries
• Google Analytics Admin - Reports, dimensions, metrics
• Google Analytics Data - Reports, dimensions, metrics
• Google BigQuery - Datasets, tables, jobs, SQL queries
• Google Calendar - Events, calendars, free/busy
• Google Classroom - Courses, coursework, students, teachers, announcements
• Google Contacts - Contacts, contact groups, people search
• Google Docs - Document creation, batch updates
• Google Drive - Files, folders, permissions
• Google Forms - Forms, questions, responses
• Gmail - Messages, threads, labels
• Google Meet - Spaces, conference records, participants
• Google Merchant - Products, inventories, promotions, reports
• Google Play - In-app products, subscriptions, reviews
• Google Search Console - Search analytics, sitemaps
• Google Sheets - Values, ranges, formatting
• Google Slides - Presentations, slides, formatting
• Google Tasks - Task lists, tasks, subtasks
• Google Workspace Admin - Users, groups, org units, domains, roles
• HubSpot - Contacts, companies, deals
• Instantly - Campaigns, leads, accounts, email outreach
• Jira - Issues, projects, JQL queries
• Jobber - Clients, jobs, invoices, quotes (GraphQL)
• JotForm - Forms, submissions, webhooks
• Kaggle - Datasets, models, competitions, kernels
• Keap - Contacts, companies, tags, tasks, opportunities, campaigns
• Kibana - Saved objects, dashboards, data views, spaces, alerts, fleet
• Kit - Subscribers, tags, forms, sequences, broadcasts
• Klaviyo - Profiles, lists, campaigns, flows, events
• Lemlist - Campaigns, leads, activities, schedules, unsubscribes
• Linear - Issues, projects, teams, cycles (GraphQL)
• LinkedIn - Profile, posts, shares, media uploads
• Mailchimp - Audiences, campaigns, templates, automations
• MailerLite - Subscribers, groups, campaigns, automations, forms
• Mailgun - Email sending, domains, routes, templates, mailing lists, suppressions
• ManyChat - Subscribers, tags, flows, messaging
• Manus - AI agent tasks, projects, files, webhooks
• Memelord - AI meme generation, video memes, template editing
• Microsoft Excel - Workbooks, worksheets, ranges, tables, charts
• Microsoft Teams - Teams, channels, messages, members, chats
• Microsoft To Do - Task lists, tasks, checklist items, linked resources
• Monday.com - Boards, items, columns, groups (GraphQL)
• Motion - Tasks, projects, workspaces, schedules
• Netlify - Sites, deploys, builds, DNS, environment variables
• Notion - Pages, databases, blocks
• Notion MCP - MCP-based interface for pages, databases, comments, teams, users
• OneNote - Notebooks, sections, section groups, pages via Microsoft Graph
• OneDrive - Files, folders, drives, sharing
• Outlook - Mail, calendar, contacts
• PDF.co - PDF conversion, merge, split, edit, text extraction, barcodes
• Pipedrive - Deals, persons, organizations, activities
• Podio - Organizations, workspaces, apps, items, tasks, comments
• PostHog - Product analytics, feature flags, session recordings, experiments, HogQL queries
• QuickBooks - Customers, invoices, reports
• Quo - Calls, messages, contacts, conversations, webhooks
• Reducto - Document parsing, extraction, splitting, editing
• Resend - Transactional emails, domains, audiences, contacts, broadcasts, webhooks
• Salesforce - SOQL, sObjects, CRUD
• SignNow - Documents, templates, invites, e-signatures
• SendGrid - Email sending, contacts, templates, suppressions, statistics
• Sentry - Issues, events, projects, teams, releases
• SharePoint - Sites, lists, document libraries, files, folders, versions
• Slack - Messages, channels, users
• Snapchat - Ad accounts, campaigns, ad squads, ads, creatives, audiences
• Square - Payments, customers, orders, catalog, inventory, invoices
• Squarespace - Products, inventory, orders, profiles, transactions
• Stripe - Customers, subscriptions, payments
• Sunsama MCP - MCP-based interface for tasks, calendar, backlog, objectives, time tracking
• Supabase - Database tables, auth users, storage buckets
• Systeme.io - Contacts, tags, courses, communities, webhooks
• Tally - Forms, submissions, workspaces, webhooks
• Tavily - AI web search, content extraction, crawling, research tasks
• Telegram - Messages, chats, bots, updates, polls
• TickTick - Tasks, projects, task lists
• Todoist - Tasks, projects, sections, labels, comments
• Toggl Track - Time entries, projects, clients, tags, workspaces
• Trello - Boards, lists, cards, checklists
• Twilio - SMS, voice calls, phone numbers, messaging
• Twenty CRM - Companies, people, opportunities, notes, tasks
• Typeform - Forms, responses, insights
• Unbounce - Landing pages, leads, accounts, sub-accounts, domains
• Vercel - Projects, deployments, domains, environment variables
• Vimeo - Videos, folders, albums, comments, likes
• WATI - WhatsApp messages, contacts, templates, interactive messages
• WhatsApp Business - Messages, templates, media
• WooCommerce - Products, orders, customers, coupons
• WordPress.com - Posts, pages, sites, users, settings
• Wrike - Tasks, folders, projects, spaces, comments, timelogs, workflows
• Xero - Contacts, invoices, reports
• YouTube - Videos, playlists, channels, subscriptions
• Zoho Bigin - Contacts, companies, pipelines, products
• Zoho Bookings - Appointments, services, staff, workspaces
• Zoho Books - Invoices, contacts, bills, expenses
• Zoho Calendar - Calendars, events, attendees, reminders
• Zoho CRM - Leads, contacts, accounts, deals, search
• Zoho Inventory - Items, sales orders, invoices, purchase orders, bills
• Zoho Mail - Messages, folders, labels, attachments
• Zoho People - Employees, departments, designations, attendance, leave
• Zoho Projects - Projects, tasks, milestones, tasklists, comments
• Zoho Recruit - Candidates, job openings, interviews, applications

Examples#

Slack - Post Message (Native API)#

bash

# Native 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 - Create Contact (Native API)#

bash

# Native 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 - Get Spreadsheet Values (Native API)#

bash

# 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://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 Query (Native API)#

bash

# 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://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 - List Tables (Native API)#

bash

# 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://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 - Query Database (Native API)#

bash

# 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://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 - List Customers (Native API)#

bash

# Native 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

Code Examples#

JavaScript (Node.js)#

javascript

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#

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!'}
)

Error Handling#

StatusMeaning400Missing connection for the requested app401Invalid or missing Maton API key429Rate limited (10 requests/second per account)500Internal Server Error4xx/5xxPassthrough 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:

bash

echo $MATON_API_KEY

1. Verify the API key is valid by listing connections:

bash

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

Troubleshooting: Invalid App Name#

1. Verify your URL path starts with the correct app name. The path must begin with /google-mail/. For example:

• Correct: https://gateway.maton.ai/google-mail/gmail/v1/users/me/messages
• Incorrect: https://gateway.maton.ai/gmail/v1/users/me/messages

1. Ensure you have an active connection for the app. List your connections to verify:

bash

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

Troubleshooting: Server Error#

A 500 error may indicate an expired OAuth token. Try creating a new connection via the Connection Management section above and completing OAuth authorization. If the new connection is "ACTIVE", delete the old connection to ensure the gateway uses the new one.

Rate Limits#

• 10 requests per second per account
• Target API rate limits also apply

Notes#

• When using curl with URLs containing brackets ( fields[], sort[], records[]), use the -g flag to disable glob parsing
• When piping curl output to jq, environment variables may not expand correctly in some shells, which can cause "Invalid API key" errors
• Media upload URLs (LinkedIn, etc.): Some APIs return pre-signed upload URLs that point to a different host than the gateway proxies (e.g., LinkedIn returns www.linkedin.com upload URLs, but the gateway proxies api.linkedin.com). These upload URLs are pre-signed and do NOT require an Authorization header — upload the binary directly to the returned URL without going through the gateway. 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. All HTTP methods supported: GET, POST, PUT, PATCH, DELETE are all supported.

5. QuickBooks special case: Use :realmId in the path and it will be replaced with the connected realm ID.

Optional#

• Github
• API Reference
• Maton Community
• Maton Support