Execute a saved workflow

/v1/workflows/{id}/execute

Headers: every response carries x-request-id (quote it in support requests). Send x-trace-id (optional, a UUID) to correlate this call across planes; reusing an id that already ran answers 409 duplicate_execution_id. Pick the body format with format or Accept (application/json, text/yaml, text/markdown, text/plain).

Authorization: send Authorization: Bearer $PLUNGE_API_KEY; X-API-Key: <ozk_ key> is accepted as an alternative.

Authorizations

Authorizationstringheaderrequired

Bearer token: Authorization: Bearer ozk_…. ozk_ platform API key (Authorization: Bearer ozk_…)

Path parameters

idstringrequired

Body

application/json

inputstring

inputsobject

user_contextUserContext · object

The caller's time zone, locale and location. Optional on every execute body; when absent the gateway derives it from the request's network location (time zone, approximate place). The agent uses it for local time and as the default schedule time zone.

Show child attributes

time_zonestring

IANA zone

Example: "America/Los_Angeles"

localestring

BCP-47 tag

Example: "en-US"

placestring

Example: "San Francisco, California, US"

latitudenumber

Example: 37.7749

longitudenumber

Example: -122.4194

accuracy_mnumber

metres; only with a device GPS fix

Example: 35

sourceenum<string>required

Available options: device, network

Example: "device"

formatenum<string>

Response format override (precedence: this field → Accept header → mirror of the request Content-Type). Default json. yaml = the envelope with Markdown as block scalars; markdown = the same result the MCP plane renders; text = the bare result content. An unknown value → 400 invalid_format.

Available options: json, yaml, markdown, text

Response

Engine acknowledgement Response format negotiates via the format field, an Accept header (application/json, text/yaml, text/markdown, text/plain), or the request Content-Type mirror; default JSON.

application/json
text/yaml
text/markdown
text/plain

Response headers

x-request-idstringfrom code

Server-minted request id.

X-Execution-Idstringfrom code

The execution this call opened.

successboolean

workflow_idstring

final_task_idstring

request_idstring

contentstring

the final task's stored content, present once the sync run has stored it

invalid_json / invalid_yaml / invalid_body — unreadable body; invalid_format — format must be one of json, yaml, markdown, text

application/json

errorobjectrequired

Show child attributes

codestringrequired

messagestringrequired

connectobject

On a 424 connection_required / credential_required: where the missing connection is made.

Show child attributes

providerstring

methodenum<string>

Available options: oauth, api_key, wallet

linkstring

Example: "POST /v1/connections/stripe/link"

unauthorized — missing, invalid or revoked ozk_ key

Error code: unauthorizedfrom code

application/json

errorobjectrequired

Show child attributes

codestringrequired

messagestringrequired

connectobject

On a 424 connection_required / credential_required: where the missing connection is made.

Show child attributes

providerstring

methodenum<string>

Available options: oauth, api_key, wallet

linkstring

Example: "POST /v1/connections/stripe/link"

workflow_not_found — no saved workflow with that id for this key; unknown_agent — the saved workflow names an agent the registry does not know (refused pre-dispatch); not_found — no route for this method on this path: every other method answers it

application/json

errorobjectrequired

Show child attributes

codestringrequired

messagestringrequired

connectobject

On a 424 connection_required / credential_required: where the missing connection is made.

Show child attributes

providerstring

methodenum<string>

Available options: oauth, api_key, wallet

linkstring

Example: "POST /v1/connections/stripe/link"

duplicate_execution_id — x-trace-id already used by an earlier run — send a fresh UUID; not_executable — the id names a saved campus or building document, which is compiled by POST /v1/companies/{campus}/apply, never executed

application/json

errorobjectrequired

Show child attributes

codestringrequired

messagestringrequired

connectobject

On a 424 connection_required / credential_required: where the missing connection is made.

Show child attributes

providerstring

methodenum<string>

Available options: oauth, api_key, wallet

linkstring

Example: "POST /v1/connections/stripe/link"

payload_too_large — body over 1 MiB (MAX_REQUEST_SIZE)

application/json

errorobjectrequired

Show child attributes

codestringrequired

messagestringrequired

connectobject

On a 424 connection_required / credential_required: where the missing connection is made.

Show child attributes

providerstring

methodenum<string>

Available options: oauth, api_key, wallet

linkstring

Example: "POST /v1/connections/stripe/link"

rate_limited — Retry-After header

application/json

errorobjectrequired

Show child attributes

codestringrequired

messagestringrequired

connectobject

On a 424 connection_required / credential_required: where the missing connection is made.

Show child attributes

providerstring

methodenum<string>

Available options: oauth, api_key, wallet

linkstring

Example: "POST /v1/connections/stripe/link"

engine_error

application/json

errorobjectrequired

Show child attributes

codestringrequired

messagestringrequired

connectobject

On a 424 connection_required / credential_required: where the missing connection is made.

Show child attributes

providerstring

methodenum<string>

Available options: oauth, api_key, wallet

linkstring

Example: "POST /v1/connections/stripe/link"

import os import requests response = requests.post( "https://api.plungeai.com/v1/workflows/{id}/execute", headers={"Authorization": f"Bearer {os.environ['PLUNGE_API_KEY']}"}, json={}, ) if not response.ok: raise SystemExit(f"{response.status_code} {response.headers.get('X-Error-Code')}") print(response.json())

const response = await fetch('https://api.plungeai.com/v1/workflows/{id}/execute', { method: 'POST', headers: { Authorization: `Bearer ${process.env.PLUNGE_API_KEY}`, 'Content-Type': 'application/json', }, body: JSON.stringify({}), }) if (!response.ok) throw new Error(`${response.status} ${response.headers.get('X-Error-Code')}`) console.log(await response.json())

import java.net.URI; import java.net.http.HttpClient; import java.net.http.HttpRequest; import java.net.http.HttpResponse; public class Main { public static void main(String[] args) throws Exception { HttpClient client = HttpClient.newHttpClient(); HttpRequest request = HttpRequest.newBuilder() .uri(URI.create("https://api.plungeai.com/v1/workflows/{id}/execute")) .header("Authorization", "Bearer " + System.getenv("PLUNGE_API_KEY")) .header("Content-Type", "application/json") .POST(HttpRequest.BodyPublishers.ofString("{}")) .build(); HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString()); if (response.statusCode() >= 400) { System.out.println(response.statusCode() + " " + response.headers().firstValue("X-Error-Code").orElse("")); return; } System.out.println(response.body()); } }