Operations
The operation catalog (openspec operations): what every operator client offers on the active context to scripts and to its AI assistant. Each client implements every operation listed here; how a client reaches them (script calls, assistant tools, the write gate) is on its own API page: web app, TUI.
A read runs at once; a write changes the platform and asks the user first (admins only). An operation for people only is never offered to scripts or assistants.
The document: https://app.virtufin.com/schemas/operations.v1.json, version 1, 30 operations.
workers
workers.list
read — Every worker of the context: id, name, status, topics, tags, source, config.
No input.
{
"type": "object",
"properties": {},
"additionalProperties": false
}
workers.start
write — Start a worker.
| Field | Type | Required | Notes |
|---|---|---|---|
id |
string | yes | not empty |
{
"type": "object",
"properties": {
"id": {
"type": "string",
"minLength": 1
}
},
"required": [
"id"
],
"additionalProperties": false
}
workers.stop
write — Stop a worker.
| Field | Type | Required | Notes |
|---|---|---|---|
id |
string | yes | not empty |
{
"type": "object",
"properties": {
"id": {
"type": "string",
"minLength": 1
}
},
"required": [
"id"
],
"additionalProperties": false
}
workers.delete
write — Delete a worker (stop it first).
| Field | Type | Required | Notes |
|---|---|---|---|
id |
string | yes | not empty |
{
"type": "object",
"properties": {
"id": {
"type": "string",
"minLength": 1
}
},
"required": [
"id"
],
"additionalProperties": false
}
workers.tag
write — Set a tag on a worker; an empty value removes it.
| Field | Type | Required | Notes |
|---|---|---|---|
id |
string | yes | not empty |
key |
string | yes | not empty |
value |
string | yes |
{
"type": "object",
"properties": {
"id": {
"type": "string",
"minLength": 1
},
"key": {
"type": "string",
"minLength": 1
},
"value": {
"type": "string"
}
},
"required": [
"id",
"key",
"value"
],
"additionalProperties": false
}
workers.create
write — Create a worker from a registry entry (tagged type and source, not started); returns its id.
| Field | Type | Required | Notes |
|---|---|---|---|
entry |
string | yes | not empty |
version |
string | no | |
topics |
array of string | yes | default [] |
config |
object of string | yes | default {} |
secrets |
object of string | yes | default {} |
{
"type": "object",
"properties": {
"entry": {
"type": "string",
"minLength": 1
},
"version": {
"type": "string"
},
"topics": {
"default": [],
"type": "array",
"items": {
"type": "string",
"minLength": 1
}
},
"config": {
"default": {},
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"type": "string"
}
},
"secrets": {
"default": {},
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"type": "string"
}
}
},
"required": [
"entry",
"topics",
"config",
"secrets"
],
"additionalProperties": false
}
workers.upgrade
write — Load another version of a worker's registry package (the latest when none is given).
| Field | Type | Required | Notes |
|---|---|---|---|
id |
string | yes | not empty |
version |
string | no |
{
"type": "object",
"properties": {
"id": {
"type": "string",
"minLength": 1
},
"version": {
"type": "string"
}
},
"required": [
"id"
],
"additionalProperties": false
}
registry
registry.list
read — The worker registry: each entry with its versions and whether the web app can create it.
No input.
{
"type": "object",
"properties": {},
"additionalProperties": false
}
feeds
feeds.list
read — The feed definitions shared on the context, with their topics and problems.
No input.
{
"type": "object",
"properties": {},
"additionalProperties": false
}
feeds.save
write — Save a feed definition (the JSON document of the feed-definition schema) under its name.
| Field | Type | Required | Notes |
|---|---|---|---|
definition |
object of any | yes |
{
"type": "object",
"properties": {
"definition": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {}
}
},
"required": [
"definition"
],
"additionalProperties": false
}
feeds.connect
write — Bring a feed definition's feeds to its topics.
| Field | Type | Required | Notes |
|---|---|---|---|
name |
string | yes | not empty |
{
"type": "object",
"properties": {
"name": {
"type": "string",
"minLength": 1
}
},
"required": [
"name"
],
"additionalProperties": false
}
feeds.disconnect
write — Delete every feed of a feed definition; the number deleted.
| Field | Type | Required | Notes |
|---|---|---|---|
name |
string | yes | not empty |
{
"type": "object",
"properties": {
"name": {
"type": "string",
"minLength": 1
}
},
"required": [
"name"
],
"additionalProperties": false
}
triggers
triggers.list
read — The scheduled triggers.
No input.
{
"type": "object",
"properties": {},
"additionalProperties": false
}
triggers.schedule
write — Schedule a trigger: a cron schedule or a due time (RFC 3339 or a duration), a target topic, repeats (0 indefinitely), a TTL.
| Field | Type | Required | Notes |
|---|---|---|---|
name |
string | yes | not empty |
targetTopic |
string | yes | not empty |
schedule |
string | no | |
dueTime |
string | no | |
repeats |
integer | yes | ≥ 0, default 0 |
ttl |
string | no |
{
"type": "object",
"properties": {
"name": {
"type": "string",
"minLength": 1
},
"targetTopic": {
"type": "string",
"minLength": 1
},
"schedule": {
"type": "string"
},
"dueTime": {
"type": "string"
},
"repeats": {
"default": 0,
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
},
"ttl": {
"type": "string"
}
},
"required": [
"name",
"targetTopic",
"repeats"
],
"additionalProperties": false
}
triggers.delete
write — Delete a trigger.
| Field | Type | Required | Notes |
|---|---|---|---|
name |
string | yes | not empty |
{
"type": "object",
"properties": {
"name": {
"type": "string",
"minLength": 1
}
},
"required": [
"name"
],
"additionalProperties": false
}
scenarios
scenarios.list
read — The scenarios with their status, legs and trading halt.
No input.
{
"type": "object",
"properties": {},
"additionalProperties": false
}
scenarios.add
write — Register a scenario (upper-case id, not LIVE) with market, portfolio and strategy legs.
| Field | Type | Required | Notes |
|---|---|---|---|
id |
string | yes | |
name |
string | no | |
marketWorld |
string | no | |
marketUniverse |
string | no | |
portfolioWorld |
string | no | |
strategyWorld |
string | no | |
strategyId |
string | no |
{
"type": "object",
"properties": {
"id": {
"type": "string"
},
"name": {
"type": "string"
},
"marketWorld": {
"type": "string"
},
"marketUniverse": {
"type": "string"
},
"portfolioWorld": {
"type": "string"
},
"strategyWorld": {
"type": "string"
},
"strategyId": {
"type": "string"
}
},
"required": [
"id"
],
"additionalProperties": false
}
scenarios.setStatus
write — Pause, resume or archive a scenario (not LIVE).
| Field | Type | Required | Notes |
|---|---|---|---|
id |
string | yes | not empty |
status |
"active" | "paused" | "archived" |
yes |
{
"type": "object",
"properties": {
"id": {
"type": "string",
"minLength": 1
},
"status": {
"type": "string",
"enum": [
"active",
"paused",
"archived"
]
}
},
"required": [
"id",
"status"
],
"additionalProperties": false
}
scenarios.halt
write — Halt a scenario's trading: strategies withhold orders, executors refuse them. Open orders stay.
| Field | Type | Required | Notes |
|---|---|---|---|
id |
string | yes | not empty |
reason |
string | yes | default "halted by a script" |
{
"type": "object",
"properties": {
"id": {
"type": "string",
"minLength": 1
},
"reason": {
"default": "halted by a script",
"type": "string"
}
},
"required": [
"id",
"reason"
],
"additionalProperties": false
}
scenarios.resume
write — Resume a halted scenario's trading.
| Field | Type | Required | Notes |
|---|---|---|---|
id |
string | yes | not empty |
reason |
string | yes | default "resumed by a script" |
{
"type": "object",
"properties": {
"id": {
"type": "string",
"minLength": 1
},
"reason": {
"default": "resumed by a script",
"type": "string"
}
},
"required": [
"id",
"reason"
],
"additionalProperties": false
}
scenarios.delete
write — Delete a scenario for good (not LIVE): marked deleted, out of the index, its sc..* state purged. Returns the keys purged.
| Field | Type | Required | Notes |
|---|---|---|---|
id |
string | yes | not empty |
{
"type": "object",
"properties": {
"id": {
"type": "string",
"minLength": 1
}
},
"required": [
"id"
],
"additionalProperties": false
}
killSwitch
killSwitch
write, for people only — Halt every scenario that still trades, then cancel every running executor's open orders; a report per scenario and executor.
No input.
{
"type": "object",
"properties": {},
"additionalProperties": false
}
strategies
strategies.list
read — Atomic strategies (workers tagged type) and composite ones (cfg.strategy.*).
No input.
{
"type": "object",
"properties": {},
"additionalProperties": false
}
strategies.compose
write — Save a composite strategy (upper-case name, at least two known strategies, no cycle).
| Field | Type | Required | Notes |
|---|---|---|---|
name |
string | yes | |
components |
array of string | yes |
{
"type": "object",
"properties": {
"name": {
"type": "string"
},
"components": {
"type": "array",
"items": {
"type": "string"
}
}
},
"required": [
"name",
"components"
],
"additionalProperties": false
}
state
state.get
read — One state entry's value (JSON when it parses) and etag; null when the key does not exist.
| Field | Type | Required | Notes |
|---|---|---|---|
key |
string | yes | not empty |
service |
string | yes | default "statestore" |
{
"type": "object",
"properties": {
"key": {
"type": "string",
"minLength": 1
},
"service": {
"default": "statestore",
"type": "string"
}
},
"required": [
"key",
"service"
],
"additionalProperties": false
}
state.keys
read — The state store's keys, optionally those starting with a prefix.
| Field | Type | Required | Notes |
|---|---|---|---|
prefix |
string | yes | default "" |
service |
string | yes | default "statestore" |
{
"type": "object",
"properties": {
"prefix": {
"default": "",
"type": "string"
},
"service": {
"default": "statestore",
"type": "string"
}
},
"required": [
"prefix",
"service"
],
"additionalProperties": false
}
topics
topics.list
read — The topics the api has seen, optionally those starting with a prefix.
| Field | Type | Required | Notes |
|---|---|---|---|
prefix |
string | yes | default "" |
{
"type": "object",
"properties": {
"prefix": {
"default": "",
"type": "string"
}
},
"required": [
"prefix"
],
"additionalProperties": false
}
topics.read
read — The next events on topics: up to count, waiting at most timeoutMs; each with topic, type, source, time and data.
| Field | Type | Required | Notes |
|---|---|---|---|
topics |
array of string | yes | not empty |
count |
integer | yes | ≥ 1, ≤ 500, default 1 |
timeoutMs |
integer | yes | ≥ 1, ≤ 60000, default 10000 |
{
"type": "object",
"properties": {
"topics": {
"minItems": 1,
"type": "array",
"items": {
"type": "string",
"minLength": 1
}
},
"count": {
"default": 1,
"type": "integer",
"minimum": 1,
"maximum": 500
},
"timeoutMs": {
"default": 10000,
"type": "integer",
"minimum": 1,
"maximum": 60000
}
},
"required": [
"topics",
"count",
"timeoutMs"
],
"additionalProperties": false
}
docs
docs.search
read — Search the Virtufin documentation (every docs site: the platform, its devkits and workers, and both operator clients, TUI and web app, with their APIs): the best matching sections with site, title, link and a snippet.
| Field | Type | Required | Notes |
|---|---|---|---|
query |
string | yes | not empty |
limit |
integer | yes | ≥ 1, ≤ 20, default 8 |
{
"type": "object",
"properties": {
"query": {
"type": "string",
"minLength": 1
},
"limit": {
"default": 8,
"type": "integer",
"minimum": 1,
"maximum": 20
}
},
"required": [
"query",
"limit"
],
"additionalProperties": false
}
docs.read
read — One documentation section's full text, by the link docs.search gave.
| Field | Type | Required | Notes |
|---|---|---|---|
url |
string | yes | not empty |
{
"type": "object",
"properties": {
"url": {
"type": "string",
"minLength": 1
}
},
"required": [
"url"
],
"additionalProperties": false
}