Build with Voltr

Make your first request

1. Open the developer console and create a developer login, or sign in with your existing login. Developer registration and the simulated sandbox require no Voltr app subscription. An owner or admin workspace is needed to grant access.
2. Create your API account and a test application.
3. Connect a workspace with the minimum scopes you need. Create a key for that grant and save it in your server’s secret store.
4. Call the capability catalog, then search the sandbox pool.

curl https://getvoltr.com/v1/capabilities \
  -H "Authorization: Bearer $VOLTR_API_KEY"

curl https://getvoltr.com/v1/creators/search \
  -H "Authorization: Bearer $VOLTR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: search-demo-0001" \
  -d '{"platform":"tiktok","keyword":"skincare","limit":20}'

Responses use { object, api_version, request_id, workspace_id, data }. Metered results include data.platform_request_id. Test results include simulated: true and provider_calls: 0.

Download the server-side JavaScript client and its TypeScript declarations into the same directory. Use Node.js 22 or later. The client is not yet published to npm. cURL and any HTTP client work without an SDK.

Customer-approved workspace access

An API account owns applications. Each application has a fixed test or live environment. Each customer approves a workspace grant with explicit scopes. Keys are issued against that grant, expire within 30 days, and can be rotated or revoked in the console.

Send your customer the application’s connect URL. Their current workspace owner or admin approves access in Voltr; management keys cannot grant it on their behalf. The grant is invalid if it is revoked, the approver loses their owner/admin membership, the workspace is archived or the account is suspended.

Keep all keys on your backend. Every workspace key is bound to one workspace; supplying a different workspace ID cannot change that binding. voltr_org_* keys manage the partner account and cannot execute workspace capabilities. voltr_sk_api_test_* and voltr_sk_api_live_* execute permitted capabilities.

Live keys require an activated contract. Customer provider connections and applicable workspace entitlements remain required. API access does not automatically connect or authorize TikTok, Meta, Shopify or messaging accounts.

Discover the available surface

GET /v1/capabilities returns only tools available to your key. Its JSON schemas are the input contract. REST and MCP share these tools and scopes.

Creator-pool IDs and workspace creator IDs are different surfaces. To save selected pool creators into a customer’s list, preview create_creator_list with source: "pool" and the exact IDs returned by search. The apply step rechecks those identities and uses the existing list service and workspace capacity limits. Use the command catalog below for new outreach workflows, email campaigns and ads.

Preview, approve, apply

Supported actions: create_creator_list, reply_unread_messages, launch_outreach_workflow, set_campaign_status, decide_sample_request, change_ad_spend and generate_creator_ad_package.

import { Voltr } from './voltr-api.mjs';
const voltr = new Voltr({ apiKey: process.env.VOLTR_API_KEY });
const preview = await voltr.preview('create_creator_list', {
  name: 'Skincare shortlist',
  source: 'pool',
  creator_ids: ['11111111-1111-4111-8111-111111111111']
});

// Show preview.impact to your customer for approval.
const result = await voltr.apply('create_creator_list', {
  previewId: preview.preview_id,
  confirmation: preview.required_confirmation,
  idempotencyKey: 'customer-job-0001'
});
const receipt = await voltr.execution(result.execution_id);

Previews expire after 10 minutes. Persist the idempotency key with your business job before calling apply. The Idempotency-Key header must match the body’s idempotency_key. Reusing it with changed arguments returns 409. An exact successful retry returns the original receipt without executing or billing twice. A key is 12–120 letters, numbers, colons, underscores or dashes.

A timeout or platform_request_pending means the outcome is unconfirmed. Reuse the same key or poll the receipt. Never generate a new key to force an uncertain action through. Background reconciliation uses durable evidence and never reruns the action.

Queued messages and active workflows are accepted work, not proof of delivery. Execution receipts distinguish queue state from a persisted provider message identifier. Ad operations also require provider eligibility and Voltr’s existing ads write gate.

Errors use { error, code, details? }: 400 invalid input, 401 invalid key, 403 insufficient access, 404 missing resource, 409 conflict or unconfirmed work, 413 input larger than 64 KiB, 429 rate/capacity limit, 502 a confirmed operation failure, and 503 unavailable or uncertain outcome. A receipt ID can appear at details.platform_request_id.

Messages, workflows and ads

GET /v1/commands publishes the commands, scopes and exact input schemas available to your key. Preview and apply use the canonical Voltr backend.

// Continue with the list returned by the earlier example.
const review = await voltr.previewCommand('create_workflow', {
  name: 'Creator outreach', message_template: 'Your reviewed message',
  target: { list_id: result.list.id }, status: 'paused'
});
const operation = await voltr.applyCommand('create_workflow', {
  previewId: review.preview_id, confirmation: review.required_confirmation,
  idempotencyKey: 'your-persisted-workflow-job-001'
});
await voltr.subscribe('workflow', operation.agent.id);
const page = await voltr.events({ after: '0', limit: 50 });
// Process and deduplicate events, then persist page.next_cursor.

Use another preview/apply to set_workflow_status or run_workflow. Direct conversation messages use send_outreach_message; poll voltr.operation(id) and the request receipt for delivery state. API workflow audiences require exact saved list IDs.

