API Reference

One production endpoint drives everything — the same surface the SDKs, the CLI, and every MCP client call. If you prefer raw HTTP, this is all you need.

Base URL & endpoint

All tool calls go to a single dispatcher. Send the tool name in script_name, its flags as an ordered args array, and (for platform-routed tools) the platform.

POST https://syntermedia.ai/api/v1/tools/run

A backend REST v1 also runs at https://api.syntermedia.ai/v1/ with the same key: POST /v1/tools/run, GET /v1/campaigns, GET /v1/campaigns/{id}/metrics, POST /v1/campaigns/{id}/pause, PATCH /v1/campaigns/{id}/budget, GET /v1/me, GET /v1/credits, GET /v1/connections (reference: docs.syntermedia.ai/api). The one shape that does not exist is api.syntermedia.ai/api/v1/....

Example request:

curl https://syntermedia.ai/api/v1/tools/run \
  -H "Authorization: Bearer syn_..." \
  -H "Content-Type: application/json" \
  -d '{
    "script_name": "list_campaigns",
    "args": ["--platform", "google", "--status", "ENABLED"],
    "platform": "google"
  }'

Two tools bypass this dispatcher: list_landing_pages uses GET /api/v1/landing-pages, and stage_audience_artifact posts to https://api.syntermedia.ai/artifacts/audience-sync-input with an X-Synter-Key header.

Script names are not MCP tool names. The REST dispatcher resolves the script name from the catalog. For Google Ads performance the canonical name is pull_google_ads. pull_google_ads_data (the script's filename) is accepted as a compatibility alias for older SDK builds, but pull_google_ads_performance is the MCP tool name and is not a dispatchable REST script. The published SDKs (@synterai/sdk-js ≥0.1.2, synter on PyPI ≥0.1.1, synter crate ≥0.1.1) send the canonical name via analytics.getPerformance / analytics.get_performance. To discover names, call GET /api/v1/tools (the paginated catalog, with ?q= search) or GET /api/v1/tools/run (the dispatchable script names); both take the same key.

Authentication

Authenticate with your API key on every request — either header works, Bearer is preferred:

Authorization: Bearer syn_...
# or
X-Synter-Key: syn_...

Keys are syn_ + 32 characters, auto-generated on signup, and managed in the Developer portal. They are secrets — keep them server-side.

Errors, rate limits & retries

Non-2xx responses carry a JSON body { "error": "message" }. A 429 includes a Retry-After header (seconds). The SDKs retry up to 3 times with exponential backoff (1s base, 10s cap) on 429 and network/timeout errors only — never on other 4xx. Default timeout is 30s.

HTTP/1.1 429 Too Many Requests
Retry-After: 3

{ "error": "Rate limit exceeded" }

Using an AI agent instead?

You usually don't call this API by hand — point your agent at the hosted MCP server and it uses these tools for you. See the MCP quickstart for Claude, Cursor, ChatGPT, Codex, and more, or the full tool catalog.

Get started with an SDK