Skip to content

The app's API

The app offers the platform's operation catalog — the same operations every operator client offers, listed on the shared Operations page — and its own small HTTP server, which serves the app, the contexts, sign-in, the AI relay and the change log.

How operations are reached here

An operation has a name (workers.start), a description, an input schema and a kind: read or write. In the app (src/api/catalog.ts, src/api/operation.ts) every operation runs in your browser against the active context, through the same code the views use:

From How
Scripts vf.<group>.<action>(input), e.g. await vf.workers.start({ id }).
The AI assistant Each operation is a tool (workers__start); the model calls it, your browser runs it. Writes are offered to admins only; people-only operations (the kill switch) never.
The views The buttons and dialogs call the same actions.

Every call checks its input against the operation's schema first (problems reported with their paths). A read runs at once. A write runs through the write gate: admins only; on a protected context the user confirms in a dialog; recorded in Changes. The app server enforces the admin rule again on every forwarded call (Architecture).

The catalog document, with each operation's input JSON Schema, is /schemas/operations.v1.json; it is checked against the contract @virtufin/domain-devkit ships, which the TUI implements too.

Schemas

Generated from src/VirtufinApp/public/schemas by npm run schemas; do not edit between the markers.

The navigation structure (openspec navigation-specs): the tree of sections, views and pages. Served at /schemas/navigation.v1.schema.json without sign-in.

The document
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://app.virtufin.com/schemas/navigation.v1.schema.json",
  "type": "object",
  "properties": {
    "$schema": {
      "type": "string"
    },
    "version": {
      "type": "number",
      "const": 1
    },
    "nodes": {
      "$ref": "#/$defs/nodes"
    }
  },
  "required": [
    "version",
    "nodes"
  ],
  "additionalProperties": false,
  "title": "Virtufin navigation structure",
  "description": "What exists and how it is grouped (openspec navigation-specs); never how it is drawn.",
  "$defs": {
    "nodes": {
      "minItems": 1,
      "type": "array",
      "items": {
        "$ref": "#/$defs/node"
      },
      "title": "Sibling nodes"
    },
    "node": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string",
          "pattern": "^(?=.*[a-z])[a-z0-9_]{1,32}$",
          "description": "Unique among its siblings; the node's part of its route."
        },
        "label": {
          "type": "string",
          "minLength": 1,
          "description": "What the client shows."
        },
        "emphasis": {
          "description": "A hint a client may ignore.",
          "type": "string",
          "enum": [
            "primary",
            "secondary"
          ]
        },
        "protected": {
          "description": "An editor may move this node but not remove it, nor a group holding it.",
          "type": "boolean"
        },
        "view": {
          "description": "A View Id; one the client lacks shows a placeholder.",
          "type": "string",
          "pattern": "^(?=.*[a-z])[a-z0-9_]{1,32}$"
        },
        "page": {
          "description": "A page name (page-specs).",
          "type": "string",
          "pattern": "^(?=.*[a-z])[a-z0-9_]{1,32}$"
        },
        "children": {
          "$ref": "#/$defs/nodes"
        }
      },
      "required": [
        "id",
        "label"
      ],
      "additionalProperties": false,
      "title": "Navigation node",
      "oneOf": [
        {
          "required": [
            "view"
          ]
        },
        {
          "required": [
            "page"
          ]
        },
        {
          "required": [
            "children"
          ]
        }
      ]
    }
  }
}

web-app-navigation-profile.v1.schema.json

How this browser draws each level of the structure (tabs, sections, links, nested). Served at /schemas/web-app-navigation-profile.v1.schema.json without sign-in.

