Skip to main content

Automating VAMS

The VAMS web interface is one of four ways to work with your assets. The command line, an AI agent, and the REST API reach the same data through the same permission checks, and are the right choice when a task is repetitive, needs to run unattended, or belongs inside another application.

This page helps you choose a surface and points you at the reference material for it. It does not teach any of them -- each has its own section of this documentation.

Choosing a surface​

SurfaceUse it whenReference
Web interfaceYou are working interactively -- browsing, viewing 3D files, reviewing results, or making one-off changes.The rest of this user guide
VAMS CLIYou are scripting a repeatable task, operating on many assets at once, or running VAMS steps from a CI/CD pipeline.CLI documentation
VAMS MCP serverYou want an AI agent to search, inspect, and report on a deployment in response to questions asked in natural language.VAMS MCP Server
REST APIYou are building your own application, integration, or connector on top of VAMS.API Overview
Your permissions apply everywhere

Every surface enforces the same two-tier authorization. Automating a task does not widen what you can reach -- if you cannot see an asset in the web interface, a script running as you cannot see it either. See Permissions.

Credentials for programmatic access​

Interactive sign-in works for the web interface, but a script or an integration needs a credential that does not involve a person at a keyboard. An API key is that credential. It is tied to a specific VAMS user and inherits that user's roles and permissions.

Create one before you start automating, and give it to the CLI, an agent, or your own application as needed. See API Keys for how to create, scope, rotate, and revoke them.

Give automation its own user

Create a dedicated VAMS user for each automated process and assign it only the roles that process needs, then issue the API key against that user. A key scoped this way limits the damage if it leaks, and it makes the audit log show which process acted.

Using the command line​

The VAMS CLI covers assets, files, databases, metadata, tags, search, permissions, pipelines, workflows, and executions. It is the surface most VAMS automation uses, and it supports a --json-output option throughout so its results can be parsed by other tools.

Prerequisites

  • Python installed on the machine that will run the CLI.
  • The URL of your VAMS deployment.
  • A VAMS account, or an API key for unattended use.

Getting started

  1. Install the CLI. See CLI Installation.

  2. Point it at your deployment:

    vamscli setup https://your-vams-url.example.com

  3. Sign in:

    vamscli auth login -u your.email@example.com

  4. Confirm the CLI is working:

    vamscli database list

From here, CLI Getting Started covers profiles for working against more than one deployment and authenticating with an API key, Command Reference lists every command group, and Automation covers scripting patterns and running the CLI in CI/CD.

Using an AI agent​

The VAMS MCP server exposes the VAMS API to an AI agent as a set of tools, so you can ask questions about a deployment in natural language -- finding assets matching a description, summarizing what a workflow produced, or checking which assets lack required metadata -- and have the agent gather the answer.

It stores no credentials of its own. It reuses the CLI's profile and sign-in, so set up and authenticate the CLI first.

Read-only until you enable more

The MCP server exposes only read tools by default. Write tools (create and update) require VAMS_ENABLE_WRITES, and destructive tools (archive and delete) additionally require VAMS_ENABLE_DESTRUCTIVE. Leave both off unless an agent genuinely needs to change data, and turn on destructive tools only against a deployment you can afford to have modified.

For setup, the tool list, and the gating options, see VAMS MCP Server.

Using the REST API​

Build against the REST API when you are writing your own application or connector rather than driving VAMS from a shell. Requests carry an Authorization header with a bearer token -- either an API key or a token from your identity provider.

Prerequisites

  • The base URL of your deployment's API.
  • An API key, or a token from your identity provider.

Start with API Overview for the base URL, response format, pagination, and error codes, then Authentication for the supported credential types and the authorization model. Individual endpoint references are grouped by domain in the API Reference section.

Consider the CLI first

If you are automating a task rather than building an application, the CLI is usually less work than calling the API directly -- it already handles authentication, token refresh, pagination, and retries. Reach for the API when you need behavior the CLI does not offer.

  • API Keys -- Create and manage credentials for programmatic access
  • Permissions -- How authorization applies to every surface
  • CLI Getting Started -- Install, configure, and authenticate the CLI
  • API Overview -- Base URL, response format, and conventions