API guide and reference

How to read this reference

Each endpoint page has: what it does and who may call it (the scope, plus the privileges and account permissions of the person or service account behind the token); its path and query parameters and headers; the request body fields with their types; the response fields; the status codes and the stable problem codes of its errors; notes on idempotency, ETags, confirmations and jobs; and examples in curl, Python (requests) and JavaScript (fetch) with an example response. Each group page explains its objects, their life cycles and the usual call sequences.

Get a token

Every call is made as someone. For your own scripts, create a personal access token on My API access (vpt_…). For a system, an Admin creates a service account and you use the client credentials grant:

curl -X POST https://vestoris.com/oauth/token \
  -u "$CLIENT_ID:$CLIENT_SECRET" \
  -d grant_type=client_credentials \
  -d scope="portfolio:read orders:read orders:write"
# {"access_token":"vat_…","token_type":"Bearer","expires_in":3600,"scope":"portfolio:read orders:read orders:write"}

import os, requests
tok = requests.post("https://vestoris.com/oauth/token",
    auth=(os.environ["CLIENT_ID"], os.environ["CLIENT_SECRET"]),
    data={"grant_type": "client_credentials", "scope": "portfolio:read orders:read"}, timeout=30).json()["access_token"]

Apps acting for people use the authorization code flow with PKCE. Details: Authentication and Scopes.

The main flows

Conventions in one paragraph

JSON over HTTPS. Ids are strings; money, prices and quantities are decimal strings; times are ISO 8601 UTC. Lists are cursor-paginated (limit, cursor, next_cursor, has_more). Every POST needs an Idempotency-Key. Updates need If-Match with the ETag of a GET. Errors are application/problem+json with a stable code. Long operations answer 202 with a job. Rate limits are in RateLimit-* headers. See Conventions and Errors.