SDK

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 (@synterai/sdk-js >= 0.2.0)
try {
  const result = await synter.campaigns.updateBudget({
    campaign_id: campaignId,
    daily_budget: 75,
    platform: '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;
}

Closed-Loop Readback Verification

For autonomous coding agents operating under authorized apply mode, @synterai/sdk-jsprovides atomic write-and-verify helpers. These mutate the campaign and immediately read back effective provider state rather than assuming success from a 2xx response:

// Atomic budget update with verification readback
const budgetVerified = await synter.campaigns.updateBudgetAndVerify({
  campaign_id: campaignId,
  daily_budget: 25.0,
  platform: 'google',
});
console.log('Effective provider budget:', budgetVerified.verifiedState);

// Atomic pause with verification readback
const pauseVerified = await synter.campaigns.pauseAndVerify({
  campaign_id: campaignId,
  platform: 'google',
});
console.log('Effective provider status:', pauseVerified.verifiedState);

Agent Intelligence & Pre-Flight Audits

SDK 0.2.0 includes dedicated resources for compliance, negative keyword isolation, and skill execution:

// Pre-flight governance & compliance review
const review = await synter.angstrom.reviewBuildPlan({
  workspaceId: 'ws_prod',
  campaignPlan: { name: 'Q4 Performance Max' },
});

// Brand cannibalization and negative search term audit
const shieldAudit = await synter.shield.auditBrandCannibalization({
  campaignId: campaignId,
});

// Autonomous domain skills orchestration
const skillResult = await synter.skills.execute({
  skillId: 'marginal-cpa-budget-rebalancer',
  threshold: 50.0,
});

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.

Was this page helpful?

PreviousPython SDK Next Rust SDK