The document
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://app.virtufin.com/schemas/web-app-navigation-profile.v1.schema.json",
  "type": "object",
  "properties": {
    "$schema": {
      "type": "string"
    },
    "version": {
      "type": "number",
      "const": 1
    },
    "levels": {
      "anyOf": [
        {
          "type": "array",
          "prefixItems": [
            {
              "type": "string",
              "const": "tabs"
            },
            {
              "type": "string",
              "const": "tabs"
            },
            {
              "type": "string",
              "enum": [
                "sections",
                "links",
                "nested"
              ]
            }
          ],
          "items": {
            "type": "string",
            "enum": [
              "sections",
              "links",
              "nested"
            ]
          },
          "minItems": 3
        },
        {
          "type": "array",
          "prefixItems": [
            {
              "type": "string",
              "const": "tabs"
            },
            {
              "type": "string",
              "enum": [
                "sections",
                "links",
                "nested"
              ]
            }
          ],
          "items": {
            "type": "string",
            "enum": [
              "sections",
              "links",
              "nested"
            ]
          },
          "minItems": 2
        },
        {
          "type": "array",
          "prefixItems": [
            {
              "type": "string",
              "enum": [
                "sections",
                "links",
                "nested"
              ]
            }
          ],
          "items": {
            "type": "string",
            "enum": [
              "sections",
              "links",
              "nested"
            ]
          },
          "minItems": 1
        }
      ],
      "description": "The level kind of each depth; deeper levels use the last."
    }
  },
  "required": [
    "version",
    "levels"
  ],
  "additionalProperties": false,
  "title": "Virtufin web app navigation profile",
  "description": "How the web app draws each level of the navigation structure (openspec web-app, Navigation Representation)."
}

feed-definition.v1.schema.json

A feed definition (Trading › Feeds), shared on the context at cfg.feed.<NAME>. Served at /schemas/feed-definition.v1.schema.json without sign-in.

The document
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://app.virtufin.com/schemas/feed-definition.v1.schema.json",
  "type": "object",
  "properties": {
    "$schema": {
      "type": "string"
    },
    "name": {
      "type": "string",
      "pattern": "^(?=.*[a-z])[a-z0-9_]{1,32}$",
      "description": "The definition's name: the owner of its feeds and the prefix of their names."
    },
    "description": {
      "type": "string"
    },
    "preset": {
      "type": "string",
      "minLength": 1,
      "description": "A venue preset of market-data-devkit (binance, alpaca, fakevenue-binance, ...)."
    },
    "world": {
      "description": "act or hyp.<NAME>; default act.",
      "type": "string"
    },
    "universe": {
      "description": "Tagged on the feeds.",
      "type": "string"
    },
    "pairs": {
      "description": "Canonical pairs (BTC_USDT): bind {pair}.",
      "type": "array",
      "items": {
        "type": "string",
        "minLength": 1
      }
    },
    "families": {
      "description": "Families the preset serves (orderbook.update, trade.update, candle.update); default: every one the given pairs and intervals fill.",
      "type": "array",
      "items": {
        "type": "string",
        "minLength": 1
      }
    },
    "intervals": {
      "description": "Intervals (1m, 1h): bind {interval}, needed by candle.update.",
      "type": "array",
      "items": {
        "type": "string",
        "minLength": 1
      }
    },
    "topics": {
      "description": "Topics or templates with {pair}/{interval}, instead of pairs x families.",
      "type": "array",
      "items": {
        "type": "string",
        "minLength": 1
      }
    },
    "reconnect": {
      "description": "The feeds' autoreconnect; default true.",
      "type": "boolean"
    },
    "secrets": {
      "description": "Feed secret name → reference into the cluster's worker Secret, never a value.",
      "type": "object",
      "propertyNames": {
        "type": "string"
      },
      "additionalProperties": {
        "type": "string"
      }
    },
    "feed": {
      "description": "Further WebSocketFeed config keys (maxitems, releasewhenidleminutes, ...).",
      "type": "object",
      "propertyNames": {
        "type": "string"
      },
      "additionalProperties": {
        "type": "string"
      }
    }
  },
  "required": [
    "name",
    "preset"
  ],
  "additionalProperties": false,
  "title": "Virtufin feed definition",
  "description": "WebSocketFeed connections serving market-data topics (openspec feed-definitions)."
}

page-catalog.v1.json

The page catalog: every component a page may use, with its props schema (see Pages). Served at /schemas/page-catalog.v1.json without sign-in.

