TypeScript / JavaScript SDK
npm install @synterai/sdk-js. A typed client for POST /api/v1/tools/run. Server-side only: the key can change live ad accounts, so never ship it to a browser.
Install and authenticate
// npm install @synterai/sdk-js
import { Synter, SynterError } from '@synterai/sdk-js';
const synter = new Synter({ apiKey: process.env.SYNTER_API_KEY! });The client sends Authorization: Bearer syn_….
| 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, 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.
Read
const campaigns = await synter.campaigns.list({ platform: 'google' });
const performance = await synter.analytics.getPerformance({
platform: 'google',
date_range: 'LAST_7_DAYS',
});Write: pause a campaign and change its daily budget
These calls change a live Google Ads campaign. platform is required, but the request always goes to Google Ads; use the REST endpoints for other platforms.
const campaignId = '1234567890';
// Pause (Google Ads)
const paused = await synter.campaigns.pause({ campaign_id: campaignId, platform: 'google' });
// Change the daily budget to 75.00 in the account currency.
// campaigns.updateBudget() in @synterai/sdk-js 0.1.2 sends --budget, which the
// API rejects with 400 UNRECOGNIZED_ARGS before anything runs. Use execute()
// until the next release (keys become flags: daily_budget -> --daily-budget):
try {
const result = await synter.execute(
'update_campaign_budget',
{ campaign_id: campaignId, daily_budget: 75 },
'google',
);
if (result.status === 'pending_review') {
console.log('Held for approval, nothing ran:', result.audit_id);
}
} catch (error) {
if (error instanceof SynterError) {
console.error(error.status, error.code); // 403 = blocked by policy or scope
}
throw error;
}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 for who approves what and where.