SDK (TypeScript)

The REST API with the typing done for you. Node 18+, ESM and CommonJS, browsers and edge runtimes with a global fetch.

Install

npm install @prompteryx/sdk
# optional peers for the copilot and cloud-browser examples
npm install zod playwright-core

Create a client

import { Prompteryx } from '@prompteryx/sdk'

const px = new Prompteryx({
  apiKey: process.env.PROMPTERYX_API_KEY!,                    // px_live_… from Cloud Platform → APIs & Webhooks → API Keys
  cloudBrowserKey: process.env.PROMPTERYX_CLOUD_BROWSER_KEY,  // pcb_live_… only for px.cloudBrowser.*
})

What is on the client

Each maps to a journey page with full examples.

px.autopilot	run(), stop(): the AI browser agent
px.copilot	do(page, step), read(page, schema), scan(page, area): AI help while you drive Playwright
px.cloudBrowser.sessions	create(), get(), list(), close(): stealth Chrome in the cloud (needs pcb_live_ key)
px.cloudBrowser	fetch(), search(): one-shot page fetch and web search without managing a session
px.workflows	list(), get(), create(), update(), delete(), run(), runAndWait()
px.executions	get(), wait(), logs(), stream(), getNodeOutput()
px.schedules	list(), get(), create(), update(), delete()
px.connectHub	listApps(), listActions(), getAction(), listAccounts(), run()
px.profiles	list(), create(): Chrome profiles
px.subscription	get(): plan, remaining balances, top-ups
verifyWebhookSignature()	check the signature on a completion callback (also constructWebhookEvent())

Errors are typed

import { AuthError, QuotaError, RateLimitError, NotFoundError } from '@prompteryx/sdk'

try {
  await px.workflows.runAndWait('wf_…', { input: { postcode: 'SW1A 1AA' } })
} catch (err) {
  if (err instanceof QuotaError) console.log('Top up or upgrade:', err.message)          // 402
  else if (err instanceof RateLimitError) {                                              // 429
    // err.code: RATE_LIMIT_EXCEEDED (60/min, 10,000/day per key) or
    // QUOTA_EXHAUSTED / QUOTA_EXCEEDED (a monthly or daily allowance is used up)
    console.log(err.code, 'retry after', err.retryAfterSeconds, 's')
  }
  else if (err instanceof AuthError) console.log('Bad or expired key')                   // 401 / 403
  else throw err
}

GET requests retry twice on network errors, 5xx responses and RATE_LIMIT_EXCEEDED (honouring Retry-After); used-up allowances are not retried. Every method returns the payload directly, with the API's { success, data } envelope removed and execution statuses lower-cased (completed, failed, …).

Versions

0.5.0: fixes autopilot.run() (0.4.1 and 0.4.2 returned before the agent ran), workflows.runAndWait() and executions.wait() (never saw the run finish), workflows.run() options and workflows.list({ search }); adds workflows.create/update/delete and webhook signature helpers; removes profiles.get/delete, which had no API behind them. Upgrade from any 0.4.x.

Models: AUTOPILOT_MODELS lists every id autopilot.run({ model }) accepts; the default is gemini-3.5-flash. claude-sonnet-5-vision was renamed claude-sonnet-5-5-vision on 30 Sep 2026. The old id still runs (as Sonnet 5.5), but use the new one.

Prefer a terminal? The CLI wraps this SDK.