Run a Procedure

Endpoint

POST https://run.rapidfolio.com/v1/procedures/:procedureId/:environment

Parameter	Description
:procedureId	The ID of the procedure to run (visible in the dashboard URL and procedure settings)
:environment	sandbox or live — must match the environment of the API key you are using

Headers:

Authorization: Bearer <api_key>
Content-Type: application/json

---

Request Body

{
  "data": {
    "customerId": "cust_123",
    "amount": 5000
  },
  "metadata": {
    "procedureVersion": "v2"
  },
  "control": {
    "executionMode": "async",
    "executionTimeout": 60000
  }
}

Fields

Field	Type	Required	Description
data	object	Yes	Input data passed to the procedure. Must conform to the procedure's defined input schema.
metadata.procedureVersion	string	No	Pin execution to a specific published version (e.g. "v2"). Defaults to the procedure's current published default.
control.executionMode	string	No	"async" or "sync". Defaults to "async". See Async vs Sync below.
control.executionTimeout	number	No	Timeout in milliseconds for sync mode. Range: 1000–300000. Defaults to 60000 (60 seconds).

---

Async vs Sync

Async (default)

The API returns immediately with a 202 Accepted response containing the runId. The procedure executes in the background. Use polling or webhooks to track completion.

Use async when:

• The procedure may take more than a few seconds.
• You are triggering a background job or event-driven workflow.
• You do not need to return the result to your caller in the same request.

Sync

The API holds the connection open until the procedure completes or the executionTimeout is reached, then returns the result inline.

Use sync when:

• You need to return the procedure output directly in an HTTP response to your own users.
• The procedure is fast and you can afford to wait.
• You want a simpler integration without polling.

Set a generous timeout to avoid false 504 responses for procedures that occasionally run longer.

---

Responses

Async — 202 Accepted

Returned immediately when executionMode is "async".

{
  "runId": "run_clxyz123",
  "status": "running",
  "statusUrl": "https://run.rapidfolio.com/runs/run_clxyz123"
}

Poll statusUrl to check for completion. See Manage Runs.

---

Sync — 200 Completed

The procedure finished before the timeout.

{
  "runId": "run_clxyz123",
  "status": "completed",
  "output": {
    "approved": true,
    "transactionId": "txn_abc"
  },
  "completedAt": "2026-02-27T10:00:05.000Z"
}

---

Sync — 200 Awaiting Review

The procedure reached a Human Review node and paused before the timeout expired. The run is not complete — a reviewer must approve or reject it before it continues.

{
  "runId": "run_clxyz123",
  "status": "awaiting_review",
  "statusUrl": "https://run.rapidfolio.com/runs/run_clxyz123"
}

Your caller should treat this as a pending state. Subscribe to the human_review_requested webhook or poll statusUrl to detect when the review is resolved and the run continues.

---

Sync — 504 Timeout

The procedure did not complete before executionTimeout expired. The run is still executing in the background.

{
  "runId": "run_clxyz123",
  "status": "timeout",
  "error": "Execution exceeded timeout of 60000ms",
  "statusUrl": "https://run.rapidfolio.com/runs/run_clxyz123"
}

The run is not cancelled — it continues running. Use statusUrl to poll for the final result. If you consistently hit timeouts, either increase executionTimeout or switch to async mode.

---

Full Example

Async run

curl -X POST https://run.rapidfolio.com/v1/procedures/proc_abc/sandbox \
  -H "Authorization: Bearer rsk_sandbox_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "data": {
      "customerId": "cust_123",
      "amount": 5000
    },
    "control": {
      "executionMode": "async"
    }
  }'

Sync run with version pin

curl -X POST https://run.rapidfolio.com/v1/procedures/proc_abc/sandbox \
  -H "Authorization: Bearer rsk_sandbox_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "data": {
      "customerId": "cust_123",
      "amount": 5000
    },
    "metadata": {
      "procedureVersion": "v2"
    },
    "control": {
      "executionMode": "sync",
      "executionTimeout": 120000
    }
  }'