Skip to content

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
}