REST API Reference
Programmatically execute and manage your automation workflows via REST API
- Create an API Key — Go to API Keys and create a new key.
- Copy your key — It will only be shown once. Store it securely.
- Make your first request:
curl -X POST https://www.prompteryx.ai/api/v1/workflows/YOUR_WORKFLOW_ID/execute \ -H "Authorization: Bearer px_live_YOUR_API_KEY" \ -H "Content-Type: application/json"
Base URL: https://www.prompteryx.ai/api/v1
See Authentication for full details on API key usage and rate limits.
/api/v1/workflowsList your workflowsQuery Parameters
limit Results per page (default 50, max 100)offset Results to skip (default 0)search Filter by name or descriptionsort name, createdAt, updatedAt (default updatedAt)order asc or desc (default desc)Returns { workflows: [...], pagination: { total, limit, offset, hasMore } }.
/api/v1/workflows/:idOne workflow with its nodes, edges and variables (data.workflow)/api/v1/workflowsCreate a linear workflow: { name, description?, nodes: [{ type, label?, params? }] } (201, data.workflowId)/api/v1/workflows/:id/nodesAppend a step: { nodeType, label, params?, afterNodeId? }/api/v1/workflows/:idUpdate name, description, nodes, edges, variables or isActive/api/v1/workflows/:idDelete the workflow and its schedulesNode types come from GET /api/v1/node-configs. Open an API-created workflow in Visual Studio to add branches.
/api/v1/workflows/:id/executeExecute a workflow/api/v1/executions/:idGet execution status/api/v1/executions/:id/logsGet execution logs/api/v1/executions/:id/logs/streamServer-Sent Events: log events, then one done with the final status/api/v1/executions/:id/nodes/:nodeId/outputGet a single node's output (full object or one field)What execute returns (202)
{
"success": true,
"data": {
"execution": {
"id": "api_1790909291145_o3dbvg",
"workflowId": "0QDHW2HTH3zRjHOtybJz",
"status": "pending",
"options": { "runMode": "headless", "videoRecording": false, "timeout": 300000 },
"createdAt": "2026-10-02T02:48:11.145Z",
"statusUrl": "https://www.prompteryx.ai/api/v1/executions/api_1790909291145_o3dbvg",
"logsUrl": "https://www.prompteryx.ai/api/v1/executions/api_1790909291145_o3dbvg/logs"
},
"message": "Workflow execution queued. Poll the statusUrl to check progress."
}
}Runs are queued and picked up by the server runner, usually within a minute. Poll the statusUrl: the status goes pending → running → COMPLETED, FAILED or STOPPED. Compare it case-insensitively; the SDK lower-cases it for you.
Execute with Variables & Options
POST /api/v1/workflows/:id/execute
Content-Type: application/json
{
"variables": {
"email": "user@example.com",
"searchQuery": "automation tools"
},
"webhookUrl": "https://your-server.com/callback",
"options": {
"chromeProfile": "profile-id",
"runMode": "visible",
"videoRecording": true,
"timeout": 300000
}
}Get full execution with per-node outputs
GET /api/v1/executions/:id Authorization: Bearer YOUR_API_KEY
The outputs map gives you each node's output keyed by its name (e.g. "Extract Price").nodeResults has the same data plus nodeId, nodeType, timing, and outputAll for nodes that emit multiple rows (table scrapes, list extractions).
Get a single node's output (or one field)
GET /api/v1/executions/:id/nodes/:nodeId/output GET /api/v1/executions/:id/nodes/:nodeId/output?field=extractedText
Use either the internal nodeId or the human nodeName (URL-encoded — spaces become %20). The ?field= parameter supports dot-path drilldown (e.g. ?field=storedVariables.productPrice) and array indices (?field=items.0.name). On a missing field, the error response lists the available top-level keys.
Built for dashboards. A scheduled workflow extracts a value; your dashboard polls this endpoint after each run to display the latest reading — no need to parse the full execution response.
Execution Options
chromeProfileUse a specific Chrome automation profilerunMode"visible" or "headless" — browser visibilityvideoRecordingEnable video recording of executiontimeoutMax execution time in milliseconds (default 300000, max 600000)viewport{ width, height } for browser stepswebhookUrl gets a signed completion callback; see Webhooks.
{
"success": true,
"data": { "workflows": [ … ], "pagination": { "total": 1, "limit": 50, "offset": 0, "hasMore": false } },
"meta": {
"requestId": "req_abc123",
"timestamp": "2026-10-02T12:00:00Z"
}
}| Code | HTTP Status | Description |
|---|---|---|
MISSING_API_KEY | 401 | No key sent |
INVALID_API_KEY | 401 | Unknown, revoked or malformed key |
API_KEY_EXPIRED | 401 | The key passed its expiry date |
INSUFFICIENT_SCOPE / FORBIDDEN | 403 | Key or OAuth connection lacks the scope (details.requiredScope), or the resource is not yours |
TRIAL_EXPIRED / SUBSCRIPTION_ENDED / PRELAUNCH | 402 | No active plan or trial (chat, apps and media endpoints) |
NOT_FOUND | 404 | Workflow, execution or schedule not found |
MISSING_FIELDS, INVALID_CRON, UNSUPPORTED_MODEL, … | 400 | The request is wrong; the message says how |
RATE_LIMIT_EXCEEDED | 429 | The key's 60/minute or 10,000/day request limit. Retry-After says when to retry. |
QUOTA_EXHAUSTED | 429 / 402 | A plan allowance is used up: 429 for monthly workflow runs (execute and webhook triggers), 402 for AI credits (AI Browser Agent). Top up or wait for the monthly reset; retrying straight away will not help. |
QUOTA_EXCEEDED | 429 / 402 | Connect Hub calls: 429 with Retry-After when the monthly or daily allowance is used, 402 when the plan has none |
INTERNAL_ERROR | 500 | Server error |
SERVICE_UNAVAILABLE | 503 | Temporary; retry with backoff |
Each key allows 60 requests a minute and 10,000 a day. Responses carry the counters:
X-RateLimit-Limit-Minute: 60 X-RateLimit-Remaining-Minute: 57 X-RateLimit-Limit-Day: 10000 X-RateLimit-Remaining-Day: 9843
Over the limit you get 429 RATE_LIMIT_EXCEEDED with Retry-After (seconds until the minute or the UTC day rolls over). Plan allowances (workflow runs, AI credits, cloud minutes, Connect Hub calls) are separate; see the error table above.
| GET /api/v1/schedules?workflowId=&active=true | your schedules |
| POST /api/v1/schedules | { workflowId, cronExpression, timezone?, active?, input?, execution? } |
| GET /api/v1/schedules/:id | one schedule |
| PATCH /api/v1/schedules/:id | change cronExpression, timezone (or cronTimezone), enabled / active, input, execution |
| DELETE /api/v1/schedules/:id | remove it |
Five-field cron, evaluated in the schedule's IANA timezone (default UTC). The shortest interval is 5 minutes (400 INVALID_CRON below that). Timestamps come back as ISO-8601 strings.
| GET /api/v1/auth/validate | who the key belongs to, its scopes, plan and remaining balances |
| GET /api/v1/subscription | { tier, balances: { aiCredits: { remaining, included }, cloudBrowserMinutes, proxyDataMB, captchaSolves, connectHubCalls, monthlyExecutions }, topUpBalances } |
| GET /api/v1/profiles · POST /api/v1/profiles | list Chrome profiles; create a cloud profile { name } |
The AI Browser Agent and the Cloud Browser have their own pages: Run the agent and Cloud browser (separate pcb_live_ key).
| Endpoint | What it returns |
|---|---|
| GET /api/v1/connect-hub/apps?q=&limit=&category= | apps: slug, name, description, iconUrl, categories, authType |
| GET /api/v1/connect-hub/apps/{app}/actions | actions: action key, name, description, parameters |
| GET /api/v1/connect-hub/apps/{app}/actions/{action} | one action with its full parameter schema |
| GET /api/v1/connect-hub/accounts?app= | the caller's connected accounts: id, app, label, addedAt |
| POST /api/v1/connect-hub/run | body { app, action, params, credentialId? }; returns success, data, error, executionMetadata. credentialId can be left out when exactly one account of that app is connected; with several you get 400 ACCOUNT_REQUIRED listing them. |
Errors: 429 QUOTA_EXCEEDED with Retry-After (monthly or daily allowance used up), 402 QUOTA_EXCEEDED (not on the plan), 403 FORBIDDEN (account paused), 404 NOT_FOUND (unknown action), 503 CONNECT_HUB_DISABLED. Worked examples: Use connected apps.
| Endpoint | Scope | What it does |
|---|---|---|
| POST /api/v1/chat | chat | body { message, chat_id?, model?, wait_seconds? }; returns chat_id, job_id, status (done | running), reply, outputs, credits_used, needs_confirmation[] |
| GET /api/v1/jobs/{id} | chat | status and result of a chat turn (or video) that was still running |
| GET /api/v1/models | chat | chat models (id, label, provider) and the default |
| GET /api/v1/chats?limit=&before= | chat | your chats, newest first |
| GET /api/v1/chats/{id}?limit= | chat | one chat's visible messages |
| GET /api/v1/outputs?limit=&chat_id= | chat | files, images, documents and media the assistant made |
| GET /api/v1/apps | apps | every connected app: Prompteryx Connections, Connect Hub accounts, custom connectors |
| POST /api/v1/apps/actions | apps | body { app, intent? }; the app's actions, each read or write |
| POST /api/v1/apps/run | apps | body { app, action, props?, account_id? }; reads return data; writes return status needs_confirmation + confirm_token |
| POST /api/v1/apps/confirm | apps | body { confirm_token }; runs a write the user approved (once; app-action tokens expire after 30 minutes) |
| POST /api/v1/media/{image|video|music|speech|sfx} | media | first call: estimate (AI credits) + confirm_token; second call with confirm_token: runs the quoted model directly and returns url / download_url (valid 24 hours), or a job_id to poll |
| GET /api/v1/explore?tab=&q=&type=&cursor= | explore | public Explore posts (trending by default; q searches) |
Same AI credits, plan limits and trial rules as the web app: an account without an active plan or trial gets 402 with TRIAL_EXPIRED, SUBSCRIPTION_ENDED or PRELAUNCH. Changes outside the chat (send, post, create, delete) never run without a confirm_token sent back by you after the user agreed. Chats started here appear in your chat history labelled “via API”.
Scopes. API keys created from 3 November 2026 only work on the areas ticked when they were made (workflows, executions, browser, integrations, profile, chat, media, apps, explore; send areas when creating a key, default all). Other areas answer 403 INSUFFICIENT_SCOPE. Older keys keep working as before. OAuth connections get the scopes the user allowed on the consent screen.
pxo_…) are accepted everywhere a key is.| GET /.well-known/oauth-authorization-server | server metadata (RFC 8414) |
| GET /.well-known/oauth-protected-resource/api/mcp | resource metadata for the MCP endpoint (RFC 9728) |
| GET /oauth/authorize | consent screen; PKCE S256 required; response_type=code |
| POST /api/oauth/token | authorization_code and refresh_token grants; 1-hour access tokens, 30-day rotating refresh tokens |
| POST /api/oauth/register | dynamic client registration (RFC 7591) for public clients |
| POST /api/oauth/revoke | revoke an access or refresh token |
Clients may identify with a client-ID metadata document (an https URL) or by registering. Loopback redirects (http://127.0.0.1:*/callback) are accepted for CLIs. Scopes: workflows executions browser integrations profile, plus chat media apps explore for the assistant, media and Explore.