API Reference

Authentication

All API requests require authentication using an API key

Get your API key

Generate an API key from the Developer Portal. Each key is tied to your account and has access to your connected ad platforms.

Get API Key

Using your API key

Send the key in one header per request. One table covers every surface; where a header is not listed, that surface does not read it.

Surface	Endpoint	Accepted	Use
REST tools endpoint	`POST https://synterai.com/api/v1/tools/run`	Authorization: Bearer syn_…, X-Synter-Key: syn_…, X-API-Key: syn_…	Authorization: Bearer syn_…
REST resource endpoints	`https://api.synterai.com/v1/… (campaigns, me, credits, tools/pending)`	Authorization: Bearer syn_…, X-Synter-Key: syn_…	Authorization: Bearer syn_…
SDKs (Python, TypeScript, Rust, Java, Go) and the synter CLI	`POST /api/v1/tools/run`	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)	`POST https://synterai.com/api/v1/tools/run`	Set SYNTER_API_KEY in the server's env block	The package sends Authorization: Bearer syn_…
Hosted MCP	`https://mcp.synterai.com`	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, 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.

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"}'

Whoami

GET https://api.synterai.com/v1/me returns the authenticated key's user_id, organization_id, scopes, and key name. There is no top-level /me on synterai.com; only this REST path.

bash

curl https://api.synterai.com/v1/me \
  -H "Authorization: Bearer $SYNTER_API_KEY"

Building for several clients or your own customers? See Multi-tenant and embedded auth for workspace-pinned keys, minting child keys, and what is not supported yet.

Key format

API keys follow this format:

syn_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Error responses

Code	Status	Description
401	Unauthorized	API key is missing or invalid
402	Payment Required	Insufficient credits for this operation
403	Forbidden	API key doesn't have permission for this action
429	Rate Limited	Too many requests, implement backoff

Security best practices

Use environment variables

Never hardcode API keys in your source code

Rotate keys regularly

Generate new keys periodically and revoke old ones

Keep your API key secure

Never expose your API key in client-side code, commit it to version control, or share it publicly. Use server-side requests to protect your key.

Was this page helpful?

PreviousBest Practices Next Multi-tenant Auth