The gateway proxies your requests to a connected app's native API. When you call the gateway, Maton looks up the connection, injects the app credentials, and forwards the request to the upstream API.
Routing
Prefix any native API path with the app identifier:
https://api.maton.ai/{app}/{native-api-path}The first path segment selects the target app. Everything after it including query string is forwarded to the upstream API.
# Slack — GET https://slack.com/api/conversations.list
curl "https://api.maton.ai/slack/api/conversations.list?types=public_channel&limit=10" \
-H "Authorization: Bearer $MATON_API_KEY"
# Gmail — GET https://gmail.googleapis.com/gmail/v1/users/me/messages
curl "https://api.maton.ai/google-mail/gmail/v1/users/me/messages" \
-H "Authorization: Bearer $MATON_API_KEY"// POST https://api.hubapi.com/crm/v3/objects/contacts/search
const response = await fetch(
'https://api.maton.ai/hubspot/crm/v3/objects/contacts/search',
{
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.MATON_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({ properties: ['email', 'firstname'], limit: 10 }),
}
)import os, requests
# POST https://api.hubapi.com/crm/v3/objects/contacts/search
response = requests.post(
"https://api.maton.ai/hubspot/crm/v3/objects/contacts/search",
headers={"Authorization": f"Bearer {os.environ['MATON_API_KEY']}"},
json={"properties": ["email", "firstname"], "limit": 10},
)Refer to each service's official API documentation for its endpoint paths and parameters.
Path Placeholders
For apps that require account-specific identifiers in the path, put the literal placeholder (eg. :realmId for QuickBooks) in the path and the gateway substitutes the connected account's value:
curl "https://api.maton.ai/quickbooks/v3/company/:realmId/query?query=SELECT%20*%20FROM%20Customer" \
-H "Authorization: Bearer $MATON_API_KEY"Specifying connection
The gateway allows you to specify a connection if you have multiple connections for an app. Pass the connection ID in the Maton-Connection header. When omitted, the gateway uses the oldest ACTIVE connection by default.
curl "https://api.maton.ai/slack/api/conversations.list?types=public_channel&limit=10" \
-H "Authorization: Bearer $MATON_API_KEY" \
-H "Maton-Connection: 21fd90f9-5935-43cd-b6c8-bde9d915ca80"import os, requests
response = requests.get(
"https://api.maton.ai/slack/api/conversations.list?types=public_channel&limit=10",
headers={
"Authorization": f"Bearer {os.environ['MATON_API_KEY']}",
"Maton-Connection": "21fd90f9-5935-43cd-b6c8-bde9d915ca80",
},
)
print(response.json())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}`,
'Maton-Connection': '21fd90f9-5935-43cd-b6c8-bde9d915ca80',
},
}
)
console.log(await response.json())Finding connection ID
List your connections for an app, filtering by ACTIVE status. Use the connection's metadata to tell accounts apart, which holds identifying details such as email or workspace name.
curl "https://api.maton.ai/connections?app=slack&status=ACTIVE" \
-H "Authorization: Bearer $MATON_API_KEY"{
"connections": [
{
"connection_id": "21fd90f9-5935-43cd-b6c8-bde9d915ca80",
"status": "ACTIVE",
"app": "slack",
"method": "OAUTH2",
"metadata": {
"team": "Acme Workspace"
}
}
]
}Common Questions
We store request metadata such as the URL, method, and headers for operational purposes. We never store request or response bodies.