DOCS · API REFERENCE

Integration API for external systems

A REST API reference for teams building their own agent applications on Vantisso, or embedding Vantisso control and management into an enterprise IT operations portal or ITSM system.

Last updated · 2026-07-28

API call basics

Authentication & authorization

1 · Token-based authentication

Tokens are issued by a Vantisso operator, and you authenticate simply by sending that token in the `Authorization: Bearer` header. During local development you can turn authentication off and call the API without a token, in which case Vantisso treats you as an operator.

curl -H "Authorization: Bearer $TOKEN" http://host:3000/whoami

{ "name": "acme-portal", "role": "user", "auth_disabled": false }

2 · Role- and ownership-based authorization

Every API call is evaluated on two independent checks: whether your assigned role is allowed to perform the requested action, and whether you may access the target object. Both must pass for the call to succeed.

3 · Choosing the right token for the job

4 · A caveat when spawning a single agent

5 · Reading the auth errors

6 · Multi-tenant isolation: a recipe

1. Issue one `user` token per tenant. A “tenant” is whatever unit you want to isolate — a customer, a portal login, a project workspace — and Vantisso maps each tenant to a single token. You can also give a tenant a TTL through the expires field.
2. Have each tenant create its own groups and run its agents inside them. Every agent in a group inherits the same owner id.
3. From there the server enforces isolation automatically: list calls return only the caller’s own resources, and any action aimed at an agent the tenant doesn’t own is rejected with a 404.

Single agent

To run a single agent without creating a group, you must spawn the VM that runs it with an `operator` token — this is mandatory, since a user token cannot create a standalone VM.

1. Spawn a VM : An optional {"profile":"…"} applies a customized sizing / model / system prompt; omit it and the default profile is applied automatically.

curl -sX POST http://host:3000/vms \
  -H "Authorization: Bearer $OP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"profile":"support-agent"}'

201 Created
{
  "vm_id": "vm-1720982400000000000",
  "guest_ip": "10.0.1.5",
  "runtimed_url": "http://10.0.1.5:8080",
  "profile": "support-agent",
  "provider": "google",
  "model": "gemini-2.0-flash",
  "runtimed_token": "…"
}

The call blocks until the agent is ready — typically under a second, up to 60 seconds. The runtimed_token is returned only once and is never reissued; in practice you rarely need it directly, because the control-plane proxy holds it centrally and injects it into each VM on demand. If host disk is exhausted, the spawn returns 507; if the evaluation license has expired, it returns 403 trial_expired.

2. Run a task : The control-plane token is all you need; the prompt is proxied to the agent automatically. An agent processes one task at a time and returns 503 while it is busy.

curl -sX POST http://host:3000/vms/$VM_ID/tasks \
  -H "Authorization: Bearer $OP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"prompt":"Summarize ticket INC-4821 and propose a resolution."}'

{ "output": "…the agent's final answer…", "error": "" }

• Multi-turn : pass "session":"<your-id>" to continue one conversation thread across calls. Session state lives in the memory of the agent runtime inside the VM, in a namespace fully isolated per VM. Unlike tokens, the session id is not managed by the control plane — it is passed straight through.
• Streaming : add ?stream=1 to receive the response as NDJSON (see Streaming, below).

3. Tear down : The VM, its network, and its disk are all released automatically.

curl -sX DELETE http://host:3000/vms/$VM_ID -H "Authorization: Bearer $OP_TOKEN"

Agent team

Vantisso lets you operate agents as a team: you create an agent group, and the agents spawned under it collaborate as one team.

1. Create the team : You can create a group with either a `user`-class or an `operator`-class token. With a user token, an Owner id is assigned and propagated to every agent in the group, making the group’s ownership explicit; a group created with an operator token, by contrast, isn’t bound to any tenant and is treated as shared infrastructure. Each role listed in the body’s `roles` field becomes one agent VM instance, and the vCPU count and memory each VM receives are drawn from the resource profile predefined for that role.

curl -sX POST http://host:3000/groups \
  -H "Authorization: Bearer $TENANT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
        "task": "Draft the release notes for v1.4",
        "roles": ["orchestrator","writer","reviewer"],
        "max_agents": 5
      }'

