API Reference

Stable VSLZ API v1 for API-key-authenticated integrations. This surface covers the routes used by direct clients and the local MCP server.

Authentication

Send Authorization: Bearer vslz_.... API keys are created in Settings and can be revoked at any time.

Async runs

Set wait=false on POST /api/v1/analyze to get a run_id, then poll or cancel.

Analyze

Run multi-step analysis either synchronously in one request or asynchronously with a durable run record.

Analyze data

Create or reuse a session, resolve file hints, and run the VSLZ analysis pipeline.

POST /api/v1/analyze

Request

message

Required natural-language analysis request.

session_id

Optional session to attach the run to. Created automatically when omitted.

file_ids

Optional list of session or global file IDs to prioritize.

model

Optional model override. Defaults to the current server default.

wait

Set `true` for a completed response or `false` for an async `run_id`.

max_iterations

Optional iteration cap between 1 and 200.

Response

data.run_id

Returned when `wait=false`; durable run identifier for polling.

data.session_id

Session associated with the request.

data.outputs

Completed outputs array when `wait=true`.

data.assistant_text

Final assistant response when `wait=true`.

Example

{
  "waitTrueRequest": {
    "message": "Build a revenue by region chart for this quarter.",
    "session_id": "sess_123",
    "file_ids": ["file_sales_q1"],
    "wait": true
  },
  "waitTrueResponse": {
    "ok": true,
    "data": {
      "session_id": "sess_123",
      "assistant_text": "Revenue is strongest in North America...",
      "outputs": [
        {
          "id": "out_123",
          "type": "chart"
        }
      ]
    }
  },
  "waitFalseRequest": {
    "message": "Profile anomalies in the uploaded pipeline logs.",
    "wait": false
  },
  "waitFalseResponse": {
    "ok": true,
    "data": {
      "run_id": "run_123",
      "session_id": "sess_456",
      "status": "running"
    }
  }
}

Runs

Poll durable async runs and request cancellation.

Get run status

Return the current status, progress snapshot, result payload, and terminal error state for an async run.

GET /api/v1/runs/:runId

Request

No body fields.

Response

data.status

Current run state such as `running`, `completed`, or `failed`.

data.progress

Progress snapshot written by the workflow.

data.result

Terminal result payload when the run completes.

data.error

Terminal error payload when the run fails.

Example

{
  "ok": true,
  "data": {
    "run_id": "run_123",
    "session_id": "sess_456",
    "status": "running",
    "progress": {
      "stage": "workflow_started",
      "status": "running"
    },
    "started_at": "2026-03-28T09:12:00.000Z",
    "finished_at": null,
    "result": null,
    "error": null,
    "credits_used": 0
  }
}

Cancel run

Mark a queued or running run as cancel requested and attempt to cancel the backing workflow execution.

POST /api/v1/runs/:runId/cancel

Request

No body fields.

Response

data.status

Updated status, usually `cancel_requested` for active runs.

data.cancellation_requested

Boolean confirmation that the request was recorded.

data.workflow_cancel_sent

Whether the workflow cancellation call was dispatched.

Example

{
  "ok": true,
  "data": {
    "run_id": "run_123",
    "status": "cancel_requested",
    "cancellation_requested": true,
    "workflow_cancel_sent": true
  }
}

Files and schemas

Upload source files, list them by scope, and fetch the generated schema card for a file.

Upload file

Upload a CSV, TSV, JSON, or XLSX file into a session or the global library.

POST /api/v1/upload

Request

file

Required multipart file payload.

scope

Either `session` or `global`. Defaults to `session`.

session_id

Required for session uploads.

kind

Usually `data`; image uploads are session-only.

Response

data.scope

Where the file was stored.

data.file.id

Uploaded file identifier.

data.file.column_names

Provisional column names extracted at upload time.

Example

{
  "ok": true,
  "data": {
    "scope": "session",
    "file": {
      "id": "file_sales_q1",
      "name": "sales-q1.csv",
      "row_count": 4812,
      "column_names": ["region", "revenue", "date"]
    }
  }
}

List files

Return global files plus optional session-scoped files for a given session.

GET /api/v1/files

Request

session_id

Optional query param to include files for a specific session.

Response

data.global_files

Files available across sessions.

data.session_files

Files attached to the requested session.

Example