Email supports provisioning, recipient import, preflight, launch and status changes after secure mailbox setup. TikTok supports GMV Max creation, status changes and creative boosts. Meta supports paused creation, plus separately consented live creation for eligible existing parents through prepare_meta_creator_ads_live and launch_meta_creator_ads_live. New/copied parents and partnership ads remain paused for review in Ads Manager.

Subscribe through POST /v1/subscriptions with {"kind":"conversation","resource_id":"WORKSPACE_RESOURCE_UUID"}. Supported kinds are conversation, workflow, email_campaign, meta_ad_batch and ad_campaign (also requires provider: meta or tiktok). Updates describe stored product/reporting state; retrieve the relevant read for details. An application supports up to 100 active subscriptions. Stop observation with DELETE /v1/subscriptions/SUBSCRIPTION_UUID or voltr.unsubscribe(id); subscribing again resumes the same record. Poll GET /v1/events?after=CURSOR if you do not use webhooks.

Fund backend access with your API plan

After activating an API plan, connect a workspace and choose Fund with API plan in the developer console. A workspace created during API registration needs no separate Voltr app subscription. An existing app workspace keeps its app entitlements.

Plans declare finite workspace, CRM, messaging, ad and email campaign allowances. Request usage and included backend work are separate counters: one bulk request does not grant unlimited downstream messages. Check GET /v1/usage and the console for consumption and reservations. Disabling funding stops new backend work; work already accepted by a provider requires its normal pause or reconciliation flow.

Connect an MCP client with OAuth

Add https://getvoltr.com/mcp to a compatible MCP client and choose OAuth. Sign in, then select the API organization, project and workspace in the consent screen. Approve only the required scopes. API projects use the same account ledger as your software integration. OAuth access tokens expire after an hour and rotate through refresh tokens; rotation preserves receipts and idempotency history.

The authorizing user must administer the workspace grant and have owner, admin or developer access to its API account. OAuth credentials are limited to /mcp; software calling REST uses a separately issued scoped API key. Client-specific connection testing remains part of release acceptance.

Cold Instagram outreach uses the manual copy/open handoff. Automated replies require an eligible inbound conversation and the provider’s messaging window. Provider connections, creator rights, quotas and workspace entitlements still apply.

Test without provider effects

Download the runnable sandbox example beside voltr-api.mjs, set your test key in VOLTR_API_KEY, and run node sandbox.mjs. It searches, saves a shortlist, creates a paused simulated workflow, subscribes to results and reads events. The example refuses live keys.

Test keys use synthetic creators and simulated action receipts. They do not send messages, create live workflows, change ads or call providers. The sandbox exposes a documented subset through capabilities; test fixtures do not model provider delivery. Applications, grants, keys and request/event records are durable.

Test usage is tracked separately and never invoiced. Use a live application with an approved contract for real execution. Signing up does not enable production ad spend or billing collection.

Receive signed request events

Register a public HTTPS endpoint in the console. Save the signing secret when it is shown; it cannot be retrieved later. Events include request.succeeded, request.failed, request.unknown, usage.threshold, and subscribed resource updates such as conversation.updated and workflow.updated. Request completion reports accepted work. Poll execution receipts for subsequent provider delivery evidence.

{
  "id": "event UUID",
  "type": "request.succeeded",
  "created_at": "ISO-8601 timestamp",
  "workspace_id": "workspace UUID",
  "data": {
    "request_id": "request UUID",
    "operation": "search_creator_pool",
    "environment": "test",
    "state": "succeeded",
    "usage_units": 1
  }
}

Read the raw request bytes. The Voltr-Signature header is t=timestamp,v1=hex, where hex is HMAC-SHA256 of timestamp + '.' + rawBody using your signing secret. Compare in constant time and reject timestamps more than five minutes old. Deduplicate by Voltr-Event-ID.

Return 2xx within five seconds. Deliveries may repeat or arrive out of order. Voltr retries up to eight attempts with backoff; inspect failures and request replay in the console. Destinations must resolve to public IPv4 addresses on HTTPS port 443. Redirects and private network destinations are rejected.

Usage limits and charges

One successful pool search uses one creator_search unit; a metered read uses one api_read unit; a successful apply uses one action_execution unit. Previews, receipt/status lookups, capabilities and usage reporting are included. Direct send_outreach_message calls instead use one message_send unit after confirmed provider delivery. Queued messages reserve capacity until reconciliation; failed delivery costs zero. A bulk workflow or campaign is billed for accepted execution, without another API fee for every downstream message.

Reservations are atomic across the account. Uncertain operations retain capacity until reconciled, and failed operations release it. The initial limits are 60 HTTP requests per minute per key, 120 newly metered requests per minute per account, 20 unresolved requests per account and a contract-defined monthly unit cap.

Only resolved, closed live months can be invoiced. The monthly charge is max(monthly minimum, usage at contract rates); drafts and automatic collection have separate release controls. The console shows invoice preparation and verified Stripe payment state, with links to hosted invoices. Select a published plan, accept its rates and complete card setup to activate live access. Plan changes start next month; cancellation ends live access at month end. The full first-month minimum applies. See API pricing.

Automate application management

Use a management key with /v1/platform/{resource} and the header X-Requested-With: XMLHttpRequest. The console uses the same routes with your signed-in session.

Account creation, workspace consent and management-key creation require an interactive signed-in session. Management endpoints return { data }. Lists are bounded in the developer preview; contact Voltr before exceeding 100 applications, 100 grants per application or 500 linked keys.