GET `/api/v1/firm`

The firm and its settings.

Scope firm:read
ETag
operationId adminFirm

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

ETag. The answer carries an ETag header. Keep it: changing this resource needs If-Match with that value.

Request

GET /api/v1/firm

Headers

Header	Required	Value
`Authorization`	yes	`Bearer <token>`: an OAuth access token (`vat_…`) or a personal access token (`vpt_…`). Get a token

Examples

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

curl

curl "https://vestoris.com/api/v1/firm" \
  -H "Authorization: Bearer $VESTORIS_TOKEN"

Python (requests)

import os, requests

r = requests.get(
    "https://vestoris.com/api/v1/firm",
    headers={
        "Authorization": f"Bearer {os.environ['VESTORIS_TOKEN']}",
    },
    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/firm", {
  method: "GET",
  headers: {
    Authorization: `Bearer ${process.env.VESTORIS_TOKEN}`,
  },
});
const data = await res.json();
if (!res.ok) throw new Error(`${data.code}: ${data.detail}`); // problem+json
console.log(data);

Response

200 OK, application/json: Firm. With an ETag header. 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).
`name`	string	The firm's name.
`code`	string	The firm's code (used in sign-in links and feed file names).
`demo`	boolean	Demo.
`status`	string	active or suspended.
`settings`	object	Firm settings.
`settings.approval_order_value`	decimal string or null	Orders above this value need an approver (null: no threshold).
`settings.approval_pct_of_account`	decimal string or null	Orders whose part in one account is above this percent of the account need an approver.
`settings.ai_enabled`	boolean	Whether the firm uses the AI at all (off: every feature falls back to deterministic text).
`settings.ai_retention_days`	integer	How long AI interaction records are kept, in days.
`settings.wash_window_days`	integer	Wash-trade window, in days.
`settings.spoof_cancel_minutes`	integer	Spoofing detector: cancelled within this many minutes.
`settings.spoof_min_value`	decimal string or null	Spoofing detector: minimum order value.
`settings.stuck_minutes`	integer	An order with no progress for this long is "stuck".
`settings.override_approval_value`	decimal string or null	Overrides above this order value also need Compliance.
`settings.single_co_approval`	boolean	Whether a lone Compliance user may sign off their own rules (marked in the register).
`settings.legacy_keys_enabled`	boolean	Whether legacy data API keys still work.
`settings.api_max_access_ttl`	integer	The longest life of an access token, in seconds.
`settings.api_max_refresh_days`	integer	The longest life of a refresh token, in days.
`settings.api_rate_per_minute`	integer	Requests per minute allowed per token.

Example response

HTTP/1.1 200 OK
Content-Type: application/json
ETag: "3f1a9c0e5b7d2a4c8e6f0b1d3a5c7e9f"

{
    "id": "1042",
    "name": "Example RIA",
    "code": "ACME",
    "demo": true,
    "status": "active",
    "settings": {
        "approval_order_value": "1000000.00",
        "approval_pct_of_account": "5.00",
        "ai_enabled": true,
        "ai_retention_days": 2555,
        "wash_window_days": 5,
        "spoof_cancel_minutes": 5,
        "spoof_min_value": "500000.00",
        "stuck_minutes": 30,
        "override_approval_value": "250000.00",
        "single_co_approval": false,
        "legacy_keys_enabled": true,
        "api_max_access_ttl": 3600,
        "api_max_refresh_days": 30,
        "api_rate_per_minute": 600
    }
}

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
200	Success
400	The request is malformed	`invalid_request`
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`
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/firm"
}

On the screens

The same thing in the app is explained in:

Firm settings