Overview

Base URL

https://api.maton.ai

Quickstart

Get your API key

Go to Maton and navigate to Settings, then copy your API key and store it as an environment variable. See Authentication for more details.

export MATON_API_KEY="YOUR_API_KEY"

Connect an app

Create a connection for the app you want to use. See apps for a list of supported apps.

curl -X POST https://api.maton.ai/connections \
  -H "Authorization: Bearer $MATON_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"app": "slack"}'

Then fetch connection details and open its url in a browser to complete the connection:

curl https://api.maton.ai/connections/{connection_id} \
  -H "Authorization: Bearer $MATON_API_KEY"

{
  "connection": {
    "connection_id": "{connection_id}",
    "status": "PENDING",
    "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": {}
  }
}

Make your first request

Call the connected app's native API through the gateway.

curl "https://api.maton.ai/slack/api/conversations.list?types=public_channel&limit=10" \
  -H "Authorization: Bearer $MATON_API_KEY"

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()
console.log(data)

import os
import requests

response = requests.get(
    "https://api.maton.ai/slack/api/conversations.list",
    params={"types": "public_channel", "limit": 10},
    headers={"Authorization": f"Bearer {os.environ['MATON_API_KEY']}"},
)

data = response.json()
print(data)

Response Format

Gateway returns the third-party API response verbatim including status code, headers, and body.

200 OK
Content-Type: application/json

{
  "ok": true,
  "channels": [
    {
      "id": "C0123456789",
      "name": "general",
      "is_channel": true,
      "is_private": false,
      "num_members": 12
    },
    {
      "id": "C0987654321",
      "name": "random",
      "is_channel": true,
      "is_private": false,
      "num_members": 8
    }
  ],
  "response_metadata": {
    "next_cursor": "dGVhbTpDMDYxRkE1UEI="
  }
}

Error Handling

Errors originate from one of two sources: Maton or the third-party API you're calling through the gateway.

Maton errors

Errors raised by Maton return a body with message, type, and code.

400 Bad Request
Content-Type: application/json
X-Request-Id: 6804a34b-1e46-4f32-b4b1-b03f1f89ccd1

{
  "message": "Invalid app name.",
  "type": "Bad Request",
  "code": 400
}

Status	Meaning	What to do
`400`	Invalid request, unknown app, or no connection for the target app	Check the app name and that an `ACTIVE` connection exists
`401`	Missing or invalid API key	Verify your `Authorization: Bearer` header
`404`	Resource not found or not owned by your account	Verify the ID (or `Maton-Connection`) is correct
`429`	Rate limit exceeded	Back off and retry with exponential backoff
`500`	Internal server error	Recreate the connection and retry

Third-party API errors

Gateway returns third-party API errors verbatim including status code, header, and body.

200 OK
Content-Type: application/json
X-Request-Id: 361023c4-920f-4c8a-b0e2-fde62a8e7a39

{
  "ok": false,
  "error": "channel_not_found"
}

Rate Limits

Default: 10 requests per second per account.
The gateway requests are also subject to the third-party API's own rate limits.
To increase rate limit, reach out to support@maton.ai to upgrade your plan.

Pagination

The list response includes a next_token. Pass it back on the next request to fetch the following page. When next_token is absent, you have reached the last page.

# First page
curl "https://api.maton.ai/triggers?limit=20" \
  -H "Authorization: Bearer $MATON_API_KEY"

# Next page — use next_token from the previous response
curl "https://api.maton.ai/triggers?limit=20&next_token=gAAAAABq..." \
  -H "Authorization: Bearer $MATON_API_KEY"

Overview

On this page