API Gateway

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

• Access is scoped to the specific third-party service connected through each Maton connection and the scopes the user authorized.
• Use least privilege. Connect only the services needed for the current task. Prefer read-only scopes and revoke unused connections promptly.
• Default to read/list calls. Retrieve or list resources first to verify identifiers, account context, and current state before proposing any change.
• All operations that modify data require explicit user approval. Before executing any POST, PUT, PATCH, or DELETE call, confirm the target service, resource, payload, and intended effect with the user. This includes sending messages, creating records, modifying content, deleting resources, and triggering workflows.
• High-impact operations require extra caution. Actions such as bulk deletions, publishing content, sending emails/messages to external recipients, modifying billing or financial data, or changing permissions must be clearly described with specific resource identifiers and confirmed before execution.
• Always specify the connection. Use the Maton-Connection header to ensure requests go to the intended account, especially when the user has multiple connections for the same service.

Supported Services

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
• Apify - Actors, runs, datasets, key-value stores, request queues, schedules
• 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
• Clio - Matters, contacts, activities, tasks, calendar entries, documents
• 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, tags, custom fields, segments, bulk activities, reporting
• 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)
• Facebook Page - Pages, posts, comments, insights, photos, videos, product catalogs
• 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
• Front - Conversations, messages, contacts, tags, inboxes, teammates
• 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
• GoHighLevel PIT - Contacts, opportunities, calendars, conversations, locations, custom fields
• 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
• 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 - Domains, routes, templates, mailing lists, suppressions
• Make - Scenarios, organizations, teams, connections, data stores, hooks
• ManyChat - Subscribers, tags, flows, messaging
• Manus - AI agent tasks, projects, files, webhooks
• Memelord - AI meme generation, video memes, template editing
• Meta Ads - Ad accounts, campaigns, ad sets, ads, creatives, insights
• 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 - Domains, audiences, contacts, webhooks
• Salesforce - SOQL, sObjects, CRUD
• SignNow - Documents, templates, invites, e-signatures
• SendGrid - 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 - Customers, orders, catalog, inventory, invoices
• Squarespace - Products, inventory, orders, profiles, transactions
• Stripe - Customers, subscriptions, account records
• 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
• Zoom - Meetings, recordings, webinars, users
• Zoom Admin - Users, meetings, webinars, recordings, account settings (admin scopes)
• 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, vendor 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 - 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

…(truncated)