The document
{
  "$id": "https://app.virtufin.com/schemas/page-catalog.v1.json",
  "version": 1,
  "components": {
    "Stack": {
      "description": "Lays its children out in a column (vertical) or a row (horizontal)",
      "props": {
        "type": "object",
        "properties": {
          "direction": {
            "anyOf": [
              {
                "type": "string",
                "enum": [
                  "vertical",
                  "horizontal"
                ]
              },
              {
                "type": "null"
              }
            ]
          },
          "gap": {
            "anyOf": [
              {
                "type": "number",
                "minimum": 0,
                "maximum": 48
              },
              {
                "type": "null"
              }
            ]
          }
        },
        "required": [
          "direction",
          "gap"
        ],
        "additionalProperties": false
      }
    },
    "Heading": {
      "description": "A heading",
      "props": {
        "type": "object",
        "properties": {
          "text": {
            "type": "string"
          },
          "level": {
            "anyOf": [
              {
                "type": "integer",
                "minimum": 1,
                "maximum": 3
              },
              {
                "type": "null"
              }
            ]
          }
        },
        "required": [
          "text",
          "level"
        ],
        "additionalProperties": false
      }
    },
    "Text": {
      "description": "A paragraph of plain text",
      "props": {
        "type": "object",
        "properties": {
          "text": {
            "type": "string"
          }
        },
        "required": [
          "text"
        ],
        "additionalProperties": false
      }
    },
    "WorkerTable": {
      "description": "The workers of an invoke source of workmanager ListWorkers ({\"$state\": \"/sources/<id>\"}), in the data grid, filtered by a Worker Filter expression",
      "props": {
        "type": "object",
        "properties": {
          "source": {
            "type": "object",
            "properties": {
              "status": {
                "type": "string",
                "enum": [
                  "loading",
                  "ready",
                  "stale",
                  "failed"
                ]
              },
              "data": {},
              "error": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "since": {
                "type": [
                  "string",
                  "null"
                ]
              }
            },
            "required": [
              "status",
              "data",
              "error",
              "since"
            ],
            "additionalProperties": false
          },
          "filter": {
            "type": [
              "string",
              "null"
            ]
          },
          "tableId": {
            "type": [
              "string",
              "null"
            ]
          }
        },
        "required": [
          "source",
          "filter",
          "tableId"
        ],
        "additionalProperties": false
      }
    },
    "WorkerBrowser": {
      "description": "The Workers view: an invoke source of workmanager ListWorkers (workers) and the worker lifecycle topic (lifecycle) with the Worker Filter, sorting, the detail and start/stop/delete/tags (writes through the write gate)",
      "props": {
        "type": "object",
        "properties": {
          "workers": {
            "type": "object",
            "properties": {
              "status": {
                "type": "string",
                "enum": [
                  "loading",
                  "ready",
                  "stale",
                  "failed"
                ]
              },
              "data": {},
              "error": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "since": {
                "type": [
                  "string",
                  "null"
                ]
              }
            },
            "required": [
              "status",
              "data",
              "error",
              "since"
            ],
            "additionalProperties": false
          },
          "lifecycle": {
            "anyOf": [
              {
                "type": "object",
                "properties": {
                  "status": {
                    "type": "string",
                    "enum": [
                      "loading",
                      "ready",
                      "stale",
                      "failed"
                    ]
                  },
                  "data": {},
                  "error": {
                    "type": [
                      "string",
                      "null"
                    ]
                  },
                  "since": {
                    "type": [
                      "string",
                      "null"
                    ]
                  }
                },
                "required": [
                  "status",
                  "data",
                  "error",
                  "since"
                ],
                "additionalProperties": false
              },
              {
                "type": "null"
              }
            ]
          }
        },
        "required": [
          "workers",
          "lifecycle"
        ],
        "additionalProperties": false
      }
    },
    "ConnectionBrowser": {
      "description": "The Connections view: the WebSocketFeed workers of an invoke source of workmanager ListWorkers (workers), kept current from the worker lifecycle topic (lifecycle) and the feeds' metrics topic (metrics), with the Worker Filter, latency, publish/stop publishing/disconnect/tags and Connect (writes through the write gate)",
      "props": {
        "type": "object",
        "properties": {
          "workers": {
            "type": "object",
            "properties": {
              "status": {
                "type": "string",
                "enum": [
                  "loading",
                  "ready",
                  "stale",
                  "failed"
                ]
              },
              "data": {},
              "error": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "since": {
                "type": [
                  "string",
                  "null"
                ]
              }
            },
            "required": [
              "status",
              "data",
              "error",
              "since"
            ],
            "additionalProperties": false
          },
          "lifecycle": {
            "anyOf": [
              {
                "type": "object",
                "properties": {
                  "status": {
                    "type": "string",
                    "enum": [
                      "loading",
                      "ready",
                      "stale",
                      "failed"
                    ]
                  },
                  "data": {},
                  "error": {
                    "type": [
                      "string",
                      "null"
                    ]
                  },
                  "since": {
                    "type": [
                      "string",
                      "null"
                    ]
                  }
                },
                "required": [
                  "status",
                  "data",
                  "error",
                  "since"
                ],
                "additionalProperties": false
              },
              {
                "type": "null"
              }
            ]
          },
          "metrics": {
            "anyOf": [
              {
                "type": "object",
                "properties": {
                  "status": {
                    "type": "string",
                    "enum": [
                      "loading",
                      "ready",
                      "stale",
                      "failed"
                    ]
                  },
                  "data": {},
                  "error": {
                    "type": [
                      "string",
                      "null"
                    ]
                  },
                  "since": {
                    "type": [
                      "string",
                      "null"
                    ]
                  }
                },
                "required": [
                  "status",
                  "data",
                  "error",
                  "since"
                ],
                "additionalProperties": false
              },
              {
                "type": "null"
              }
            ]
          }
        },
        "required": [
          "workers",
          "lifecycle",
          "metrics"
        ],
        "additionalProperties": false
      }
    },
    "EventStoreBrowser": {
      "description": "The EventStores view: the EventStore workers of an invoke source of workmanager ListWorkers (workers), kept current from the worker lifecycle topic (lifecycle, health) and the EventStore metrics topic (metrics, counts), with their rules, fallback table and last error from the status command, and the Worker Filter",
      "props": {
        "type": "object",
        "properties": {
          "workers": {
            "type": "object",
            "properties": {
              "status": {
                "type": "string",
                "enum": [
                  "loading",
                  "ready",
                  "stale",
                  "failed"
                ]
              },
              "data": {},
              "error": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "since": {
                "type": [
                  "string",
                  "null"
                ]
              }
            },
            "required": [
              "status",
              "data",
              "error",
              "since"
            ],
            "additionalProperties": false
          },
          "lifecycle": {
            "anyOf": [
              {
                "type": "object",
                "properties": {
                  "status": {
                    "type": "string",
                    "enum": [
                      "loading",
                      "ready",
                      "stale",
                      "failed"
                    ]
                  },
                  "data": {},
                  "error": {
                    "type": [
                      "string",
                      "null"
                    ]
                  },
                  "since": {
                    "type": [
                      "string",
                      "null"
                    ]
                  }
                },
                "required": [
                  "status",
                  "data",
                  "error",
                  "since"
                ],
                "additionalProperties": false
              },
              {
                "type": "null"
              }
            ]
          },
          "metrics": {
            "anyOf": [
              {
                "type": "object",
                "properties": {
                  "status": {
                    "type": "string",
                    "enum": [
                      "loading",
                      "ready",
                      "stale",
                      "failed"
                    ]
                  },
                  "data": {},
                  "error": {
                    "type": [
                      "string",
                      "null"
                    ]
                  },
                  "since": {
                    "type": [
                      "string",
                      "null"
                    ]
                  }
                },
                "required": [
                  "status",
                  "data",
                  "error",
                  "since"
                ],
                "additionalProperties": false
              },
              {
                "type": "null"
              }
            ]
          }
        },
        "required": [
          "workers",
          "lifecycle",
          "metrics"
        ],
        "additionalProperties": false
      }
    },
    "ScriptBrowser": {
      "description": "The Scripts view: the user's scripts and examples, an editor, run and stop in a sandbox, the output and every operation called (writes through the write gate)",
      "props": {
        "type": "object",
        "properties": {},
        "additionalProperties": false
      }
    },
    "PortfolioBrowser": {
      "description": "The Portfolio view: an account picked among those whose snapshot topics the api has seen, its balances (zero ones hidden until shown) and working open orders, from the saved account then each change (read only)",
      "props": {
        "type": "object",
        "properties": {},
        "additionalProperties": false
      }
    },
    "PnlBrowser": {
      "description": "The P&L view: the scenario's P&L book, one row per symbol and a total, read again on each P&L update (read only)",
      "props": {
        "type": "object",
        "properties": {},
        "additionalProperties": false
      }
    },
    "RiskBrowser": {
      "description": "The Risk view: the scenario's spot exposure per symbol with limits and breaches, from the exposure updates or the saved book with the scenario's limits; Limits… sets them (a write through the write gate)",
      "props": {
        "type": "object",
        "properties": {},
        "additionalProperties": false
      }
    },
    "IndicatorBrowser": {
      "description": "The Indicators view: a scenario and an indicator picked among the changed topics the api has seen, one row per pair with columns by the value's shape, from the saved values then each changed event; a pair opens its values while shown (read only)",
      "props": {
        "type": "object",
        "properties": {},
        "additionalProperties": false
      }
    },
    "OrderBookBrowser": {
      "description": "The Order book view: one book picked among every book the api has seen, seeded from the saved book, then each changed image; the ladder of the top levels with depth bars, gaps and a note when nothing produces it (read only)",
      "props": {
        "type": "object",
        "properties": {},
        "additionalProperties": false
      }
    },
    "InstrumentBrowser": {
      "description": "The Instruments view: every instrument whose snapshot topic the api has seen (any venue and world), its tick and lot size from the saved instrument, then each snapshot (read only)",
      "props": {
        "type": "object",
        "properties": {},
        "additionalProperties": false
      }
    },
    "StrategyBrowser": {
      "description": "The Strategy view: the atomic strategies (workers tagged type, from an invoke source of workmanager ListWorkers) and the composite ones (cfg.strategy.*); new strategy worker, compose (cycles refused), remove (writes through the write gate)",
      "props": {
        "type": "object",
        "properties": {
          "workers": {
            "type": "object",
            "properties": {
              "status": {
                "type": "string",
                "enum": [
                  "loading",
                  "ready",
                  "stale",
                  "failed"
                ]
              },
              "data": {},
              "error": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "since": {
                "type": [
                  "string",
                  "null"
                ]
              }
            },
            "required": [
              "status",
              "data",
              "error",
              "since"
            ],
            "additionalProperties": false
          }
        },
        "required": [
          "workers"
        ],
        "additionalProperties": false
      }
    },
    "ScenarioBrowser": {
      "description": "The Scenario view: the context's scenarios (cfg.scenario.*) with status and trading halt; add, pause/resume, halt/resume trading, archive, delete (purges its sc.<S>.* state), use (writes through the write gate)",
      "props": {
        "type": "object",
        "properties": {},
        "additionalProperties": false
      }
    },
    "EventBrowser": {
      "description": "The Events view: the CloudEvents on the topics this browser follows on the context (picked from the api's topic catalog), the newest 500 with a running total, pause and clear, the value filter, flat or as the topic name tree, and each event's attributes and data",
      "props": {
        "type": "object",
        "properties": {},
        "additionalProperties": false
      }
    },
    "StateBrowser": {
      "description": "The States view: the state store's entries (QueryState, again on state-change events and every 2 s while shown), with the value filter, flat or as the name tree, and each key's value and stream (read only)",
      "props": {
        "type": "object",
        "properties": {},
        "additionalProperties": false
      }
    },
    "TriggerBrowser": {
      "description": "The Triggers view: the context's scheduled triggers (the api's Trigger service, read again on each trigger change event) with the table filter; Schedule (cron or a point in time) and Delete (writes through the write gate)",
      "props": {
        "type": "object",
        "properties": {},
        "additionalProperties": false
      }
    },
    "FeedBrowser": {
      "description": "The Feeds view: the feed definitions shared on the context (feed-definitions), each with its state from the WebSocketFeed workers of an invoke source of workmanager ListWorkers (workers) tagged with it as feedowner, kept current by the worker lifecycle topic (lifecycle) and the feeds' metrics topic (metrics); New/Edit (JSON editor with topics and plan), Connect, Disconnect, Delete (writes through the write gate)",
      "props": {
        "type": "object",
        "properties": {
          "workers": {
            "type": "object",
            "properties": {
              "status": {
                "type": "string",
                "enum": [
                  "loading",
                  "ready",
                  "stale",
                  "failed"
                ]
              },
              "data": {},
              "error": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "since": {
                "type": [
                  "string",
                  "null"
                ]
              }
            },
            "required": [
              "status",
              "data",
              "error",
              "since"
            ],
            "additionalProperties": false
          },
          "lifecycle": {
            "anyOf": [
              {
                "type": "object",
                "properties": {
                  "status": {
                    "type": "string",
                    "enum": [
                      "loading",
                      "ready",
                      "stale",
                      "failed"
                    ]
                  },
                  "data": {},
                  "error": {
                    "type": [
                      "string",
                      "null"
                    ]
                  },
                  "since": {
                    "type": [
                      "string",
                      "null"
                    ]
                  }
                },
                "required": [
                  "status",
                  "data",
                  "error",
                  "since"
                ],
                "additionalProperties": false
              },
              {
                "type": "null"
              }
            ]
          },
          "metrics": {
            "anyOf": [
              {
                "type": "object",
                "properties": {
                  "status": {
                    "type": "string",
                    "enum": [
                      "loading",
                      "ready",
                      "stale",
                      "failed"
                    ]
                  },
                  "data": {},
                  "error": {
                    "type": [
                      "string",
                      "null"
                    ]
                  },
                  "since": {
                    "type": [
                      "string",
                      "null"
                    ]
                  }
                },
                "required": [
                  "status",
                  "data",
                  "error",
                  "since"
                ],
                "additionalProperties": false
              },
              {
                "type": "null"
              }
            ]
          }
        },
        "required": [
          "workers",
          "lifecycle",
          "metrics"
        ],
        "additionalProperties": false
      }
    },
    "ValueStream": {
      "description": "The values of a topic or state source ({\"$state\": \"/sources/<id>\"}), newest first",
      "props": {
        "type": "object",
        "properties": {
          "source": {
            "type": "object",
            "properties": {
              "status": {
                "type": "string",
                "enum": [
                  "loading",
                  "ready",
                  "stale",
                  "failed"
                ]
              },
              "data": {},
              "error": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "since": {
                "type": [
                  "string",
                  "null"
                ]
              }
            },
            "required": [
              "status",
              "data",
              "error",
              "since"
            ],
            "additionalProperties": false
          },
          "title": {
            "type": [
              "string",
              "null"
            ]
          }
        },
        "required": [
          "source",
          "title"
        ],
        "additionalProperties": false
      }
    }
  }
}