{
  "ok": true,
  "data": {
    "session_files": [
      { "id": "file_sales_q1", "name": "sales-q1.csv" }
    ],
    "global_files": [
      { "id": "file_reference", "name": "product-catalog.xlsx" }
    ]
  }
}

Get schema card

Fetch the generated schema card for a session or global file ID.

GET /api/v1/schema/:fileId

Request

No body fields.

Response

data.source

Either `session` or `global` depending on where the file lives.

data.schema.content

Schema profile payload including rows, columns, and quirks.

data.schema.tier2_complete

Whether deeper profiling completed.

Example

{
  "ok": true,
  "data": {
    "source": "session",
    "schema": {
      "id": "schema_123",
      "tier2_complete": false,
      "content": {
        "rows": 4812,
        "columnsCount": 3
      }
    }
  }
}

Query and outputs

Run a synchronous query and fetch either chart payloads or downloadable output files.

Run query

Shortcut to `/api/v1/analyze` with `wait=true` so the result returns in one response.

POST /api/v1/query

Request

message

Required natural-language prompt.

session_id

Optional session identifier.

file_ids

Optional file IDs to prioritize.

model

Optional model override.

max_iterations

Optional cap for the agent loop.

Response

data.assistant_text

Completed assistant response.

data.outputs

Completed outputs array from the run.

Example

{
  "ok": true,
  "data": {
    "session_id": "sess_123",
    "assistant_text": "The strongest margin compression came from wholesale accounts.",
    "outputs": [
      {
        "id": "out_123",
        "type": "chart"
      }
    ]
  }
}

Get output

Return chart JSON metadata or download a generated file output for a session.

GET /api/v1/outputs/:outputId

Request

session_id

Required query param used to locate the output group.

version_id

Optional query param for a specific output version.

Response

data.type

For chart outputs, the response is JSON with `type: chart`.

data.code

Chart code when the output is a chart.

binary download

File bytes with `Content-Disposition` when the output is a file.

Example

{
  "ok": true,
  "data": {
    "type": "chart",
    "output_id": "out_123",
    "version_id": "ver_456",
    "version_number": 2,
    "label": "Revenue by region",
    "chart_type": "bar",
    "code": "{ ... chart config ... }"
  }
}

Sessions and keys

List workspace sessions and manage API keys used by MCP clients and direct integrations.

List sessions

Return sessions for the authenticated account ordered by recent activity.

GET /api/v1/sessions

Request

limit

Optional query param between 1 and 100. Defaults to 25.

offset

Optional query param for pagination. Defaults to 0.

Response

data.sessions

Session rows including status and timestamps.

data.limit

Applied page size.

data.offset

Applied offset.

Example

{
  "ok": true,
  "data": {
    "sessions": [
      {
        "id": "sess_123",
        "name": "Q1 revenue deep dive",
        "run_status": "completed"
      }
    ],
    "offset": 0,
    "limit": 25
  }
}

Create API key

Create a new API key from an authenticated workspace session and return the plain text key once.

POST /api/v1/keys

Request

name

Required label for the key.

scopes

Optional scopes array. Defaults to the current generated key scopes.

expires_at

Optional ISO timestamp expiry.

Response

data.key

Stored key metadata without the secret value.

data.plain_text_key

Full API key string, shown once.

Example

{
  "ok": true,
  "data": {
    "key": {
      "id": "key_123",
      "name": "Claude Desktop",
      "prefix": "vslz_abcd"
    },
    "plain_text_key": "vslz_abcdefghijklmnopqrstuvwxyz"
  }
}

List API keys

Return API key metadata for the authenticated workspace user.

GET /api/v1/keys

Request

No body fields.

Response

data[]

Array of key metadata including prefix, scopes, revocation state, and last use.

Example

{
  "ok": true,
  "data": [
    {
      "id": "key_123",
      "name": "Claude Desktop",
      "prefix": "vslz_abcd",
      "scopes": ["mcp"],
      "revoked_at": null
    }
  ]
}

Revoke API key

Soft-revoke an API key so it stops authorizing new requests immediately.

DELETE /api/v1/keys/:keyId

Request

No body fields.

Response

data.revoked

Boolean indicating whether a matching active key was revoked.

Example

{
  "ok": true,
  "data": {
    "revoked": true
  }
}