POST `/api/v1/workflow/rules`

Draft a rule from a structure, or from a sentence ("text"); replayed on the test bench.

Scope workflow:rules:write
Idempotency-Key
operationId workflowDraft

The token needs the scope workflow:rules: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/workflow/rules

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: `WorkflowRuleIn`

Field	Type	Required	Description
`text`	string	no	A sentence to draft the rule from (instead of conditions and actions).
`name`	string	no	The rule's name.
`item_type`	string	no	The kind of item it routes.
`priority`	integer	no	Evaluation order (lower first).
`conditions`	object	no	When the rule applies: "all" conditions must hold and at least one "any" condition.
`actions`	list	no	What the rule does when its conditions hold (approvals, queue, assignment, priority, SLA, notifications).
`change_of`	any	no	To change an active rule: the id of the version you are replacing (a new version is drafted).

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/workflow/rules" \
  -H "Authorization: Bearer $VESTORIS_TOKEN" \
  -H 'Idempotency-Key: 7f9c2b1e-4d0a-4a7e-9a51-3c2f0b8d6e11' \
  -H "Content-Type: application/json" \
  -d '{"text":"Orders over $1M in the Growth accounts need PM and Compliance approval, and must be released within 30 minutes."}'

Python (requests)

import os, requests

r = requests.post(
    "https://vestoris.com/api/v1/workflow/rules",
    headers={
        "Authorization": f"Bearer {os.environ['VESTORIS_TOKEN']}",
        "Idempotency-Key": "7f9c2b1e-4d0a-4a7e-9a51-3c2f0b8d6e11",
    },
    json={
        "text": "Orders over $1M in the Growth accounts need PM and Compliance approval, and must be released within 30 minutes."
    },
    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/workflow/rules", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.VESTORIS_TOKEN}`,
    "Idempotency-Key": "7f9c2b1e-4d0a-4a7e-9a51-3c2f0b8d6e11",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
      "text": "Orders over $1M in the Growth accounts need PM and Compliance approval, and must be released within 30 minutes."
  }),
});
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: WorkflowRule. 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).
`lineage_id`	id (string)	The id shared by every version of the rule.
`version`	integer	Version number.
`name`	string	The rule's name.
`item_type`	string	The kind of item: order, override, rule, violation, batch, feed_run, access_review, exception.
`priority`	integer	1 (urgent) to 4 (low); for rules, lower numbers are evaluated first.
`status`	string	draft, pending, active, superseded, retired or rejected.
`state`	string	How the rule stands now (in force, scheduled, waiting for sign-off…).
`is_default`	boolean	True for the default rules that reproduce the firm thresholds.
`conditions`	any	When the rule applies: "all" conditions must hold and at least one "any" condition.
`actions`	list	What the rule does when its conditions hold (approvals, queue, assignment, priority, SLA, notifications).
`restatement`	string	What the engine will enforce, written by code from the structured definition.
`source_text`	string	The words the rule was written from.
`drafted_by_ai`	boolean	True when the AI drafted it (a person still checks and signs).
`pending_action`	string or null	What is waiting for sign-off: "activate", "change" or "retire".
`weakens`	boolean	True when the change weakens an approval (then Compliance must also sign).
`weakens_why`	string	Why it counts as weakening.
`signoffs`	object	Who has signed off so far.
`signoffs.admin`	id (string) or null	The Admin who signed off (id), or null.
`signoffs.compliance`	id (string) or null	The results of the compliance checks (rule, outcome, measured value, limit).
`test_bench`	object or null	The latest test-bench result: what the rule would have blocked, warned on or logged.
`effective_from`	date-time or null	When this version took (or takes) effect.
`effective_to`	date-time or null	When this version stopped being in force (null: still in force).
`created_by`	id (string) or null	The user who created it.
`created_at`	date-time or null	When it was created.
`done`	boolean	Whether every required sign-off is in.
`still_needed`	list of string	Sign-offs still needed.

Example response

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

{
    "id": "1042",
    "lineage_id": "41",
    "version": 1,
    "name": "Large Growth orders",
    "item_type": "order",
    "priority": 2,
    "status": "active",
    "state": "in force",
    "is_default": false,
    "conditions": {
        "all": [
            {
                "field": "notional",
                "op": ">",
                "value": 1000000
            }
        ],
        "any": []
    },
    "actions": [
        {
            "type": "require_approval",
            "roles": [
                "portfolio_manager",
                "compliance_officer"
            ],
            "count": 2
        }
    ],
    "restatement": "Block any order that would make one issuer more than 5.00% of a Growth account (ETFs excepted).",
    "source_text": "",
    "drafted_by_ai": false,
    "pending_action": "",
    "weakens": false,
    "weakens_why": "",
    "signoffs": {
        "admin": null,
        "compliance": []
    },
    "test_bench": null,
    "effective_from": null,
    "effective_to": null,
    "created_by": "7",
    "created_at": "2026-10-27T14:30:00Z",
    "done": false,
    "still_needed": [
        "compliance"
    ]
}

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/workflow/rules"
}

On the screens

The same thing in the app is explained in:

POST /api/v1/workflow/rules