POST `/api/v1/commands/{screen}`

Plan a natural-language command and preview it (screen: portfolio, blotter, monitor, wfrules); nothing runs.

Scope ai:use
Idempotency-Key
operationId aiPlan

The token needs the scope ai:use, 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/commands/{screen}

Path parameters

Name	Description	Example
`screen`	portfolio, blotter, monitor or wfrules.	`blotter`

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

Field	Type	Required	Description
`text`	string	yes	The command in plain English.
`answer_to`	any	no	The id of the command whose clarifying question you are answering.

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/commands/blotter" \
  -H "Authorization: Bearer $VESTORIS_TOKEN" \
  -H 'Idempotency-Key: 7f9c2b1e-4d0a-4a7e-9a51-3c2f0b8d6e11' \
  -H "Content-Type: application/json" \
  -d '{"text":"Cancel all my unfilled AAPL buys"}'

Python (requests)

import os, requests

r = requests.post(
    "https://vestoris.com/api/v1/commands/blotter",
    headers={
        "Authorization": f"Bearer {os.environ['VESTORIS_TOKEN']}",
        "Idempotency-Key": "7f9c2b1e-4d0a-4a7e-9a51-3c2f0b8d6e11",
    },
    json={
        "text": "Cancel all my unfilled AAPL buys"
    },
    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/commands/blotter", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.VESTORIS_TOKEN}`,
    "Idempotency-Key": "7f9c2b1e-4d0a-4a7e-9a51-3c2f0b8d6e11",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
      "text": "Cancel all my unfilled AAPL buys"
  }),
});
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: Command. 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).
`screen`	string	The screen the command is for: portfolio, blotter, monitor or wfrules.
`text`	string	The command in the user's words.
`status`	string	planned, question, previewed, executed, cancelled, stale or failed.
`planned_by_ai`	boolean	Planned by ai.
`question`	string or null	A clarifying question, when something material is ambiguous.
`message`	string	What Vestoris says about the plan.
`plan`	object	The typed actions the command was planned as.
`preview`	object or null	What would happen: each item before and after, what is left out and why.
`item_count`	integer	How many items the plan touches.
`confirm_token`	string or null	Send this in X-Vestoris-Confirm to confirm exactly what was previewed.
`typed_confirmation`	string or null	Text to send as "typed" for large or destructive plans.
`results`	list	Each item's result.
`created_at`	date-time or null	When it was created.
`previewed_at`	date-time or null	When the preview was made.
`executed_at`	date-time or null	When the plan was executed.

Example response

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

{
    "id": "55",
    "screen": "blotter",
    "text": "Cancel all my unfilled AAPL buys",
    "status": "previewed",
    "planned_by_ai": true,
    "question": null,
    "message": "3 orders would be cancelled; 1 is left out (already filled).",
    "plan": {
        "actions": [
            {
                "type": "cancel_orders",
                "filter": {
                    "side": "buy",
                    "symbols": [
                        "AAPL"
                    ],
                    "mine": true
                }
            }
        ]
    },
    "preview": null,
    "item_count": 3,
    "confirm_token": "vcf_c41e…",
    "typed_confirmation": "CONFIRM 3",
    "results": [],
    "created_at": "2026-10-27T14:30:00Z",
    "previewed_at": null,
    "executed_at": null
}

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`
404	Not found, or not visible to you (the API never confirms what you may not see)	`not_found`
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/commands/blotter"
}

On the screens

The same thing in the app is explained in:

POST /api/v1/commands/{screen}