POST `/api/v1/pipeline/runs`

Interpret a request in plain English (stage 0; the AI may be used).

Scope pipeline:write
Idempotency-Key
operationId pipelineStart

Starts an Intent Pipeline request: the text is interpreted (by the AI, or the built-in parser when the AI is off) into a structured intent: the action, the accounts, the changes and constraints. Nothing else happens yet; check the intent, then run the stages. "run": true interprets and runs stages 1 to 3 in one call. Every AI interpretation is in the AI log.

The token needs the scope pipeline:write, and the person or service account behind it needs the matching privileges and account permissions, exactly as on the screens. See Scopes.

Idempotency-Key. Send a unique Idempotency-Key (up to 255 characters, e.g. a UUID) with every POST. Retrying with the same key and body replays the first answer for 24 hours, so a timeout never creates a second order; the same key with a different body is refused (idempotency_key_reused).

Request

POST /api/v1/pipeline/runs

Headers

Header	Required	Value
`Authorization`	yes	`Bearer <token>`: an OAuth access token (`vat_…`) or a personal access token (`vpt_…`). Get a token
`Idempotency-Key`	yes	A unique string up to 255 characters (a UUID). Idempotency
`Content-Type`	yes	`application/json`

Body: `PipelineIn`

Field	Type	Required	Description
`text`	string	yes	The request in plain English.
`run`	boolean	no	true: run every stage now (stops before creating orders).

Decimals (money, prices, quantities, percentages) are sent as strings, ids as strings, times as ISO 8601 UTC.

Examples

Keep the token in an environment variable (VESTORIS_TOKEN), never in the script.

curl

curl -X POST "https://vestoris.com/api/v1/pipeline/runs" \
  -H "Authorization: Bearer $VESTORIS_TOKEN" \
  -H 'Idempotency-Key: 7f9c2b1e-4d0a-4a7e-9a51-3c2f0b8d6e11' \
  -H "Content-Type: application/json" \
  -d '{"text":"Rebalance growth accounts without realizing gains over $25k","run":false}'

Python (requests)

import os, requests

r = requests.post(
    "https://vestoris.com/api/v1/pipeline/runs",
    headers={
        "Authorization": f"Bearer {os.environ['VESTORIS_TOKEN']}",
        "Idempotency-Key": "7f9c2b1e-4d0a-4a7e-9a51-3c2f0b8d6e11",
    },
    json={
        "text": "Rebalance growth accounts without realizing gains over $25k",
        "run": False
    },
    timeout=30,
)
r.raise_for_status()  # errors are application/problem+json with a stable "code"
print(r.json())

JavaScript (fetch)

const res = await fetch("https://vestoris.com/api/v1/pipeline/runs", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.VESTORIS_TOKEN}`,
    "Idempotency-Key": "7f9c2b1e-4d0a-4a7e-9a51-3c2f0b8d6e11",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
      "text": "Rebalance growth accounts without realizing gains over $25k",
      "run": false
  }),
});
const data = await res.json();
if (!res.ok) throw new Error(`${data.code}: ${data.detail}`); // problem+json
console.log(data);

Response

201 Created, application/json: PipelineRun. Rate-limit headers: RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset.

Response fields

Field	Type	Description
`id`	id (string)	The record's id (a string of digits).
`request`	string	The request in the user's words.
`status`	string	interpreted, checked, orders_created, failed or cancelled.
`interpreted_by_ai`	boolean	True when the AI interpreted the text; false when the built-in parser did.
`intent`	any	The structured intent the request was interpreted as (accounts, changes, constraints).
`stages`	any	Each stage (interpret, entitlements, proposal, compliance, orders) with its outcome.
`created_at`	date-time or null	When it was created.
`updated_at`	date-time or null	When it last changed.
`note`	string	A reminder that nothing is executed by the pipeline.

Example response

HTTP/1.1 201 Created
Content-Type: application/json

{
    "id": "27",
    "request": "Rebalance growth accounts without realizing gains over $25k",
    "status": "interpreted",
    "interpreted_by_ai": true,
    "intent": {
        "action": "rebalance",
        "accounts": [
            "tag:growth"
        ],
        "constraints": {
            "max_realized_gain": "25000"
        }
    },
    "stages": [
        {
            "stage": "interpret",
            "ok": true,
            "summary": "Rebalance 2 growth accounts to their model; realized gains at most $25,000"
        }
    ],
    "created_at": "2026-10-27T14:30:00Z",
    "updated_at": "2026-10-27T14:30:00Z",
    "note": "Nothing is executed: run the stages, create orders, then release them."
}

Example values. Your values depend on your firm's data; prices, orders and fills are simulated.

Status codes and errors

Errors are application/problem+json (RFC 9457) with a stable code to program against; the detail says what to fix. See Errors.

Status	When	Problem codes
201	Created
200 / 201	The same Idempotency-Key again: the first answer is replayed (24 hours)
400	The request is malformed	`invalid_request` `invalid_json`
401	No token, or it is invalid or expired	`invalid_token`
403	The token lacks the scope, or the person or service account behind it lacks the privilege or account permission	`insufficient_scope` `forbidden` `ip_not_allowed`
409	Not possible in the current state	`invalid_transition` `conflict` `idempotency_in_progress`
422	Validation failed (the detail says which field), or blocked	`validation_failed` `idempotency_key_reused`
428	A required header is missing	`idempotency_key_required`
429	Rate limited: wait for Retry-After seconds	`rate_limited`

{
    "type": "https://vestoris.com/developers/errors#validation_failed",
    "title": "Validation failed",
    "status": 422,
    "detail": "Quantity must be greater than zero.",
    "code": "validation_failed",
    "instance": "/api/v1/pipeline/runs"
}

On the screens

The same thing in the app is explained in:

The Intent Pipeline

POST /api/v1/pipeline/runs