---
title: "Quickstart API &amp; MCP Setup"
description: "Create a Synter API key, configure MCP, and make your first advertising automation request in under five minutes."
url: https://docs.synterai.com/
---

# Quickstart API &amp; MCP Setup

Copy as Markdown[View as Markdown](/quickstart.md "Open the Markdown version of this page")

Get Started

# Get started with Synter

Make your first API call in under 5 minutes

[

### Playground

Test API calls interactively in the Playground



](/playground)[

### MCP Server

Connect your AI assistant directly to your ad accounts



](/mcp/configuration)

## Hosted MCP server

Use this server URL for Claude, Codex, or another client that supports Streamable HTTP and browser OAuth:

text

```
https://mcp.synterai.com
```

Browser OAuth does not require an API key. Follow the [MCP configuration guide](/mcp/configuration) for your client. The API key steps below apply to direct API and SDK requests.

Updating an existing MCP connection

If your saved server URL uses an older domain, use `https://mcp.synterai.com` and sign in with the account for your existing workspace. You do not need to delete the workspace or its connected ad accounts to update the server URL.

Root endpoint and /mcp compatibility path

The canonical install URL is `https://mcp.synterai.com`. The same service also accepts `https://mcp.synterai.com/mcp`; it is a compatibility path, not a second server or a separate integration. Use the root URL consistently in a new client configuration. For an account-scoped first read, follow the [Google Ads and Meta Ads reporting workflow for Codex](/mcp/overview#codex-google-meta-reporting).

## Installation

PythonJavaScriptcURL

```
pip install synter
```

## Quick start guide

1

### Get your API key

Create an account and generate your API key from the [Developer Portal](https://synterai.com/developer).

[Get API Key](https://synterai.com/developer)

2

### Set your environment variable

Store your API key as an environment variable for secure access.

bash

```
export SYNTER_API_KEY=syn_your_api_key_here
```

3

### Make your first request

Read your Google Ads campaigns. Script names are platform-prefixed, so swap the prefix for another platform: `meta_ads_get_campaigns`, `linkedin_ads_get_campaigns`, `reddit_ads_get_campaigns`, and so on.

bash

```
curl -X POST https://synterai.com/api/v1/tools/run \
  -H "Authorization: Bearer $SYNTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "script_name": "google_ads_get_campaigns"
  }'
```

## Java SDK: read Google Ads performance

Use Java 17 or later and version 0.1.1 or later from Maven Central (the full guide, including writes, is on the [Java SDK page](/sdk/java)). Connect your Google Ads account in Synter first, then set `SYNTER_API_KEY` as shown above. Keep the key on your server, never in browser code.

GradleMaven

```
repositories { mavenCentral() }
dependencies {
    implementation("ai.syntermedia:synter-sdk:0.1.1")
}
```

java

```
import ai.syntermedia.sdk.Synter;
import ai.syntermedia.sdk.SynterException;
import ai.syntermedia.sdk.requests.GetPerformanceRequest;
import java.util.Map;

public class PerformanceReport {
    public static void main(String[] args) {
        Synter synter = Synter.builder()
            .apiKey(System.getenv("SYNTER_API_KEY"))
            .build();

        try {
            Map<String, Object> result = synter.analytics().getPerformance(
                GetPerformanceRequest.builder()
                    .platform("google")
                    .dateRange("LAST_7_DAYS")
                    .build());
            // Process result in your app; do not log raw account data.
            System.out.println("Performance request completed.");
        } catch (SynterException error) {
            System.err.println("Request failed (status " + error.getStatus() + ").");
            System.exit(1);
        }
    }
}
```

This is a read, not a campaign launch. The SDK sends `pull_google_ads` with `--days 7` to `POST /api/v1/tools/run` and returns the response as a map. It authenticates with `Authorization: Bearer $SYNTER_API_KEY`, like every Synter SDK. Which header each surface accepts:

Surface

Accepted

Use

REST tools endpoint

Authorization: Bearer syn\_…, X-Synter-Key: syn\_…, X-API-Key: syn\_…

Authorization: Bearer syn\_…

REST resource endpoints

Authorization: Bearer syn\_…, X-Synter-Key: syn\_…

Authorization: Bearer syn\_…

SDKs (Python, TypeScript, Rust, Java, Go) and the synter CLI

The SDK sets the header for you

Pass the key to the client. Every SDK sends Authorization: Bearer syn\_…

Local stdio MCP (npm @synterai/mcp-server)

Set SYNTER\_API\_KEY in the server's env block

The package sends Authorization: Bearer syn\_…

Hosted MCP

Browser OAuth (the client sends Authorization: Bearer <OAuth access token>), or X-Synter-Key: syn\_… for headless clients

OAuth. Headless: X-Synter-Key. Do not put an API key in Authorization on this host.

Keys start with `syn_` (sandbox keys with `syn_test_`). Create one at [synterai.com/developer](https://synterai.com/developer), keep it in `SYNTER_API_KEY` or a secret store, and send one header per request. On the hosted MCP endpoint, the `Authorization` header is reserved for the OAuth token the client gets from browser sign-in, so a failed key there shows up as a sign-in prompt rather than a key error. Use `X-Synter-Key` when you connect a hosted MCP client with a key. Details: [Authentication](/api/authentication).

Handle API errors explicitly

The Java SDK throws `SynterException` for HTTP errors; inspect `getStatus()`. A 401 means authentication failed; check your key and environment. A 402 indicates a billing or credit restriction; inspect the response and billing settings rather than retrying. A 403 means access is denied; check the key's scopes and workspace access. For 429, the SDK retries up to three times with backoff and honors `Retry-After`; if it still fails, reduce request frequency.

## Pause a campaign and change its budget

These change a live campaign. REST takes a `platform`; the SDK pause and budget methods reach Google Ads only. Per-language code is on each [SDK page](/sdk).

RESTCLI

```
curl -X POST https://api.synterai.com/v1/campaigns/1234567890/pause \
  -H "Authorization: Bearer $SYNTER_API_KEY" \
  -H "Content-Type: application/json" -d '{"platform": "GOOGLE"}'

curl -X PATCH https://api.synterai.com/v1/campaigns/1234567890/budget \
  -H "Authorization: Bearer $SYNTER_API_KEY" \
  -H "Content-Type: application/json" -d '{"platform": "GOOGLE", "daily_budget": 75}'
```

Writes the safety gate holds or refuses

With the default workspace policy, pausing a campaign and changing a budget run straight away and are recorded in the audit log. Enabling or resuming a campaign, deleting or removing anything, sending creative to a platform, and creating new campaigns can be held for approval. A held write returns HTTP 202 with `status: "pending_review"`, an `audit_id` and the exact `reviewed_args`. Nothing has run at that point. The SDKs return this body as a normal result, so check `status` before you report success.

A write the policy refuses (blocked tool, outside operating hours, over a monetary limit) returns HTTP 403 with `status: "blocked"`, and the SDKs raise their error type. Approval cannot override a block.

An API key cannot approve its own pending write. See [Approval model and safety controls](/mcp/approval-model) for who approves what and where.

## Log in with the CLI

Prefer the terminal? The Synter CLI can create and store an API key for you with no copy and paste:

bash

```
npm install -g synter
synter login
```

Choose the browser login option. The CLI opens `synterai.com/cli/login` with a one-time device code in the URL and prints a short confirmation code (like `ABCD-EFGH`) so you can verify you are on the right page. Sign in in the browser, and the page confirms the login automatically. The CLI is polling in the background: it picks up a freshly created API key and stores it locally, so there is nothing to paste.

Login links expire after 10 minutes

If the link expires before you finish signing in, run `synter login` again. Keys created this way appear as "CLI Login" in the [Developer Portal](https://synterai.com/developer), where you can revoke them at any time.

Test API calls in the Playground

Explore the platform interactively across 43 advertising platforms, the only Agentic DSP. Use the Playground to test API calls, run reports, and optimize campaigns.

[Try the Playground →](/playground)

## Frequently asked questions

What platforms are supported?

Synter supports 43 canonical ad platforms, including Google Ads, Microsoft Ads, Meta (Facebook & Instagram), LinkedIn Ads, X Ads, Reddit Ads, TikTok Ads, Snapchat Ads, Pinterest Ads, Spotify Ads, Amazon Ads, Amazon DSP, The Trade Desk, OpenAI Ads, Display & Video 360, StackAdapt, Taboola, Outbrain, Criteo, and retail media networks. Read and execution capabilities vary by platform API and active connection. See the [Integrations](/integrations) page for the full list and per-platform capabilities.

How do credits work?

Synter supports 43 advertising platforms, the only Agentic DSP. Synter charges 0% of ad spend (zero media markup). Paid plans unlock campaign writes and creative generation, with tool costs denominated in US dollars. Call `forecast_tool_cost` with the tool name to check the current cost in US dollars before running it. Use `get_credit_balance` to check your available usage value.

Is there a trial?

Paid plans for campaign mutations and execution are SOLO ($20/month or $200/year), SCALE ($500/month or $5,000/year), and CUSTOM (sales-led). Synter charges 0% of ad spend. See billing in the app.

Was this page helpful?

YesNo

[Next Playground](/playground)