201 Created
{
  "group_id": "group-1720982500000000000",
  "task": "Draft the release notes for v1.4",
  "agents": [
    { "agent_id": "orchestrator-1", "role": "orchestrator", "profile": "orchestrator",
      "vm_id": "vm-…", "runtimed_url": "http://10.0.1.6:8080", "status": "ready" },
    { "agent_id": "writer-1", "role": "writer", "profile": "writer",
      "vm_id": "vm-…", "runtimed_url": "http://10.0.1.7:8080", "status": "ready" },
    { "agent_id": "reviewer-1", "role": "reviewer", "profile": "reviewer",
      "vm_id": "vm-…", "runtimed_url": "http://10.0.1.8:8080", "status": "ready" }
  ],
  "runtimed_tokens": { "orchestrator-1": "…", "writer-1": "…", "reviewer-1": "…" },
  "feed_url": "/groups/group-…/feed",
  "post_url": "/groups/group-…/post"
}

As the example response above shows, each agent’s id is the role name plus an index number (writer-1, writer-2, …). The runtimed_tokens are the credentials used to talk to the agents directly, and they are returned in the response only once, at creation.

2. Run tasks : To send a prompt to a single member of the group, address it by that agent’s vm_id (POST /vms/{id}/tasks). To fan a prompt out to every member at once, use the broadcast endpoint, as shown below.

curl -sX POST http://host:3000/groups/$GID/broadcast \
  -H "Authorization: Bearer $TENANT_TOKEN" \
  -H "Content-Type: application/json" -d '{"body":"Status check: where are we?"}'

3. Tear down the team : Deleting an agent group also tears down every agent VM that belongs to it.

curl -sX DELETE http://host:3000/groups/$GID -H "Authorization: Bearer $TENANT_TOKEN"

Transcripts

A live chat session lives only in the RAM assigned to its VM, so it disappears the moment that VM shuts down. Vantisso persists each agent’s chat session to the host as a snapshot at teardown, so the conversation survives events such as a VM restart. Vantisso calls this the transcript feature.

An example transcript record:

{
  "schema_version": 1,
  "session": "INC-4821",
  "vm_id": "vm-…",
  "group_id": "group-…",
  "agent_id": "writer-1",
  "owner": "acme-portal",
  "profile": "support-agent",
  "title": "Summarize ticket INC-4821",
  "turns": [
    { "role": "user", "text": "Summarize ticket INC-4821…" },
    { "role": "assistant", "text": "…" }
  ],
  "saved_at": "2026-07-15T09:12:00Z"
}

Reference data

These read-only endpoints provide the core information you need when building a custom UI for composing and managing agent teams on Vantisso.

Streaming

Rather than returning the whole result in a single buffered object, POST /vms/{id}/tasks?stream=1 streams the response as newline-delimited JSON (NDJSON) — one frame per line. As the example below shows, frames come in three types.

{ "type": "progress", "text": "running shell: grep -n …" }
{ "type": "token",    "text": "The " }
{ "type": "token",    "text": "root cause " }
{ "type": "result",   "output": "…final answer…", "error": "" }

• type: "progress" — emitted at each defined step as the agent loop runs and calls tools. A frame may arrive with an empty text field, acting as a heartbeat; retry hints, such as backing off under an LLM’s rate limits, are also delivered as progress frames.
• type: "token" — an incremental piece of the output text, sent only when the profile’s live token streaming (described earlier) is enabled; concatenate these in order to reconstruct the model’s full response.
• type: "result" — delivered exactly once, as the final frame of the stream; reading just this frame reproduces the buffered object. An empty error field means success, a non-empty one means failure.

Status codes

• Error message format : every error is returned as a JSON object of the form {"error":"…"}.

GET /license
→ {
  "type":       "evaluation",           // or "commercial"
  "status":     "active",               // "active" | "grace" | "expired"
  "started_at": "2026-07-01T00:00:00Z",
  "expires_at": "2026-07-31T00:00:00Z",
  "days_left":  21,
  "enforced":   true
}