Skip to main content
Use the SDK in software that calls Apostra’s V3 HTTP API. It does not open an MCP connection, open a browser, or retry writes for you. You need an API key or M2M access token with access to the intended account, or, for local development, a sign-in from apostra login. You also need a draft campaign to preview. This guide uses a provisioned synthetic buyer and draft campaign in automated checks. Do not put its credentials, or any production credential, in source code. Run the same steps with your own account and campaign before enabling a real launch.

1. Install the SDK

TypeScript requires Node.js 22.18 or later. Python requires Python 3.11 or later. The TypeScript SDK is ESM-only. The current paired SDK release is 0.38.0. Both SDKs are generated from the current V3 OpenAPI operation catalogue.

2. Supply a credential

In production, keep an API key in your server-side secret manager. These examples read the environment in application code and pass the value to the SDK. The SDK sends credentials only to the Apostra API.
APOSTRA_ACCOUNT_ID is optional when the credential already resolves to one account. If you set it, it must name an account that credential can reach. Sign in with apostra login for local development. Run npx @apostra/cli login, approve one account in your browser, and omit the credential: the TypeScript SDK in Node.js and the Python SDK then use that sign-in, with no API key in your code or environment. An API key you pass, or APOSTRA_API_KEY, always wins over a sign-in. Use an API key or M2M access token in CI and on servers. See the Apostra CLI.

3. Verify the account

Call getStatus before a write. It returns the account resolved by the credential, its readiness and any blockers.

Use typed request and response variants

Requests and responses identify their variants with literal fields. Send the kind required by a write, then check the response kind before using the fields for that variant. For example, save_ask creates a new ask with kind: 'create', while a campaign search returns a campaign page when objects.kind is "campaign":

4. Preview, then confirm a launch

Use a new idempotency key for each distinct write. Keep the same key only when retrying the exact same request after its result is uncertain. A launch request without confirmLaunch previews the draft campaign. Inspect that response and only then make a separate confirmed request.
confirmLaunch: true can activate the campaign’s staged media buys. Do not put the confirmation call on an automatic retry path. The current SDK makes zero automatic retries and sends the key you supply unchanged.

5. Read delivery

Use getDelivery with the campaign and a reporting window. The result is a page, not a fixed snapshot: preserve the same query when following a cursor.
The complete runnable examples live in each package: examples/first-value.ts and examples/first_value.py. They make the launch confirmation opt-in with APOSTRA_CONFIRM_LAUNCH=true so the default synthetic-seller run stops after the preview. For transport error and retry behaviour, use the SDK guide.