App server routes

The app server (server/*.ts) answers these paths; everything else is the app itself (static files, with index.html for any other path). JSON routes answer content-type: application/json and cache-control: no-store; their errors are {"error": "<reason>"}.

Auth: none — no sign-in needed; session — a signed-in user (the vf_session cookie), else 401; admin for writes — see the route. Without sign-in configured (the dev server) every request counts as a signed-in admin. Routes marked same origin refuse a request whose Origin is not the app's own (VIRTUFIN_APP_PUBLIC_URL) with 403.

Health and static files

Method, path Auth Answer
GET /healthz none 200 ok (text).
GET /schemas/<file> none The published JSON documents (Schemas).
GET /<anything else> none The app (hashed /assets/* cached for a year, the rest no-cache).

Sign-in: /auth/…

Method, path Auth Request Answer
GET /auth/login?returnTo=<path> none returnTo: a path of this app (anything else becomes /). 302 to the OIDC provider (authorization code flow with PKCE, scopes openid profile email groups); sets the vf_login cookie (encrypted, 10 minutes).
GET /auth/callback?code=…&state=… none The provider's redirect. 302 to returnTo, setting vf_session (encrypted HttpOnly cookie, SameSite=Lax, Secure over https, lasting VIRTUFIN_APP_SESSION_HOURS); 400 {"error": "the sign-in took too long or was not started here; sign in again"} without a valid vf_login; 502 {"error": "sign-in failed: …"}.
GET /auth/logout none — 302 to /, clearing vf_session.
GET /auth/me none — 200 {"auth": true, "name", "email", "admin"} signed in; 401 {"auth": true} signed out; dev without sign-in: 200 {"auth": false, "name": null, "email": null, "admin": true}.

admin is true when the provider's groups claim holds the admin group (VIRTUFIN_APP_ADMIN_GROUP, default virtufin-admins), as of sign-in.

Contexts and the proxy

Method, path Auth Answer
GET /contexts session (401 sign in first, text) 200 {"contexts": [{"name", "description", "protected"}], "default": <VIRTUFIN_CONTEXT if in the catalog, else null>, "problems": ["context x: no api_port; left out", …]}. Never endpoints or keys.
POST /ctx/<name>/<package.Service>/<Method> session; same origin; admin for writes Forwarded to the context's api over HTTP/2 (h2c without TLS, h2 with), with the context's key as x-api-key; the response (status, headers, body) streams back unbuffered. gRPC-Web (application/grpc-web-text from the app).

/ctx/ errors (text): 401 sign in first; 403 requests from <origin> are not allowed; 404 no context <name>; 413 request larger than 16777216 bytes; 403 only admins may write (a non-admin's write); 502 context <name> unreachable: …. The browser's cookie, x-api-key, origin and referer headers are not forwarded.

AI: /ai/<context>/…

All: session (401 {"error": "sign in first"}), same origin, 404 {"error": "no context <name>"} for an unknown context, 405 for another method, 502 {"error": …} when the state store or the provider fails. The user's providers are kept per context at cfg.ai.provider.<USER> (Privacy).

Method, path Request Answer
GET /ai/<context>/providers — {"default": <name or null>, "providers": [{"name", "baseUrl", "model", "hasKey", "hint"}], "org": {"name": "org", "model"} or null}. hint: the key's last 4 characters.
PUT /ai/<context>/providers {"default": <name>, "providers": [{"name", "baseUrl", "model", "key"?}]} (at most 2 MiB). A provider without key keeps its sealed key; default may be org. The same view as GET. 400 for: more than 10 providers, a missing or duplicate name, the name org, a base URL that is not https, carries credentials, does not resolve or is private. An unknown default becomes the first provider.
POST /ai/<context>/chat {"provider"?, "messages": [...], "tools"?: [...]} (OpenAI Chat Completions messages and tools; at most 2 MiB). Without provider: the user's default, else the org provider. The provider's answer as is ({"choices": [{"message": …}]}), relayed from <base URL>/chat/completions with the user's key (120 s timeout). 400 without a list of messages, no AI provider: add one in Settings > AI, no provider <name> with a key, no model for <name>: choose one in Settings > AI; 502 {"error": "provider answered <status>: …"}.
GET /ai/<context>/models — {"models": [{"provider", "id", "price": {"input", "output", "context"} or null}], "problems": [{"provider", "error"}], "pricesError": <string or null>}. The models each keyed provider lists (GET <base URL>/models, 15 s, at most 2000) and the org provider's; prices in USD per million tokens from LiteLLM's list.

Documentation: /docs/…

Session, same origin. The Virtufin docs sites in scope (VIRTUFIN_APP_AI_DOCS_SITES, by default all), indexed from their published search indexes and reloaded daily; the operations docs.search and docs.read call these.

Method, path Request Answer
GET /docs/search?q=<words>&limit=<n> q required; limit 1–20, default 8. {"sections": [{"site", "title", "url", "snippet"}], "problems": [{"site", "error"}]}: the best sections (title words count three times), the sites whose index could not be loaded. 400 without q.
GET /docs/read?url=<section url> A url from a search. {"url", "site", "title", "text"} (at most 20000 characters); 404 for a URL no site in scope has.

Changes: /changes

Session, same origin. The log is kept per user in each context's state at cfg.changelog.<USER>, the newest 500 per context.

Method, path Request Answer
GET /changes — {"changes": [{"at", "what", "outcome", "detail", "context"}], "unread": [{"context", "error"}]}: every context's entries, newest first; a context that does not answer within 5 s is in unread.
POST /changes/<context> {"what": <at most 500 characters>, "outcome": "done" \| "failed" \| "declined", "detail"?: <at most 2000 characters>} (at most 8 KiB). 200 with the stored entry (at set by the server) and context. 400 for a missing what, a bad outcome, a field too long; 404 for an unknown context; appended by compare-and-swap (5 attempts), 502 when that fails.

The browser's write gate posts each write here; you do not call it yourself.