{"info":{"_postman_id":"230ce1f4-4c29-4006-87b5-45620ae91c61","name":"PVML Documentation","description":"

\n\n

📄 Get started here!

Introduction

PVML is a database virtualization infrastructure that lets IT teams spin up Virtual Databases (VDBs): secure virtual environments on top of their existing data stack in seconds.

Not a copy, no data stored. 100% data-less.

Each VDB enforces fine-grained access controls such as column-level policies, row-level security (RLS), query timeout, dynamic masking, and differential privacy, independent of the capabilities of the underlying database.

Every query is intercepted and transformed in real time - policies baked directly into the query - so only secure outputs ever leave the database.

Plug-and-Play

Connecting your existing databases to PVML takes seconds - just a connection string. No installations, no drivers, no agents, no data copying.

Once connected, VDBs are instantly consumable by any client through standard protocols, including:

ODBC/JDBC - for BI tools (Tableau, PowerBI, etc.)
\n
MCP (Model Context Protocol) - for GenAI applications and platforms (ChatGPT, LangChain, etc.)
\n
API - for custom applications, agents, services, and programmatic integrations via REST/HTTP interfaces
\n

How it works

A VDB consists of 2 components:

PVML Proxy Engine (reverse-proxy), matches any underlying database technology and can decode any query.
\n
PVML Runtime Authorization Engine (compiler), dialect-agnostic, can reconstruct any query and re-build it into a secure query. This means that guardrails enforcement is done solely as pre-processing via query transformation, making the solution efficient, secure, and optimized (under 3ms overhead).
\n

A VDB does not ingest or store raw data. It acts like a database from a connectivity & enforcement perspective:

Adheres to the protocol of the physical database
\n
Exposes standard interfaces such as ODBC/JDBC, MCP, API
\n
Independently enforcing guardrails at runtime.
\n
Built-in user-level authentication (oAuth for MCP)
\n
Every data interaction is automatically audited
\n

What's Our Edge?

We deliver bionic security at enterprise scale, bringing deterministic security to the non-deterministic GenAI era by combining advanced guardrails with runtime enforcement, so every AI interaction with enterprise data is governed and auditable by design.

🤖❌ Our solution is 100% LLM free

We don't rely on AI to enforce privacy and security. Every query is routed through our dedicated Runtime Authorization Engine, which deterministically ensures results adhere to your VDB guardrails.

The result: the tradeoff IT has always faced - between security and business enablement - is gone. Your teams can connect AI on real data without compromise.

Impact

Deterministic Security by Design: GenAI requires security that is not probabilistic, but predictable and auditable.
\n
No Workflow Changes: Legacy code from 30 years ago works as-is. Modern AI agents connect just the same.
\n
Enterprise-Grade Scale & Performance: No more encryption or synthetic data. Get live, secure access with sub-3 ms latency.
\n
No Data Movement or Duplication: No siloed copies, no stale extracts. On-demand Virtual Databases for any use case.
\n
Context-Aware Access at Scale: Infinite virtual databases over the same underlying data, enabling context-specific access identities at scale.
\n

Guardrails

IT teams can now unify permissions across all data sources through a centralized infrastructure plane. This eliminates inconsistent enforcement across systems, reduces operational complexity, and applies security controls uniformly at enterprise scale.

Our Runtime Authorization Engine enables highly granular access control, including:

Column level scoping
\n
Dynamic row level security (RLS)
\n
Dynamic masking
\n
Differential Privacy
\n
Aggregation functions only (Privacy)
\n
Load control (timeout and row limit)
\n

Differential Privacy - PVML's Proprietary Algorithms

PVML offers a robust data protection technology called Differential Privacy to protect data outputs with mathematical guarantees of individual privacy. This concept is unique since it requires no alterations to the underlying data, ensuring privacy is enforced at the output level of the analysis.

Audit & Visibility

\n\n

Each virtual DB provides full visibility over all data interactions. You can track queries of all users, success/failure rates, run duration and even the free text questions used in agentic pipelines.

We also provide System Audit to monitor workspace-level actions, such as who changed a policy, a VDB or a user's access, and when.

Security and Compliance Applications

Security and compliance teams gain structured audit and security logs for every data interaction, including query metadata, user metadata, and policy violation attempts. The logs are in a standard JSON format, so you can send them to the tools you already use: your SIEM, ELK, CloudWatch, Datadog or any other monitoring platform. Use them there for investigations, threat detection and compliance reports.

Product and Business Applications

Data and AI teams gain visibility into how users and AI agents interact with data through free-text questions, latency metrics, and success/failure tracking. Teams can identify recurring questions, repeated failures, broken workflows, and inefficient queries to improve agent behavior, optimize applications, refine prompts, and prioritize product improvements based on real usage patterns.

How Does PVML Speed Up My GenAI Initiatives?

Security: VDB guardrails can be tailored to compliance and governance requirements, enabling initiatives previously blocked by security constraints.
\n
Connectivity: PVML automatically provides an MCP server and an API for each virtual database, plug-n-play into any agent building platform (e.g., Anthropic Claude, OpenAI ChatGPT, Microsoft Copilot Studio), AI application (e.g., Cursor, Claude Code) or internal solution (e.g., built on LangChain).
\n
Performance & Accuracy: Each VDB can be optimally scoped for the GenAI initiative and includes a semantic layer for describing metadata and business context to LLMs, improving query generation, reasoning quality, response reliability, and overall application performance.
\n

Deploy Anywhere

PVML supports flexible deployment across cloud and on-premise environments.

Cloud Deployment (SaaS)

Cloud-agnostic (Azure, AWS, GCP, Gov Cloud)
\n
Available on Google Cloud Marketplace & AWS Marketplace
\n
Supports VPC peering and dedicated tenant configurations
\n

On-Premise Deployment

Deploy on your existing Kubernetes infrastructure
\n
No dependency on external services: no external APIs, no LLMs, no GPUs required.
\n
Supports multi-datacenter setups and high-availability configurations
\n

How is PVML Compliant?

PVML provides cutting-edge data protection solutions powered by our proprietary Differential Privacy (DP) technology, which stands out in the EU review of anonymization methods: the Article 29 Working Party (today the European Data Protection Board) compared about 7 methods, and Differential Privacy was the only one that could defend against all the re-identification attacks it tested. The EU Data Act further underscores the importance of privacy-preserving technologies (PPT) like Differential Privacy. Our approach enables clients to securely access sensitive data without ever compromising privacy. As a SOC2-certified company, we adhere to rigorous standards for security, availability, and confidentiality, reaffirming our commitment to protecting data by design.

\n $\"PVML's%20Certifications\"$ \n\n

PVML Architecture

PVML's virtual databases require no installation, data movement, duplication, or modifications. This approach ensures that we do not store any sensitive raw data while providing a quick onboarding process with no changes to the existing workflow of end users.

PVML can be deployed as a SaaS solution in any cloud environment (AWS, GCP, Azure, Gov cloud) or on-premises in air-gapped environments.

\n $\"PVML%20Architecture%20(GCP%20example)\"$ \n\n

How do I get started?

Via API

This documentation thoroughly covers all the essential APIs needed to manage your data access effectively.

To get your API key and get started, navigate to Connections > REST API > Create****.

Authentication

Send your API key in the Authorization header of every request:

Authorization: Bearer <your API key>\n

In Postman, add a variable token with your API key, in an environment or in the collection's Variables tab. All requests use it. Do the same for the IDs in the URLs, for example {{workspace_id}}.

You can open the documentation on Postman to easily test and run API calls.

\n $\"Test%20and%20execute%20PVML%20API%20calls\"$ \n\n

The fundamental elements necessary for PVML to function are the Datasources and Policies. Once these are configured and users are invited/created, you can use the policies as building blocks to create your desired Virtual DBs.

We'll guide you through each step in the following sections to help you get everything up and running!

Via Python SDK

The PVML Python SDK streamlines access to all key features of our platform, offering pre-built methods for API operations and efficient handling of data access workflows. It’s designed to help you integrate and automate tasks with minimal setup.

\n $\"Using%20the%20PVML%20Python%20SDK%20with%20Langchain\"$ \n\n

Via User Interface (Platform)

PVML is fully available through the API, but we also have a really user-friendly UI platform with a complete walkthrough to guide you through everything hand in hand!

\n $\"PVML%20Platform\"$ \n\n

Contact and Support

In case you have questions, want to report an error or bug, or simply need additional assistance - don't hesitate to contact us at support@pvml.com or fill out a form here.

\n","schema":"https://schema.getpostman.com/json/collection/v2.0.0/collection.json","toc":[{"content":"📄 Get started here!","slug":"get-started-here"}],"owner":"27304672","collectionId":"230ce1f4-4c29-4006-87b5-45620ae91c61","publishedId":"2sBYHXQduf","public":true,"customColor":{"top-bar":"FFFFFF","right-sidebar":"303030","highlight":"7177F8"},"publishDate":"2026-11-02T22:06:26.000Z"},"item":[{"name":"Guide: Quick start","item":[],"id":"351fedb4-9e17-48b3-9f00-b6d32b5d91f8","description":"

This guide takes you from zero to the first secure query in about 15 minutes. Each step names the request in this collection and the place in the platform, so you can use either one.

The story

Maya runs the data platform at a bank. The branch analysts want a dashboard of accounts per city. They may see the account data, but not the names of the account holders. Maya does not want to copy data or change the database.

With PVML, she connects the database once and creates a VDB (virtual database) for the analysts. The analysts connect their BI tool to the VDB, not to the database.

💡 The tables in this guide are examples. Use your own names (see Step 2).

Before you start

Workspace ID: in the platform, Settings > General. Put it in a Postman variable workspace_id.
API key: in the platform, Connections > REST API > Create New. Put it in a Postman variable token. Every request sends it as Authorization: Bearer <key>.
Network: PVML must be able to reach your database (host and port open for PVML).

Step 1: Connect the database

Check the connection details with Test Datasource Connection. It returns success or failed.
Connect it with the Connect request of your type, for example Connect Postgres. Save the id from the response as datasource_id.

In the platform: Datasources.

💡 Use a database user with read-only rights, unless you plan write policies. PVML can never allow more than this database user can do.

Step 2: Wait for the snapshot

PVML reads the structure of the database (schemas, tables, columns). This is the snapshot. It starts by itself after you connect.

Check it with Get Snapshot Status until lastRefreshStatus is completed.
PVML does not copy your data. The snapshot is the structure, plus data samples in a Standard snapshot.
Get Snapshot lists your schemas, tables and columns with their exact names.

Step 3: Create the policies

Policies say what the analysts may see. Maya creates two:

A column policy (what they may read): the whole \"bank\".\"core\" schema. Use Create Column Policy with:

[{\"schema\": \"\\\"bank\\\".\\\"core\\\"\", \"table\": \"\", \"column\": \"\"}]\n

An empty table or column means \"all\".

A masking policy (what they see hidden): the holder names. Use Create Masking Policy with:

[{\"column\": \"\\\"bank\\\".\\\"core\\\".\\\"accounts\\\".\\\"holder_name\\\"\", \"unmaskLeft\": 0, \"unmaskRight\": 0}]\n

Save both policy ids.

In the platform: Policies, tabs Column and Masking.

Step 4: Create the VDB

Use Create Virtual DB with:

datasourceId: from Step 1.
permissionsIds: the two policy IDs from Step 3.
entitiesIds: leave it empty for now. You add the analysts in Step 6.

Save the VDB id as vdb_id.

In the platform: Virtual DBs.

Step 5: Test it

Run a query as yourself with Execute Query on Virtual DB:

SELECT a.holder_name, b.city\nFROM \"bank\".\"core\".\"accounts\" a\nJOIN \"bank\".\"core\".\"branches\" b ON a.branch_id = b.branch_id\nLIMIT 5\n

The result has real cities and masked names (*****). The data in the database did not change.

Step 6: Give the analysts access

People: invite them with Invite Users (role member), or add them with SSO (see Workspaces > Guide: SSO and SCIM setup).
Groups are easier: create a group \"branch analysts\" (Create Group), add the people, and give the group access with Update Virtual DB Users. New analysts only need to join the group.

Step 7: Connect the BI tool

Create a service account for the dashboard (Create Service Account) and add it to the VDB (Update Virtual DB Users).
Create a connection string for it (Create ODBC/JDBC Connection String).
Put the fields from the response in the BI tool. See the Connections folder.

💡 An analyst who uses an AI client instead connects it to the MCP server of the VDB. See GenAI > MCP.

Step 8: Check the audit

Every query on the VDB is in the Data Access Audit (Get Audit Records): who ran it, from which tool, how long it took, and if it succeeded. Every change Maya made (policies, VDB, users) is in the System Audit (Get Activity Log).

What next?

Show each analyst only the rows of their own branch: Policies > Guide: Row-level security (RLS).
Add more policies and learn how they combine: Policies > Guide: How policies work together.
Pick the right masking method: Policies > Guide: Masking strategies.

\n","_postman_id":"351fedb4-9e17-48b3-9f00-b6d32b5d91f8","auth":{"type":"bearer","bearer":{"basicConfig":[{"key":"token","value":"{{token}}"}]},"isInherited":true,"source":{"_postman_id":"230ce1f4-4c29-4006-87b5-45620ae91c61","id":"230ce1f4-4c29-4006-87b5-45620ae91c61","name":"PVML Documentation","type":"collection"}}},{"name":"Workspaces","item":[{"name":"Workspace CRUD","item":[{"name":"Create Workspace","id":"4be938c5-cee7-4a7d-b66a-0f4b0e9a87e6","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[],"body":{"mode":"formdata","formdata":[{"key":"data","type":"text","value":"{\n \"name\": \"my workspace\",\n \"description\": \"my team's workspace\"}"},{"key":"image","type":"text","value":""}]},"url":"https://platform.pvml.com/platform/api/v1/workspaces","description":"

This endpoint allows you to create a new workspace.

Path Parameters

This request uses no parameters.

Request Body

Form data containing:

data (text): Json with the following properties:
\n
- name(string): The name of the new workspace.
  \n
- description(string): The description of the new workspace.
  \n
\n

Response Body

The response is a workspace object in json format that includes the details of the newly created workspace:

id (string): The unique identifier of the new workspace.
\n
name (string): The name of the new workspace.
\n
description (string): The description of the new workspace.
\n
image (string): The path to the workspace's image.
\n

This endpoint retrieves a specific workspace by id.

Path Parameters

workspace_id (string): The unique identifier of the workspace.
enrich (boolean, query parameter): When true, the response also has the workspace image.

Request Body

This request does not contain a request body.

Response Body

The workspace, with these fields:

id (string): The unique identifier for the workspace.
\n
name (string): The name of the workspace.
\n
description (string): A brief description of the workspace.
\n

This endpoint retrieves the workspaces associated with a specific user.

Path Parameters

user_id(string): the unique id of the user in the workspace
\n
summary (boolean, query parameter): Whether to return more details (number of users and image).
\n

Request Body

This request does not contain a request body.

Response Body

The response will contain workspaces array in JSON format, where each workspace object includes the following fields:

id (string): The unique identifier for the workspace.
\n
name (string): The name of the workspace.
\n
description (string): A brief description of the workspace.
\n
numOfUsers (number): The number of users associated with the workspace (returned if summary is true).
\n
image (string): The image associated with the workspace (returned if summary is true).
\n

This endpoint allows you to update a workspace.

Path Parameters

workspace_id(string): the unique id of the workspace.

Request Body

Form data containing the fields to update:

data (text): Json with the following properties:
\n
- name(string): The name of the workspace.
  \n
- description(string): The description of the workspace.
  \n
\n
image (File): The image for the workspace.
\n

Response Body

Upon successful update, the server returns a status code of 201 and an empty JSON response.

This endpoint is used to delete a specific workspace.

Path Parameters

workspace_id (string): The unique identifier of the workspace to be deleted.

Request Body

This request does not contain a request body.

Response Body

Upon successful deletion of the workspace, the server returns a status code of 200 and an empty JSON response.

This guide connects PVML to your identity provider (IdP), such as Okta, Microsoft Entra ID or Google. After it:

people log in to PVML with their company account (SSO), and
users, groups and user attributes stay in sync with the IdP by themselves (SCIM).

The story

A bank has 300 analysts in Okta. Each one has a department in their Okta profile. The security team wants three things:

No separate PVML passwords.
When someone joins or leaves in Okta, PVML follows the same day, with no manual work.
Each analyst sees only the rows of their own department, based on the value in Okta.

SSO solves 1. SCIM solves 2. SCIM plus a linked attribute catalog solves 3.

Part 1: SSO (log in with the company account)

Create the provider in PVML. In the platform: Settings > SSO. With the API: Create SSO Integration, with:
- type: saml or oauth.
- vendor: okta, google, microsoft or generic.
- For SAML: the Metadata URL of the SAML app in your IdP.
- For OAuth: the Client ID, Client Secret, Auth URL, Token URL and User Info URL of the app in your IdP.
\n
Copy the PVML values into your IdP app. The platform shows them after you create the provider:
- OAuth: the Redirect URL (API: Get Redirect URL).
- SAML: the ACS URL and the Entity Id.
\n
Share the login URL. The response has a workspaceLoginUrl (platform: Workspace Login URL). Users of the workspace log in with it.

Save the provider id. SCIM needs it.

Part 2: SCIM (keep users and groups in sync)

In the platform (easiest): open Settings > SSO, open the provider, turn on Enable SCIM provisioning and click Generate SCIM credentials. Copy the Base URL and the Auth token into the provisioning settings of your IdP.

⚠️ The token is shown only once. If you generate new credentials, the old token stops working after you update your IdP.

With the API: see the steps in the SCIM folder.

After this, your IdP manages PVML users:

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

In your IdP	In PVML
Assign a person to the PVML app	A user is created
Change their profile	The user is updated, with the new attribute values
Unassign them, or they leave	The user is deactivated or removed
Push a group	A PVML group is created, with the same members
Give the `admin` role	The user becomes a workspace admin

💡 Tip: give VDB access to groups, not to single people. Then a new analyst who joins the right group in Okta gets the right VDBs in PVML, with no work in PVML.

Part 3: Attributes from the IdP (for row-level security)

SCIM also sends the profile fields of each user, for example department or country. To use one in a policy, link an attribute catalog to the SSO provider:

Create Attribute Catalog with:
- name: for example idp.
- ssoProviderId: the provider id from Part 1.
- urn: the SCIM schema of the field. For the standard enterprise fields (such as department): urn:ietf:params:scim:schemas:extension:enterprise:2.0:User.
\n
Define Attributes in this catalog with the same name as the SCIM field, for example department (type text).
That's it. When the IdP sends or updates a user, PVML fills the value. Check it with Get User Attributes.
Use it in a row policy, for example:

\"finance\".\"core\".\"expenses\".\"department\" = {{idp.department}}\n

Dana has department = Finance in Okta, so she sees only the expenses of Finance. If HR moves her to Sales in Okta, she sees the expenses of Sales after the next sync, with no change in PVML.

💡 Values that come from the IdP are managed by the IdP. You can not delete them in PVML. Change them in the IdP.

⚠️ If you delete the SSO provider, its linked catalogs and their values are removed too. Policies that use them then block the queries (a missing attribute never gives more access).

Checklist

SSO provider created, IdP app configured, login URL shared.
SCIM credentials generated and set in the IdP.
Groups pushed from the IdP and attached to VDBs.
Attribute catalog linked to the provider, attributes defined with the SCIM field names.
Row policies use {{catalog.attribute}}. See Policies > Guide: Row-level security (RLS).

\n","_postman_id":"219a3930-b659-4902-963c-86656464288a","auth":{"type":"bearer","bearer":{"basicConfig":[{"key":"token","value":"{{token}}"}]},"isInherited":true,"source":{"_postman_id":"230ce1f4-4c29-4006-87b5-45620ae91c61","id":"230ce1f4-4c29-4006-87b5-45620ae91c61","name":"PVML Documentation","type":"collection"}}},{"name":"SSO","item":[{"name":"Create SSO Integration","id":"ea5cb4e6-d3e6-4061-a522-6dee88893738","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[],"body":{"mode":"formdata","formdata":[{"key":"data","type":"text","value":"{\n \"createSsoProviderData\": {\n \"type\": \"saml\",\n \"vendor\": \"okta\",\n \"name\": \"my_sso\",\n \"userAttributesFetch\": \"none\",\n \"configData\": {\n \"samlData\": {\n \"metadataUrl\": \"https://mydomain.okta.com/app/abc123/sso/saml/metadata\"\n }\n }\n }\n}"}]},"url":"https://platform.pvml.com/platform/api/v1/workspaces/{{workspace_id}}/sso","description":"

Connects an SSO provider (identity provider) to the workspace.

Path Parameters

workspace_id (string): The unique identifier of the workspace.

Request Body

Form data with one field, data (text), a JSON with createSsoProviderData:

type (string): saml or oauth.
vendor (string): okta, google, microsoft or generic.
name (string, required): A name for the provider.
configData (object): Provider settings:
- For SAML: samlData.metadataUrl (the metadata URL of your SAML app).
- For OAuth: oauthData with clientId, clientSecret, authUrl, tokenUrl, userInfoUrl, scopes.
\n

Response Body

The provider: id, workspaceId, vendor, type, name, createdAt, configData, and workspaceLoginUrl. Users of the workspace log in with this URL.

\n","auth":{"type":"bearer","bearer":{"basicConfig":[{"key":"token","value":"{{token}}"}]},"isInherited":true,"source":{"_postman_id":"230ce1f4-4c29-4006-87b5-45620ae91c61","id":"230ce1f4-4c29-4006-87b5-45620ae91c61","name":"PVML Documentation","type":"collection"}},"urlObject":{"protocol":"https","path":["platform","api","v1","workspaces","{{workspace_id}}","sso"],"host":["platform","pvml","com"],"query":[],"variable":[]}},"response":[{"id":"e2092928-04b3-4f7e-81ab-08a431a60a6a","name":"Create SSO Integration - 201 Created","originalRequest":{"method":"POST","header":[],"body":{"mode":"formdata","formdata":[{"key":"data","type":"text","value":"{\n \"createSsoProviderData\": {\n \"type\": \"saml\",\n \"vendor\": \"okta\",\n \"name\": \"my_sso\",\n \"userAttributesFetch\": \"none\",\n \"configData\": {\n \"samlData\": {\n \"metadataUrl\": \"https://mydomain.okta.com/app/abc123/sso/saml/metadata\"\n }\n }\n }\n}"}]},"url":"https://platform.pvml.com/platform/api/v1/workspaces/{{workspace_id}}/sso"},"status":"Created","code":201,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json; charset=utf-8"}],"cookie":[],"responseTime":null,"body":"{\n \"id\": \"f75163b2-0ee9-55d5-acb6-9cfe445ec361\",\n \"workspaceId\": \"a1997551-93b5-5adc-9403-748712e22687\",\n \"vendor\": \"okta\",\n \"type\": \"saml\",\n \"userAttributesFetch\": \"none\",\n \"createdAt\": \"2026-10-29T23:56:10.539682Z\",\n \"name\": \"my_sso\",\n \"workspaceLoginUrl\": \"https://platform.pvml.com/login/a1997551-93b5-5adc-9403-748712e22687\",\n \"configData\": {\n \"samlData\": {\n \"metadataUrl\": \"https://mydomain.okta.com/app/abc123/sso/saml/metadata\"\n }\n }\n}"}],"_postman_id":"ea5cb4e6-d3e6-4061-a522-6dee88893738"},{"name":"Get SSO Providers","id":"ba373c79-c385-4b58-a9b0-e5cd72377c4f","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"GET","header":[],"url":"https://platform.pvml.com/platform/api/v1/workspaces/{{workspace_id}}/sso","auth":{"type":"bearer","bearer":{"basicConfig":[{"key":"token","value":"{{token}}"}]},"isInherited":true,"source":{"_postman_id":"230ce1f4-4c29-4006-87b5-45620ae91c61","id":"230ce1f4-4c29-4006-87b5-45620ae91c61","name":"PVML Documentation","type":"collection"}},"urlObject":{"protocol":"https","path":["platform","api","v1","workspaces","{{workspace_id}}","sso"],"host":["platform","pvml","com"],"query":[],"variable":[]}},"response":[{"id":"74229e58-6cdd-4cfc-89ad-7660302fd67f","name":"Get SSO Providers - 200 OK","originalRequest":{"method":"GET","header":[],"url":"https://platform.pvml.com/platform/api/v1/workspaces/{{workspace_id}}/sso"},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json; charset=utf-8"}],"cookie":[],"responseTime":null,"body":"{\n \"ssoProviders\": [\n {\n \"id\": \"f75163b2-0ee9-55d5-acb6-9cfe445ec361\",\n \"workspaceId\": \"a1997551-93b5-5adc-9403-748712e22687\",\n \"type\": \"saml\",\n \"userAttributesFetch\": \"none\",\n \"configData\": {},\n \"vendor\": \"okta\",\n \"name\": \"my_sso\",\n \"createdAt\": \"0001-01-01T00:00:00Z\",\n \"workspaceLoginUrl\": \"https://platform.pvml.com/login/a1997551-93b5-5adc-9403-748712e22687\"\n }\n ]\n}"}],"_postman_id":"ba373c79-c385-4b58-a9b0-e5cd72377c4f"},{"name":"Get Redirect URL","id":"7756033d-6996-4e44-a4ec-854afcd6f3c1","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"GET","header":[],"url":"https://platform.pvml.com/platform/api/v1/workspaces/{{workspace_id}}/sso/redirectUrl","auth":{"type":"bearer","bearer":{"basicConfig":[{"key":"token","value":"{{token}}"}]},"isInherited":true,"source":{"_postman_id":"230ce1f4-4c29-4006-87b5-45620ae91c61","id":"230ce1f4-4c29-4006-87b5-45620ae91c61","name":"PVML Documentation","type":"collection"}},"urlObject":{"protocol":"https","path":["platform","api","v1","workspaces","{{workspace_id}}","sso","redirectUrl"],"host":["platform","pvml","com"],"query":[],"variable":[]}},"response":[{"id":"eccd2c73-06bb-419d-93bf-cfe4de50905d","name":"Get Redirect URL - 200 OK","originalRequest":{"method":"GET","header":[],"url":"https://platform.pvml.com/platform/api/v1/workspaces/{{workspace_id}}/sso/redirectUrl"},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json; charset=utf-8"}],"cookie":[],"responseTime":null,"body":"{\n \"redirectUrl\": \"https://platform.pvml.com/platform/api/v1/auth/callback\"\n}"}],"_postman_id":"7756033d-6996-4e44-a4ec-854afcd6f3c1"},{"name":"Get SSO Integration","id":"d1e77d25-f4b6-4ee4-81fa-0ce7ca2cadc8","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"GET","header":[],"url":"https://platform.pvml.com/platform/api/v1/workspaces/{{workspace_id}}/sso/{{sso_integration_id}}","auth":{"type":"bearer","bearer":{"basicConfig":[{"key":"token","value":"{{token}}"}]},"isInherited":true,"source":{"_postman_id":"230ce1f4-4c29-4006-87b5-45620ae91c61","id":"230ce1f4-4c29-4006-87b5-45620ae91c61","name":"PVML Documentation","type":"collection"}},"urlObject":{"protocol":"https","path":["platform","api","v1","workspaces","{{workspace_id}}","sso","{{sso_integration_id}}"],"host":["platform","pvml","com"],"query":[],"variable":[]}},"response":[{"id":"bcec49b9-2324-4dff-a53c-19b731eb9fc5","name":"Get SSO Integration - 200 OK","originalRequest":{"method":"GET","header":[],"url":"https://platform.pvml.com/platform/api/v1/workspaces/{{workspace_id}}/sso/{{sso_integration_id}}"},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json; charset=utf-8"}],"cookie":[],"responseTime":null,"body":"{\n \"ssoProvider\": {\n \"id\": \"f75163b2-0ee9-55d5-acb6-9cfe445ec361\",\n \"workspaceId\": \"a1997551-93b5-5adc-9403-748712e22687\",\n \"type\": \"saml\",\n \"userAttributesFetch\": \"none\",\n \"configData\": {\n \"samlData\": {\n \"metadataUrl\": \"https://mydomain.okta.com/app/abc123/sso/saml/metadata\",\n \"acsUrl\": \"https://platform.pvml.com/platform/api/v1/auth/saml/acs/f75163b2-0ee9-55d5-acb6-9cfe445ec361\",\n \"entityId\": \"PVML\"\n }\n },\n \"vendor\": \"okta\",\n \"name\": \"my_sso\",\n \"createdAt\": \"2026-10-29T23:56:10.539682Z\",\n \"workspaceLoginUrl\": \"https://platform.pvml.com/login/a1997551-93b5-5adc-9403-748712e22687\"\n }\n}"}],"_postman_id":"d1e77d25-f4b6-4ee4-81fa-0ce7ca2cadc8"},{"name":"Update SSO Provider","id":"cad0b0fb-e61c-4f9a-84ee-5f5ae3c2de59","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"PATCH","header":[],"body":{"mode":"formdata","formdata":[{"key":"data","type":"text","value":"{\n \"updateSsoProviderData\": {\n \"vendor\": \"okta\",\n \"type\": \"saml\",\n \"name\": \"my_sso\",\n \"userAttributesFetch\": \"none\",\n \"configData\": {\n \"samlData\": {\n \"metadataUrl\": \"https://mydomain.okta.com/app/abc123/sso/saml/metadata\"\n }\n }\n }\n}"}]},"url":"https://platform.pvml.com/platform/api/v1/workspaces/{{workspace_id}}/sso/{{sso_integration_id}}","description":"

Updates an SSO provider.

Path Parameters

workspace_id (string): The unique identifier of the workspace.
sso_integration_id (string): The SSO provider ID.

Request Body

Form data with one field, data (text), a JSON with updateSsoProviderData. It has the same fields as in Create SSO Integration.

Response Body

The updated provider.

PVML integrates with your IAM to streamline user management and leverage user attributes in dynamic policies (e.g., creating row-level security based on a user’s region in Okta).

📘 See Guide: SSO and SCIM setup for the full setup, with SCIM and attributes from your identity provider.

\n","_postman_id":"21cbbb80-6e85-47f1-93ad-7dbb29eeb93b","auth":{"type":"bearer","bearer":{"basicConfig":[{"key":"token","value":"{{token}}"}]},"isInherited":true,"source":{"_postman_id":"230ce1f4-4c29-4006-87b5-45620ae91c61","id":"230ce1f4-4c29-4006-87b5-45620ae91c61","name":"PVML Documentation","type":"collection"}}},{"name":"SCIM","item":[{"name":"SCIM Get Service Provider Config","id":"ccc8bde1-f1be-40c3-a153-58c43239e8f3","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"GET","header":[],"url":"https://platform.pvml.com/platform/api/v1/workspaces/{{workspace_id}}/oauth2/{{sso_integration_id}}/scim/v2/ServiceProviderConfig","description":"

Returns the SCIM features of PVML. IdPs read it when you set up provisioning.

Path Parameters

workspace_id (string): The workspace ID.
sso_integration_id (string): The SSO provider ID.

Creates a PVML user in the workspace.

Path Parameters

workspace_id (string): The workspace ID.
sso_integration_id (string): The SSO provider ID.

Request Body

A SCIM User: userName (the email, required), externalId (the ID in your IdP), name, emails, active, and optional roles.

Response Body

Status 201 with the user and its PVML id.

Lists users, with an optional filter.

Path Parameters

workspace_id (string): The workspace ID.
sso_integration_id (string): The SSO provider ID.

Response Body

A SCIM ListResponse: totalResults, startIndex, itemsPerPage and Resources (the users).

Returns one user.

Path Parameters

workspace_id (string): The workspace ID.
sso_integration_id (string): The SSO provider ID.
scim_user_id (string): The user id.

Replaces all fields of a user.

Path Parameters

workspace_id (string): The workspace ID.
sso_integration_id (string): The SSO provider ID.
scim_user_id (string): The user id.

⚠️ The user must be active.

Changes some fields of a user. The most common use: deactivate a user who left.

Path Parameters

workspace_id (string): The workspace ID.
sso_integration_id (string): The SSO provider ID.
scim_user_id (string): The user id.

Request Body

A SCIM PatchOp. Each operation has op (add, replace or remove), path and value. Paths with filters ([...]) are not supported for users.

Response Body

The updated user.

Deletes the user from PVML.

Path Parameters

workspace_id (string): The workspace ID.
sso_integration_id (string): The SSO provider ID.
scim_user_id (string): The user id.

💡 To keep the user's settings, deactivate instead (SCIM Update User, active: false).

Creates a PVML group.

Path Parameters

workspace_id (string): The workspace ID.
sso_integration_id (string): The SSO provider ID.

Request Body

displayName (required) and members ([{\"value\": \"<user id>\"}]).

Response Body

Status 201 with the group and its id.

💡 Add members with SCIM Update Group after you create the group.

Lists groups, with an optional filter.

Path Parameters

workspace_id (string): The workspace ID.
sso_integration_id (string): The SSO provider ID.

Returns one group with its members.

Path Parameters

workspace_id (string): The workspace ID.
sso_integration_id (string): The SSO provider ID.
scim_group_id (string): The group id.

Replaces the name and all members of a group.

Path Parameters

workspace_id (string): The workspace ID.
sso_integration_id (string): The SSO provider ID.
scim_group_id (string): The group id.

Response Body

{\"status\": \"updated\"}.

Adds or removes group members.

Path Parameters

workspace_id (string): The workspace ID.
sso_integration_id (string): The SSO provider ID.
scim_group_id (string): The group id.

Request Body

A SCIM PatchOp. Supported operations:

Add: {\"op\": \"add\", \"path\": \"members\", \"value\": [{\"value\": \"<user id>\"}]}
Replace all: {\"op\": \"replace\", \"path\": \"members\", \"value\": [...]}
Remove one: {\"op\": \"remove\", \"path\": \"members[value eq \\\"<user id>\\\"]\"}

Response Body

The updated group.

Deletes the group. The users stay in the workspace.

Path Parameters

workspace_id (string): The workspace ID.
sso_integration_id (string): The SSO provider ID.
scim_group_id (string): The group id.

SCIM keeps PVML users and groups in sync with your identity provider (IdP), such as Microsoft Entra ID, Okta or SailPoint. When someone joins, moves or leaves in your IdP, PVML follows automatically. You do not call these endpoints yourself: your IdP does.

Set up SCIM

In the PVML UI (easiest): open Settings > SSO, open your SSO provider and turn on SCIM provisioning. PVML shows a Base URL and an Auth token. Put them in the provisioning settings of your IdP.

With the API:

Pick the SSO provider of the workspace (Get SSO Providers). Its id is part of the URL.
Create a service account for the IdP (Create Service Account) and give it the admin role (Update User Role).
Create an API key for this service account (Create User API Key). This is the token.
In your IdP, set:
- Base URL / Tenant URL: https://platform.pvml.com/platform/api/v1/workspaces/{workspace_id}/oauth2/{sso_integration_id}/scim/v2
- Authentication: Bearer token, with the API key.
\n

💡 Why a separate service account? The IdP gets its own key, which you can revoke at any time without touching any person's access. In the activity log you also see clearly which changes came from the IdP.

What PVML supports

Users: create, read, list, replace (PUT), update (PATCH) and delete. userName is the email address.
Groups: create, read, list, replace (PUT), update members (PATCH) and delete.
Filters: Users by userName (eq, ew), externalId (eq) and id (eq). Groups by displayName (eq) and id (eq). Combine with and. Example: filter=userName eq \"dana@example.com\".
Pages: startIndex (default 1) and count (default 100).
Deactivate a user: PATCH active to false. Use it when someone leaves: the user is deactivated, not deleted.
Admin role: a roles entry with the value admin makes the user a workspace admin.

Good to know

Add group members with SCIM Update Group (PATCH), operation add and path members.
Not supported: bulk requests, sorting, ETags and password changes.

\n","_postman_id":"fba1dc18-957d-42f9-bdf9-a647770033b3","auth":{"type":"bearer","bearer":{"basicConfig":[{"key":"token","value":"{{token}}"}]},"isInherited":true,"source":{"_postman_id":"230ce1f4-4c29-4006-87b5-45620ae91c61","id":"230ce1f4-4c29-4006-87b5-45620ae91c61","name":"PVML Documentation","type":"collection"}}}],"id":"7692889e-4205-415f-96a9-e02a11a98512","description":"

Everything in PVML is tied to a specific workspace. A workspace contains your datasources, users, policies, and a full audit log.

To get your workspace id, go to System > Settings > General and copy the workspace id:

\n $\"PVML%20-%20Get%20Workspace%20ID\"$ \n\n","_postman_id":"7692889e-4205-415f-96a9-e02a11a98512","auth":{"type":"bearer","bearer":{"basicConfig":[{"key":"token","value":"{{token}}"}]},"isInherited":true,"source":{"_postman_id":"230ce1f4-4c29-4006-87b5-45620ae91c61","id":"230ce1f4-4c29-4006-87b5-45620ae91c61","name":"PVML Documentation","type":"collection"}}},{"name":"Users","item":[{"name":"Groups","item":[{"name":"Create Group","id":"ca71ee4e-95c4-45e4-9c00-5ce6613ea3e1","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[],"body":{"mode":"formdata","formdata":[{"key":"data","type":"text","value":"{\"name\": \"new group\",\n\"description\": \"some description\"}"},{"key":"image","type":"file","value":null}]},"url":"https://platform.pvml.com/platform/api/v1/workspaces/{{workspace_id}}/groups","description":"

This endpoint allows to create a new group in a specific workspace.

Path Parameters

workspace_id(string): The unique identifier of the workspace.

Request Body

Form data with these fields:

data (text): Json with the following properties:
\n
- name(string): The name of the group.
  \n
- description(string): The description of the group.
  \n
\n
image (File): The image for the group.
\n

Response Body

Status 201 with the new group: id, name, description, workspaceId, createdAt, lastModifiedAt and image.

This endpoint retrieves a specific group within a workspace.

Path Parameters

workspace_id(string): The unique identifier of the workspace.
\n
group_id (string): The unique identifier of the group.
\n
enrich (boolean, query parameter): when set to true, the request returns additional details such as the group's image and users count.
\n

Request Body

This request does not contain a request body.

Response Body

group:
\n
- id (string): Unique identifier for the group.
  \n
- name (string): The name of the group.
  \n
- description (string): Description of the group.
  \n
- workspaceId (string): Unique identifier for the workspace to which the group belongs.
  \n
- createdAt (string, ISO 8601 format) Timestamp when the group was created.
  \n
- lastModifiedAt (string, ISO 8601 format): Timestamp when the group was last modified.
  \n
- usersCount (int): Number of users that belong to this group (returned if enrich is true).
  \n
- image (Base64-encoded string): binary image data; decode to retrieve the original image (returned if enrich is true).
  \n
\n

This endpoint retrieves the groups within a specific workspace.

Path Parameters

workspace_id(string): The unique identifier of the workspace.
\n
summary (boolean, query parameter): when set to true, the request returns additional details such as each group's image and users count.
\n

Request Body

This request does not contain a request body.

Response Body

groups: the groups of the workspace
\n
- group:
  \n
  - id: (String) Unique identifier for the group.
    \n
  - name (string): The name of the group.
    \n
  - description (string): Description of the group.
    \n
  - workspaceId (string): Unique identifier for the workspace to which the group belongs.
    \n
  - createdAt: (string, ISO 8601 format) Timestamp when the group was created.
    \n
  - lastModifiedAt: (string, ISO 8601 format) Timestamp when the group was last modified.
    \n
  - usersCount (int): Number of users that belong to this group (returned if summary is true).
    \n
  - image (Base64-encoded string): binary image data; decode to retrieve the original image (returned if summary is true).
    \n
  \n
\n

💡 The response also has a pagination object: totalRecords, currentPage, totalPages, pageSize, nextPage, prevPage.

This endpoint returns the VDBs that a group can access within a workspace.

Path Parameters

workspace_id(string): The unique identifier of the workspace.
\n
group_id (string): The unique identifier of the group.
\n

Request Body

This request does not contain a request body.

Response Body

vdbs: a list of VDBs associated with the group.

  - `vdbId` (string): Unique identifier for the VDB.\n      \n  - `datasourceId` (string): Unique identifier for the datasource of the VDB.\n      \n  - `datasourceType` (string): The type of the datasource (e.g., \"Postgres\").\n      \n  - `workspaceId` (string): Unique identifier for the workspace to which the group belongs.\n      \n  - `name` (string): The name of the VDB.\n      \n  - `description` (string): Description of the VDB.\n      \n  - `createdAt` (string, ISO 8601 format): Timestamp when the group was created.\n      \n  - `lastModifiedAt` (string, ISO 8601 format): Timestamp when the group was last modified.\n      \n  - `permissionsLastModifiedAt` (string, ISO 8601 format): Timestamp when the policies attached to the VDB were last modified.\n      \n  - `image` (Base64-encoded string): binary image data; decode to retrieve the original image (returned if `enrich` is `true`).\n

💡 The response also has a pagination object: totalRecords, currentPage, totalPages, pageSize, nextPage, prevPage.

This endpoint retrieves the users of a specific group within a workspace.

Path Parameters

workspace_id(string): The unique identifier of the workspace.
\n
group_id (string): The unique identifier of the group.
\n

Request Body

This request does not contain a request body.

Response Body

users: a list of users associated with the group.
\n
- User:
  \n
  - id (string): Unique identifier for the user.
    \n
  - email (string): Email address of the user.
    \n
  - created_at (string, ISO 8601 format): Timestamp when the user was created/joined.
    \n
  - image (string, URL): Link to the user’s profile picture or avatar.
    \n
  \n
- workspaceId (string): Unique identifier for the workspace to which the user belongs.
  \n
- joined_at (string, ISO 8601 format): Timestamp when the user joined the workspace.
  \n
- role (string): Role of the user in the workspace: \"owner,\" \"admin,\" or \"member.\"
  \n
- type (string): The type of the user in the workspace: regular (platform user) or adhoc (service account).
  \n
\n

💡 The response also has a pagination object: totalRecords, currentPage, totalPages, pageSize, nextPage, prevPage.

This endpoint allows to update a specific group in a workspace.

Path Parameters

workspace_id(string): The unique identifier of the workspace.
\n
group_id(string): the unique id of the group in the workspace
\n

Request Body

Form data containing the fields to update:

data (text): Json with the following properties:
\n
- name(string): The name of the group.
  \n
- description(string): The description of the group.
  \n
\n
image (File): The image for the group.
\n

Response Body

Upon successful update, the server returns a status code of 200 and an empty JSON response.

Adds users to a group and removes users from it.

Path Parameters

workspace_id(string): The unique identifier of the workspace.
\n
group_id(string): the unique id of the group in the workspace
\n

Request Body

usersToAdd (array of strings): The IDs of the users to add.
usersToRemove (array of strings): The IDs of the users to remove.

Each array can be empty ([]).

Response Body

Upon successful update, the server returns a status code of 200 and an empty JSON response.

Gives a group access to VDBs, or removes it. All users in the group get the access.

Path Parameters

workspace_id (string): The unique identifier of the workspace.
group_id (string): The group ID.

Request Body

vdbsToAdd (array of strings, required): VDB IDs.
vdbsToRemove (array of strings, required): VDB IDs.

Send both keys. Use [] for an empty list.

Response Body

Status 200 with an empty body.

Requires the workspace admin or owner role.

This endpoint deletes a specific group within a workspace.

Path Parameters

workspace_id(string): The unique identifier of the workspace.
\n
group_id (string): The unique identifier of the group.
\n

Request Body

This request does not contain a request body.

Response Body

Upon successful deletion of the group from the workspace, the server returns a status code of 200 and an empty JSON response.

A group is a collection of users, typically organized based on a shared purpose such as team membership, department, or role within the organization.

Groups provide a convenient way to assign permissions to multiple users simultaneously, enabling consistent and efficient access management aligned with business use cases.

\n","_postman_id":"da074097-cd8b-401f-bb9a-2c94996b9e3a","auth":{"type":"bearer","bearer":{"basicConfig":[{"key":"token","value":"{{token}}"}]},"isInherited":true,"source":{"_postman_id":"230ce1f4-4c29-4006-87b5-45620ae91c61","id":"230ce1f4-4c29-4006-87b5-45620ae91c61","name":"PVML Documentation","type":"collection"}}},{"name":"Attributes","item":[{"name":"Create Attribute Catalog","id":"61fe4aa7-478a-4ed1-9c3b-b3c1d6f1e5bb","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[],"body":{"mode":"raw","raw":"{\n \"name\": \"hr\"\n}","options":{"raw":{"language":"json"}}},"url":"https://platform.pvml.com/platform/api/v1/workspaces/{{workspace_id}}/catalogs","description":"

Creates an attribute catalog. A catalog is a named group of attribute definitions, for example hr or bank. The catalog name is the first part of the attribute name in policies: {{hr.region}}.

Path Parameters

workspace_id (string): The unique identifier of the workspace.

Request Body

name (string, required): The catalog name. It can not contain a dot.
ssoProviderId (string, optional): Link the catalog to an SSO provider. Then attribute values come from your identity provider through SCIM. See Workspaces > Guide: SSO and SCIM setup.
urn (string, optional): The prefix your identity provider uses for these attributes, for example a SCIM extension URN (urn:...). PVML uses it to match incoming attribute values to the definitions in this catalog.

Response Body

The catalog: id, workspaceId, name, isSystem, and ssoProviderId / urn if set. System catalogs are created by PVML and can not be changed.

Requires the workspace admin or owner role.

Lists the attribute catalogs of the workspace.

Path Parameters

workspace_id (string): The unique identifier of the workspace.

Response Body

catalogs (array): Catalog objects.
pagination (object).

Returns one attribute catalog.

Path Parameters

workspace_id (string): The unique identifier of the workspace.
catalog_id (string): The attribute catalog ID.

Updates the name, SSO provider or URN of a catalog.

Path Parameters

workspace_id (string): The unique identifier of the workspace.
catalog_id (string): The attribute catalog ID.

Request Body

The same fields as Create Attribute Catalog.

⚠️ Renaming a catalog changes the attribute names ({{old.x}} becomes {{new.x}}). Update your row policies too.

Requires the workspace admin or owner role.

Deletes an attribute catalog.

Path Parameters

workspace_id (string): The unique identifier of the workspace.
catalog_id (string): The attribute catalog ID.

⚠️ The catalog must be empty. Remove all its attribute definitions first (with Define Attributes, attributesToRemove).

Response Body

Status 200 with an empty body.

Requires the workspace admin or owner role.

Adds, changes or removes attribute definitions in a catalog. A definition sets the name and type of an attribute. Values are set later per user or group.

Path Parameters

workspace_id (string): The unique identifier of the workspace.
catalog_id (string): The attribute catalog ID.

Request Body

attributesToUpsert (array): Definitions to add or change. Each item has:
- name (string, required): The attribute name. It can not contain a dot.
- type (string, required): text, numeric, boolean, date, datetime, timestamp, geometry or complex.
- complexType (object): Only for complex:
  - type (string): The type of each item (for an array) or complex (for an object).
  - multiValued (boolean): true for an array, false for an object.
  - subAttributes (array): For an object, its fields: {\"name\", \"type\"}.
  \n
\n
attributesToRemove (array of strings): Attribute definition IDs to remove.

Attribute types

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Type	Example value	How it looks in SQL
`text`	`\"London\"`	`'London'`
`numeric`	`50000`	`50000`
`boolean`	`true`	`true`
`date` / `datetime` / `timestamp`	`\"2026-01-31\"`	a date or time literal for your database
`geometry`	a WKT string	a geometry literal for your database
`complex`, `multiValued: true` (array)	`[\"London\", \"Paris\"]`	`'London','Paris'` (use it inside `IN (...)`)
`complex`, `multiValued: false` (object)	`{\"city\": \"London\", \"country\": \"GBR\"}`	use one field: `{{catalog.office.city}}`

Response Body

definitions (array): The saved definitions, each with its id. Use the id as attributeId when you set values.

Requires the workspace admin or owner role.

Lists the attribute definitions of a catalog.

Path Parameters

workspace_id (string): The unique identifier of the workspace.
catalog_id (string): The attribute catalog ID.

Response Body

definitions (array): id, catalogId, name, type, complexType.
pagination (object).

Returns one attribute definition.

Path Parameters

workspace_id (string): The unique identifier of the workspace.
catalog_id (string): The attribute catalog ID.
attribute_id (string): The attribute definition ID.

Lists the full names of all attributes in the workspace, as you write them in a row policy (catalog.attribute).

Path Parameters

workspace_id (string): The unique identifier of the workspace.

Response Body

keys (array of strings): For example hr.region. Use them as {{hr.region}}.
pagination (object).

Lists all attributes in the workspace with their types.

Path Parameters

workspace_id (string): The unique identifier of the workspace.

Response Body

attributesMetadata (array): key (full name), type, complexType.
pagination (object).

Sets or removes attribute values for one user. Row policies use these values when this user runs a query.

Path Parameters

workspace_id (string): The unique identifier of the workspace.
user_id (string): The user ID.

Request Body

attributesToUpsert (array): Values to set. Each item has:
- attributeId (string): The attribute definition ID (from Define Attributes).
- value: The value, in the format of the attribute type (see Define Attributes). For example \"EMEA\", 10000, [\"London\", \"Paris\"] or {\"city\": \"London\", \"country\": \"GBR\"}.
\n
attributesToRemove (array of strings): Attribute definition IDs whose value you want to remove.

💡 A user value wins over a group value of the same attribute.

Response Body

Status 200 with an empty body.

Requires the workspace admin or owner role.

Lists the attribute values of a user.

Path Parameters

workspace_id (string): The unique identifier of the workspace.
user_id (string): The user ID.

Response Body

attributes (array). Each item has:
- id (string): The ID of this value. Use it in Get User Attribute and Delete User Attribute.
- attributeId (string): The attribute definition ID.
- name, catalogName, type, complexType, value.
- ssoProviderId (string): Set when the value comes from your identity provider.
\n
pagination (object).

Returns one attribute value of a user.

Path Parameters

workspace_id (string): The unique identifier of the workspace.
user_id (string): The user ID.
user_attribute_value_id (string): The value id from Get User Attributes (not the attribute definition ID).

Removes one attribute value from a user.

Path Parameters

workspace_id (string): The unique identifier of the workspace.
user_id (string): The user ID.
user_attribute_value_id (string): The value id from Get User Attributes.

💡 Values that come from your identity provider can not be deleted here.

Response Body

Status 200 with an empty body.

Requires the workspace admin or owner role.

Sets or removes attribute values for a group. All users in the group get these values, unless the user has their own value.

Path Parameters

workspace_id (string): The unique identifier of the workspace.
group_id (string): The group ID.

Request Body

attributesToUpsert (array): Values to set. Each item has:
- attributeId (string): The attribute definition ID (from Define Attributes).
- value: The value, in the format of the attribute type (see Define Attributes). For example \"EMEA\", 10000, [\"London\", \"Paris\"] or {\"city\": \"London\", \"country\": \"GBR\"}.
\n
attributesToRemove (array of strings): Attribute definition IDs whose value you want to remove.

Response Body

Status 200 with an empty body.

Requires the workspace admin or owner role.

Lists the attribute values of a group. The format is the same as Get User Attributes.

Path Parameters

workspace_id (string): The unique identifier of the workspace.
group_id (string): The group ID.

Returns one attribute value of a group.

Path Parameters

workspace_id (string): The unique identifier of the workspace.
group_id (string): The group ID.
group_attribute_value_id (string): The value id from Get Group Attributes.

Removes one attribute value from a group.

Path Parameters

workspace_id (string): The unique identifier of the workspace.
group_id (string): The group ID.
group_attribute_value_id (string): The value id from Get Group Attributes.

Response Body

Status 200 with an empty body.

Requires the workspace admin or owner role.

Attributes describe your users, for example their region, team or branch. Row policies use them to show each user only their own rows (see Guide: Row-level security (RLS) in the Policies section).

How attributes are organized

Catalog: a named group of attributes, for example hr.
Definition: an attribute inside a catalog, with a type, for example region (text).
Value: the value for one user or one group, for example region = \"EMEA\" for Dana.

In a row policy you write the full name in double curly braces: {{hr.region}}.

[SCREENSHOT: attributes_catalog_definitions.png]

[SCREENSHOT: attributes_user_values.png]

Where values come from

Set them with the API (this section) or in the PVML UI, per user or per group.
From your identity provider: link the catalog to an SSO provider and set up SCIM. PVML updates the values each time your identity provider sends a change. See Workspaces > Guide: SSO and SCIM setup.

Which value wins

A value set on the user.
Otherwise, the value set on the user's group.
Otherwise, the user has no value. Any query that needs it is blocked. This is secure by default: no value means no data.

\n","_postman_id":"973d5edf-9e97-48f6-b5e6-1ef8220d617e","auth":{"type":"bearer","bearer":{"basicConfig":[{"key":"token","value":"{{token}}"}]},"isInherited":true,"source":{"_postman_id":"230ce1f4-4c29-4006-87b5-45620ae91c61","id":"230ce1f4-4c29-4006-87b5-45620ae91c61","name":"PVML Documentation","type":"collection"}}},{"name":"Invite Users","id":"8b6c50e1-30fd-488f-84bc-53f2926783c3","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[],"body":{"mode":"raw","raw":"{\n \"usersToInvite\": [\n \"someone@example.com\"\n ],\n \"userRole\": \"member\",\n \"groupsToAdd\": [\n \"{{group_id}}\"\n ]\n}","options":{"raw":{"language":"json"}}},"url":"https://platform.pvml.com/platform/api/v1/workspaces/{{workspace_id}}/users/invite","description":"

This endpoint allows you to invite users to a workspace by email.

Path Parameters

workspace_id(string): The unique identifier of the workspace.

Request Body

usersToInvite (array): The email addresses to invite.
userRole (string): The role of the new users: member, admin or owner.
groupsToAdd (array, optional): Group IDs to add the new users to.

Response Body

Upon successful invite of the users, the server returns a status code of 200 and an empty JSON response.

Lists invitations that were sent and not used yet. Expired invitations are not listed.

Path Parameters

workspace_id (string): The unique identifier of the workspace.

Response Body

invitations (array): target_user_email, invited_by, workspace_id, expiration_date, created_at. null when there are none.

Requires the workspace admin or owner role.

Cancels the invitation of one email address, so it can no longer be used. PVML does not send an email about it.

Path Parameters

workspace_id (string): The unique identifier of the workspace.

Request Body

target_user_email (string): The invited email address.

Response Body

Status 200 with an empty body.

Requires the workspace admin or owner role.

This endpoint allows you to check if users belong to a workspace using their ids.

Path Parameters

workspace_id(string): The unique identifier of the workspace.

Request Body

usersOfWorkspace: An array containing the user IDs to check whether they belong to the workspace.

Response Body

isPartOfWorkspace (boolean): indicating whether all the specified users belong to the workspace.

Creates a service account in a workspace. In the platform: Users > Create service account.

A service account is for an app, a script or a BI tool. It can not log in to the platform. Give it access to VDBs like any user, then create a REST API key or an ODBC/JDBC connection string for it (see Connections).

💡 In the API, a service account is called adhoc: this endpoint is /users/adhoc, and the user has type: \"adhoc\".

Path Parameters

workspace_id (string): The unique identifier of the workspace.

Request Body

name (string): The name of the service account.

Response Body

id (string): The unique identifier of the service account.
email (string): NAME@WORKSPACE_ID.pvml.com. This is not a real email address.
createdAt (string): When the service account was created (ISO 8601).
image (string): The path to the user's image.

This endpoint retrieves the user associated with a specific workspace.

Path Parameters

workspace_id(string): The unique identifier of the workspace.
\n
user_id (string): The unique identifier of the user.
\n
enrich (boolean, query parameter): when set to true, the request returns additional details such as the user's image.
\n

Request Body

This request does not contain a request body.

Response Body

User:
\n
- id (String): Unique identifier for the user.
  \n
- email (String): Email address of the user.
  \n
- created_at (String, ISO 8601 format): Timestamp when the user was created/joined.
  \n
- image (String, URL): Link to the user’s profile picture or avatar.
  \n
\n
workspaceId (String): Unique identifier for the workspace to which the user belongs.
\n
joined_at: (String, ISO 8601 format) Timestamp when the user joined the workspace.
\n
role: (String) Role of the user in the workspace: \"owner,\" \"admin,\" or \"member.\"
\n
type: (String) The type of the user in the workspace: regular (platform user) or adhoc (service account).
\n

This endpoint retrieves the users associated with a specific workspace.

Path Parameters

workspace_id(string): The unique identifier of the workspace.
\n
enrich (boolean, query parameter): when set to true, the request returns additional details such as the user's image.
\n

Request Body

This request does not contain a request body.

Response Body

workspaceUsers: a list of users associated with a workspace
\n
- User:
  \n
  - id (string): Unique identifier for the user.
    \n
  - email (string): Email address of the user.
    \n
  - created_at (string, ISO 8601 format): Timestamp when the user was created/joined.
    \n
  - image (string, URL): Link to the user’s profile picture or avatar.
    \n
  \n
- workspaceId (string): Unique identifier for the workspace to which the user belongs.
  \n
- joined_at (string, ISO 8601 format): Timestamp when the user joined the workspace.
  \n
- role (string): Role of the user in the workspace: \"owner,\" \"admin,\" or \"member.\"
  \n
- type (string): The type of the user in the workspace: regular (platform user) or adhoc (service account).
  \n
\n

💡 The response also has a pagination object: totalRecords, currentPage, totalPages, pageSize, nextPage, prevPage.

Lists the VDBs a user can access, directly or through groups.

Path Parameters

workspace_id (string): The unique identifier of the workspace.
user_id (string): The user ID.

Response Body

vdbs (array): VDB objects (vdbId, name, description, datasourceId, datasourceType, createdAt, ...).
pagination (object).

Lists the groups of a user.

Path Parameters

workspace_id (string): The unique identifier of the workspace.
user_id (string): The user ID.

Response Body

groups (array): id, name, description, workspaceId, createdAt, lastModifiedAt.
pagination (object).

This endpoint retrieves the role associated with a specific user in a workspace.

Path Parameters

workspace_id(string): The unique identifier of the workspace.
\n
user_id(string): the unique id of the user in the workspace
\n

Request Body

This request does not contain a request body.

Response Body

userRole (string): The user's role in the workspace (member / admin / owner)

Adds a user to groups or removes them from groups.

Path Parameters

workspace_id (string): The unique identifier of the workspace.
user_id (string): The user ID.

Request Body

groupsToAdd (array of strings): Group IDs.
groupsToRemove (array of strings): Group IDs.

At least one list must have an item.

Response Body

Status 201 with an empty body.

Requires the workspace admin or owner role.

Gives a user direct access to VDBs, or removes it.

Path Parameters

workspace_id (string): The unique identifier of the workspace.
user_id (string): The user ID.

Request Body

vdbsToAdd (array of strings, required): VDB IDs.
vdbsToRemove (array of strings, required): VDB IDs.

Send both keys. Use [] for an empty list.

💡 This is the same as Update Virtual DB Users, seen from the user side. A user also gets access to the VDBs of their groups.

Response Body

Status 200 with an empty body.

Requires the workspace admin or owner role.

This endpoint allows to change the role of a specific user in a workspace.

Path Parameters

workspace_id(string): The unique identifier of the workspace.
\n
user_id(string): the unique id of the user in the workspace
\n

Request Body

role (string): The user's new role in the workspace: member, admin or owner.

Response Body

Upon successful update, the server returns a status code of 201 and an empty JSON response.

Removes one user from a workspace. Use your own user ID to leave the workspace. Admins can also use it to remove a member. To remove several users at once, use Remove Users from Workspace. The workspace itself is not deleted.

Path Parameters

workspace_id (string): The unique identifier of the workspace.
\n
user_id(string): the unique id of the user in the workspace
\n

Request Body

This request does not contain a request body.

Response Body

Upon successful deletion of the user from the workspace, the server returns a status code of 200 and an empty JSON response.

Removes one or more users from the workspace.

In the platform: Users, then Remove user in the user's menu.

Path Parameters

workspace_id (string): The unique identifier of the workspace.

Request Body

usersToRemove (array of strings): The user IDs to remove.

Response Body

Status 200 with an empty body.

Good to know

Regular users keep their PVML account and their other workspaces. They lose all access in this workspace.
Service accounts are deleted.
You can not remove yourself. To leave a workspace, use Leave Workspace.

Requires the workspace admin or owner role.

PVML has two kinds of users:

Users: people invited by email. They log in to the platform and can also use the API.
Service accounts: for apps, scripts and BI tools. They can not log in to the platform. They connect with a REST API key or an ODBC/JDBC connection string (see Connections). In the platform: Create service account.

💡 Names in the API: a user has type: \"regular\", a service account has type: \"adhoc\". The endpoint to create a service account is /users/adhoc.

\n $\"Invite%20users%20to%20the%20workspace%20or%20create%20service%20accounts.\"$ \n\n

Users and service accounts can be managed one by one or in groups.

💡 What does a service account look like?

When you create a service account, the name you give is converted to an \"email\" with the following format: NAME@WORKSPACE_ID.pvml.com (note: this is not a real email, it cannot be used to log into the platform). The user is assigned an id just like a regular user.

💡 How can I get my user id?

To get a user ID, open the Users page (under Data Access) and copy the user ID.

What Can Each User Role Do?

Member:
\n
- Get a connection string from a VDB they have access to.
  \n
- Access the Notebook app on the PVML platform.
  \n
- Request access. Admins see the requests under the bell icon at the top right of the platform. See Access Requests.
  \n
\n
Admin: Everything members can do, plus:
\n
- Fully configure resources such as datasources, policies, VDBs and LLMs.
  \n
- Invite/create users.
  \n
- Approve or decline access requests (the bell icon at the top right). This also works with the API, so you can build your own approval flow, for example a Slack bot.
  \n
\n
Owner: Everything admins can do, plus:
\n
- Deleting a workspace.
\n

\n","_postman_id":"525391b6-eb75-4d9d-af69-0ba429ca67e6","auth":{"type":"bearer","bearer":{"basicConfig":[{"key":"token","value":"{{token}}"}]},"isInherited":true,"source":{"_postman_id":"230ce1f4-4c29-4006-87b5-45620ae91c61","id":"230ce1f4-4c29-4006-87b5-45620ae91c61","name":"PVML Documentation","type":"collection"}}},{"name":"Access Requests","item":[{"name":"Tutorial: Build access requests in Slack","item":[],"id":"3aceca6a-7051-4c07-801d-442fea5a8922","description":"

Build a Slack app that lets people ask for data access in Slack, and lets data owners approve it with one click. By the end, you have a working app that you own and can adapt to your company's process.

Time: about 30 minutes. Level: you are comfortable with Python and Slack app settings.

What you will build

A Slack app called PVML Access with these commands:

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Command	What it does	PVML API used
`/access`	Lists the groups people can ask for.	Get Groups
`/access <group>`	Asks to join a group. Data owners approve or reject it in a channel. After an approval, the user gets the MCP servers of the group's VDBs.	Request to Join a Group, Approve or Reject Request, Get Group VDBs, Get MCPs
`/access-like @teammate`	Asks for the same groups as a teammate. Good for a new team member. Data owners see the groups and approve or reject.	Get User Groups, Request Same Groups as Another User, Approve or Reject Request, Get User VDBs, Get MCPs
`/my-vdbs`	Lists the user's VDBs and their MCP servers.	Get User VDBs, Get MCPs
`/my-groups`	Lists the user's groups.	Get User Groups
`/connection <VDB> [days]`	Asks for an ODBC/JDBC connection string. The data owner picks how long it is valid. The user sees it once, in a private pop-up.	Create ODBC/JDBC Connection String

Example: Dana, a new analyst, types /access finance analysts. Noa, a data owner, clicks Approve in the owners' channel. PVML adds Dana to the group, and Dana gets the MCP server of the finance VDB in a direct message. A minute later she asks her first question in her AI client. Every answer follows the VDB's policies.

Before you begin

You need:

A PVML workspace where you are an admin.
A Slack workspace where you can create and install apps.
Python 3.9 or newer.
For production: a place to run a small, always-on service, for example a VM with Docker or a Kubernetes cluster. The app is light (about 0.1 CPU and 256 MB of memory), so the smallest VM is enough, often a free-tier one. It needs no public URL.

People use the app with their Slack email. They must be users in the PVML workspace with the same email (invite them, or sync them with SCIM: see Workspaces > Guide: SSO and SCIM setup).

Step 1: Prepare PVML

Create a service account for the app, for example slack-access-bot (Create Service Account). Copy its user ID.
Give it the admin role (Update User Role). Only admins can approve requests.
Create a REST API key for it (Create User API Key). Set a long expiry, for example 1 year. Copy the key and its tokenId.
Check that each team has a group, and that the group has the right VDBs (Update Group VDBs). People ask for groups, not for single VDBs.

⚠️ The app acts with this account's admin rights. Keep the key in a secret manager, and choose your approvers carefully (Step 3).

Step 2: Create the Slack app

Go to api.slack.com/apps and click Create New App > From an app manifest. Pick your workspace and paste:

display_information:\n  name: PVML Access\n  description: Ask for PVML data access and approve it in Slack\nfeatures:\n  bot_user:\n    display_name: PVML Access\n    always_online: false\n  slash_commands:\n    - command: /access\n      description: Ask for access to a PVML group\n      usage_hint: \"[group name], or leave empty to see the groups\"\n      should_escape: false\n    - command: /access-like\n      description: Ask for the same PVML groups as a teammate\n      usage_hint: \"@teammate\"\n      should_escape: true\n    - command: /connection\n      description: Ask for an ODBC/JDBC connection to one of your VDBs\n      usage_hint: \"[VDB name] [days, optional]\"\n      should_escape: false\n    - command: /my-vdbs\n      description: Your PVML VDBs and their MCP servers\n      should_escape: false\n    - command: /my-groups\n      description: Your PVML groups\n      should_escape: false\noauth_config:\n  scopes:\n    bot:\n      - commands\n      - chat:write\n      - users:read\n      - users:read.email\nsettings:\n  interactivity:\n    is_enabled: true\n  org_deploy_enabled: false\n  socket_mode_enabled: true\n  token_rotation_enabled: false\n

Basic Information > App-Level Tokens: generate a token with the connections:write scope. Copy it (xapp-...).
Install App: install the app to your workspace. Copy the Bot User OAuth Token (xoxb-...).
Invite the app to the data owners' channel: /invite @PVML Access.

The manifest turns on Socket Mode, so the app connects out to Slack and needs no public URL or open ports.

Step 3: Add the code and settings

Install the libraries:

pip install slack_bolt requests\n

Set these environment variables:

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Variable	Value
`SLACK_BOT_TOKEN`	The bot token (`xoxb-...`)
`SLACK_APP_TOKEN`	The app-level token (`xapp-...`)
`SLACK_APPROVAL_CHANNEL`	The channel ID of the data owners
`SLACK_APPROVERS`	Slack member IDs of the people who may approve, comma-separated
`PVML_BASE_URL`	Optional. Your PVML address, for self-hosted PVML (default `https://platform.pvml.com`)
`PVML_WORKSPACE_ID`	Your workspace ID
`PVML_API_KEY`	The API key from Step 1
`PVML_BOT_USER_ID`	The user ID of the service account from Step 1
`PVML_API_KEY_ID`	Optional. The key's `tokenId`. The app then warns the owners 7 days before the key expires.
`CONN_DEFAULT_DAYS`	Optional. Connection string expiry when nobody picks one (default `30`)
`CONN_MAX_DAYS`	Optional. Longest connection string expiry (default `90`)

Make a new folder for the app. Save this code in it as bot.py:

import os, re, json, time, threading, requests\nfrom slack_bolt import App\nfrom slack_bolt.adapter.socket_mode import SocketModeHandler\nfrom slack_sdk.errors import SlackApiError\n\nPVML = os.environ.get(\"PVML_BASE_URL\", \"https://platform.pvml.com\") + \"/platform/api/v1\"\nWS = os.environ[\"PVML_WORKSPACE_ID\"]\nBOT_USER = os.environ[\"PVML_BOT_USER_ID\"]        # user ID of the bot's service account\nHEADERS = {\"Authorization\": \"Bearer \" + os.environ[\"PVML_API_KEY\"]}\nCHANNEL = os.environ[\"SLACK_APPROVAL_CHANNEL\"]   # channel of the data owners\nAPPROVERS = set(os.environ[\"SLACK_APPROVERS\"].split(\",\"))  # Slack user IDs who may approve\n\napp = App(token=os.environ[\"SLACK_BOT_TOKEN\"])\nDEFAULT_DAYS = int(os.environ.get(\"CONN_DEFAULT_DAYS\", \"30\"))   # connection string expiry if nobody picks one\nMAX_DAYS = int(os.environ.get(\"CONN_MAX_DAYS\", \"90\"))           # longest expiry anyone can get\nKEY_ID = os.environ.get(\"PVML_API_KEY_ID\", \"\")                  # ID of the bot's API key, to warn before it expires\nWARN_DAYS = 7\n\n\nclass KeyRejected(Exception):\n    pass\n\n\ndef pvml(method, path, **kw):\n    r = requests.request(method, f\"{PVML}/workspaces/{WS}{path}\", headers=HEADERS, timeout=30, **kw)\n    if r.status_code == 401:\n        raise KeyRejected()\n    r.raise_for_status()\n    return r.json() if r.text.strip() not in (\"\", \"null\") else None\n\n\ndef find_user(email):\n    users = pvml(\"GET\", \"/users\", params={\"searchText\": email})[\"workspaceUsers\"]\n    return next((u[\"User\"][\"id\"] for u in users if u[\"User\"][\"email\"].lower() == email.lower()), None)\n\n\ndef clean(text):\n    # Remove Slack formatting (*bold*, _italic_, ~strike~, `code`) and quotes that people copy with a name\n    return \" \".join(text.strip(\"*_~`'\\\" \").split())\n\n\ndef slack_user_to_pvml(client, slack_user):\n    email = client.users_info(user=slack_user)[\"user\"][\"profile\"].get(\"email\", \"\")\n    return email, (find_user(email) if email else None)\n\n\nMCP_HELP = (\"Add a URL as a custom connector (MCP server) in your AI client, for example Claude, \"\n            \"ChatGPT or Cursor, and sign in with your company account. The AI sees only what you can see.\")\n\n\ndef mcp_lines(vdbs):\n    mcps = {m[\"internalReferences\"][\"vdbId\"]: m[\"url\"] for m in (pvml(\"GET\", \"/mcps\")[\"mcps\"] or [])}\n    return [f\"- *{v['name']}*: {mcps[v['vdbId']]}\" for v in vdbs if v[\"vdbId\"] in mcps]\n\n\ndef ask_owners(client, respond, text, blocks):\n    # Post to the owners' channel. Returns False (and tells the user) if the bot can not post there.\n    try:\n        client.chat_postMessage(channel=CHANNEL, text=text, blocks=blocks)\n        return True\n    except SlackApiError as e:\n        print(f\"Can not post to {CHANNEL}: {e.response['error']} (is the bot invited to the channel?)\")\n        respond(\"Sorry, I could not reach the data owners. Please tell your PVML admin.\")\n        return False\n\n\ndef find_group(name):\n    groups = pvml(\"GET\", \"/groups\")[\"groups\"]\n    return next((g for g in groups if g[\"name\"].lower() == name.lower()), None), [g[\"name\"] for g in groups]\n\n\ndef decision_buttons(text, value):\n    return [{\"type\": \"section\", \"text\": {\"type\": \"mrkdwn\", \"text\": text}},\n            {\"type\": \"actions\", \"elements\": [\n                {\"type\": \"button\", \"text\": {\"type\": \"plain_text\", \"text\": \"Approve\"}, \"style\": \"primary\",\n                 \"action_id\": \"approve\", \"value\": value},\n                {\"type\": \"button\", \"text\": {\"type\": \"plain_text\", \"text\": \"Reject\"}, \"style\": \"danger\",\n                 \"action_id\": \"reject\", \"value\": value}]}]\n\n\ndef done(client, channel, ts, text):\n    # Replace the buttons with the final text\n    client.chat_update(channel=channel, ts=ts, text=text,\n                       blocks=[{\"type\": \"section\", \"text\": {\"type\": \"mrkdwn\", \"text\": text}}])\n\n\n@app.command(\"/access\")\ndef request_access(ack, command, client, respond):\n    ack()\n    group_name = clean(command[\"text\"])\n    if not group_name:  # \"/access\" alone lists the groups\n        groups = pvml(\"GET\", \"/groups\")[\"groups\"]\n        lines = [f\"- *{g['name']}*\" + (f\": {g['description']}\" if g.get(\"description\") else \"\") for g in groups]\n        return respond(\"Groups you can ask for:\\n\" + \"\\n\".join(lines) + \"\\nType `/access <group name>`, \"\n                       \"or `/access-like @teammate` to ask for the same groups as a teammate.\")\n    email, user_id = slack_user_to_pvml(client, command[\"user_id\"])\n    if not user_id:\n        return respond(f\"You are not a user in PVML yet ({email}). Ask an admin to invite you.\")\n    group, all_groups = find_group(group_name)\n    if not group:\n        return respond(f\"No group named '{group_name}'. Groups: {', '.join(all_groups)}\")\n    event = pvml(\"POST\", f\"/groups/{group['id']}/events/join\",\n                 json={\"userToAdd\": user_id, \"senderId\": BOT_USER})[\"Event\"]\n    text = f\"<@{command['user_id']}> asks to join *{group['name']}* in PVML.\"\n    value = json.dumps({\"event\": event[\"id\"], \"requester\": command[\"user_id\"], \"group\": group[\"id\"]})\n    if not ask_owners(client, respond, text, decision_buttons(text, value)):\n        return pvml(\"DELETE\", f\"/cancel/{event['id']}\")  # nobody can approve it, so cancel the PVML request\n    respond(f\"Your request to join *{group['name']}* was sent to the data owners.\")\n\n\n@app.command(\"/access-like\")\ndef request_same_access(ack, command, client, respond):\n    ack()\n    tag = re.search(r\"<@(\\w+)(?:\\|[^>]*)?>\", command[\"text\"])  # Slack sends a tagged person as <@U123|name>\n    if not tag:\n        return respond(\"Type `/access-like @teammate` to ask for the same groups as a teammate.\")\n    teammate = tag.group(1)\n    if teammate == command[\"user_id\"]:\n        return respond(\"Tag a teammate, not yourself.\")\n    email, user_id = slack_user_to_pvml(client, command[\"user_id\"])\n    if not user_id:\n        return respond(f\"You are not a user in PVML yet ({email}). Ask an admin to invite you.\")\n    _, teammate_id = slack_user_to_pvml(client, teammate)\n    if not teammate_id:\n        return respond(f\"<@{teammate}> is not a user in PVML.\")\n    names = [g[\"name\"] for g in pvml(\"GET\", f\"/users/{teammate_id}/groups\")[\"groups\"] or []]\n    if not names:\n        return respond(f\"<@{teammate}> is not in any group yet, so there is nothing to ask for.\")\n    event = pvml(\"POST\", f\"/users/{user_id}/events/copy-groups\",\n                 json={\"sourceUser\": teammate_id, \"senderId\": BOT_USER})[\"Event\"]\n    text = (f\"<@{command['user_id']}> asks for the same groups as <@{teammate}> in PVML: \"\n            + \", \".join(f\"*{n}*\" for n in names) + \".\")\n    value = json.dumps({\"event\": event[\"id\"], \"requester\": command[\"user_id\"], \"user\": user_id})\n    if not ask_owners(client, respond, text, decision_buttons(text, value)):\n        return pvml(\"DELETE\", f\"/cancel/{event['id']}\")\n    respond(f\"Your request for the same groups as <@{teammate}> was sent to the data owners.\")\n\n\nREASON_BOX = {\"type\": \"input\", \"block_id\": \"reason\", \"optional\": True,\n              \"label\": {\"type\": \"plain_text\", \"text\": \"Reason, if you reject (optional)\"},\n              \"element\": {\"type\": \"plain_text_input\", \"action_id\": \"text\", \"max_length\": 300,\n                          \"placeholder\": {\"type\": \"plain_text\", \"text\": \"The requester sees it\"}}}\n\n\ndef typed_reason(body):\n    # The text an approver typed in the reason box of the request message\n    return next((e.get(\"value\") or \"\" for b in body.get(\"state\", {}).get(\"values\", {}).values()\n                 for e in b.values() if e.get(\"type\") == \"plain_text_input\"), \"\").strip()\n\n\ndef reason_note(reason):\n    return f\"\\nReason: {reason}\" if reason else \"\"\n\n\ndef decide(client, approver, info, channel, ts, text, result, reason=\"\"):\n    if approver not in APPROVERS:\n        return client.chat_postEphemeral(channel=channel, user=approver, text=\"Only data owners can approve requests.\")\n    status = pvml(\"GET\", f\"/events/eventId/{info['event']}\")[\"event\"][\"status\"]\n    if status != \"pending\":\n        return done(client, channel, ts, f\"{text}\\nAlready handled in PVML: *{status}*.\")\n    try:\n        pvml(\"POST\", f\"/resolve/{info['event']}/by/{BOT_USER}\", json={\"result\": result})\n    except requests.HTTPError:  # another approver was faster: the first decision wins\n        status = pvml(\"GET\", f\"/events/eventId/{info['event']}\")[\"event\"][\"status\"]\n        return done(client, channel, ts, f\"{text}\\nAlready handled in PVML: *{status}*.\")\n    done(client, channel, ts, f\"{text}\\n*{result.capitalize()}* by <@{approver}>.\" + reason_note(reason))\n    dm = f\"Your data access request was {result}.\" + reason_note(reason)\n    if result == \"approved\":\n        if \"group\" in info:  # /access: the VDBs of the new group\n            lines, title = mcp_lines(pvml(\"GET\", f\"/groups/{info['group']}/vdbs\")[\"vdbs\"] or []), \"Your new VDBs\"\n        else:  # /access-like: all the user's VDBs now\n            lines, title = mcp_lines(pvml(\"GET\", f\"/users/{info['user']}/vdbs\")[\"vdbs\"] or []), \"Your VDBs\"\n        if lines:\n            dm += f\"\\n{title} and their MCP servers:\\n\" + \"\\n\".join(lines) + \"\\n\" + MCP_HELP\n    client.chat_postMessage(channel=info[\"requester\"], text=dm)\n\n\n@app.action(\"approve\")\ndef approve(ack, body, client):\n    ack()\n    decide(client, body[\"user\"][\"id\"], json.loads(body[\"actions\"][0][\"value\"]),\n           body[\"channel\"][\"id\"], body[\"message\"][\"ts\"], body[\"message\"][\"text\"], \"approved\")\n\n\n@app.action(\"reject\")\n@app.action(\"conn_reject\")\ndef show_reason_box(ack, body, client):\n    # First Reject click: add the reason box to the card and turn Reject into \"Confirm reject\"\n    ack()\n    approver, channel = body[\"user\"][\"id\"], body[\"channel\"][\"id\"]\n    if approver not in APPROVERS:\n        return client.chat_postEphemeral(channel=channel, user=approver, text=\"Only data owners can approve requests.\")\n    blocks = body[\"message\"][\"blocks\"]\n    actions = blocks[-1]\n    for e in actions[\"elements\"]:\n        if e.get(\"action_id\") in (\"reject\", \"conn_reject\"):\n            e[\"action_id\"] += \"_final\"\n            e[\"text\"][\"text\"] = \"Confirm reject\"\n    client.chat_update(channel=channel, ts=body[\"message\"][\"ts\"], text=body[\"message\"][\"text\"],\n                       blocks=blocks[:-1] + [REASON_BOX, actions])\n\n\n@app.action(\"reject_final\")\ndef reject(ack, body, client):\n    ack()\n    decide(client, body[\"user\"][\"id\"], json.loads(body[\"actions\"][0][\"value\"]), body[\"channel\"][\"id\"],\n           body[\"message\"][\"ts\"], body[\"message\"][\"text\"], \"rejected\", typed_reason(body))\n\n\n@app.command(\"/my-vdbs\")\ndef my_vdbs(ack, command, client, respond):\n    ack()\n    email, user_id = slack_user_to_pvml(client, command[\"user_id\"])\n    if not user_id:\n        return respond(f\"You are not a user in PVML yet ({email}). Ask an admin to invite you.\")\n    lines = mcp_lines(pvml(\"GET\", f\"/users/{user_id}/vdbs\")[\"vdbs\"] or [])\n    if not lines:\n        return respond(\"You have no VDBs yet. Ask for a group with `/access`.\")\n    respond(\"Your VDBs and their MCP servers:\\n\" + \"\\n\".join(lines) + \"\\n\" + MCP_HELP)\n\n\n@app.command(\"/my-groups\")\ndef my_groups(ack, command, client, respond):\n    ack()\n    email, user_id = slack_user_to_pvml(client, command[\"user_id\"])\n    if not user_id:\n        return respond(f\"You are not a user in PVML yet ({email}). Ask an admin to invite you.\")\n    groups = pvml(\"GET\", f\"/users/{user_id}/groups\")[\"groups\"] or []\n    if not groups:\n        return respond(\"You are not in any group yet. Type `/access` to see the groups you can ask for.\")\n    respond(\"Your groups:\\n\" + \"\\n\".join(f\"- *{g['name']}*\" for g in groups))\n\n\n# ---------- ODBC / JDBC connection strings ----------\ndef days_option(days):\n    return {\"text\": {\"type\": \"plain_text\", \"text\": f\"{days} days\"}, \"value\": str(days)}\n\n\n@app.command(\"/connection\")\ndef request_connection(ack, command, client, respond):\n    ack()\n    text = clean(command[\"text\"])\n    name, _, last = text.rpartition(\" \")\n    vdb_name, days = (clean(name), int(last)) if last.isdigit() and name else (text, DEFAULT_DAYS)\n    days = max(1, min(days, MAX_DAYS))\n    email, user_id = slack_user_to_pvml(client, command[\"user_id\"])\n    if not user_id:\n        return respond(f\"You are not a user in PVML yet ({email}). Ask an admin to invite you.\")\n    vdbs = pvml(\"GET\", f\"/users/{user_id}/vdbs\")[\"vdbs\"] or []\n    vdb = next((v for v in vdbs if v[\"name\"].lower() == vdb_name.lower()), None)\n    if not vdb:\n        names = \", \".join(v[\"name\"] for v in vdbs) or \"none yet (ask for a group with `/access`)\"\n        return respond(f\"Type `/connection <VDB name> [days]`. Your VDBs: {names}\")\n    value = json.dumps({\"vdb\": vdb[\"vdbId\"], \"name\": vdb[\"name\"], \"user\": user_id, \"requester\": command[\"user_id\"]})\n    msg = f\"<@{command['user_id']}> asks for an ODBC/JDBC connection to *{vdb['name']}*. Pick how long it is valid:\"\n    choices = sorted({7, 30, 90, days} - {d for d in (7, 30, 90) if d > MAX_DAYS})\n    if not ask_owners(client, respond, msg, [\n        {\"type\": \"section\", \"text\": {\"type\": \"mrkdwn\", \"text\": msg}},\n        {\"type\": \"actions\", \"elements\": [\n            {\"type\": \"static_select\", \"action_id\": \"conn_days\", \"initial_option\": days_option(days),\n             \"options\": [days_option(d) for d in choices]},\n            {\"type\": \"button\", \"text\": {\"type\": \"plain_text\", \"text\": \"Approve\"}, \"style\": \"primary\",\n             \"action_id\": \"conn_approve\", \"value\": value},\n            {\"type\": \"button\", \"text\": {\"type\": \"plain_text\", \"text\": \"Reject\"}, \"style\": \"danger\",\n             \"action_id\": \"conn_reject\", \"value\": value}]}]):\n        return\n    respond(f\"Your request for a connection to *{vdb['name']}* ({days} days) was sent to the data owners.\")\n\n\n@app.action(\"conn_days\")\ndef pick_days(ack):\n    ack()  # the choice is read when the owner clicks Approve\n\n\n@app.action(\"conn_approve\")\n@app.action(\"conn_reject_final\")\ndef decide_connection(ack, body, client):\n    ack()\n    approver, action = body[\"user\"][\"id\"], body[\"actions\"][0]\n    info = json.loads(action[\"value\"])\n    channel, ts, text = body[\"channel\"][\"id\"], body[\"message\"][\"ts\"], body[\"message\"][\"text\"]\n    if approver not in APPROVERS:\n        return client.chat_postEphemeral(channel=channel, user=approver, text=\"Only data owners can approve requests.\")\n    if action[\"action_id\"] == \"conn_reject_final\":\n        reason = reason_note(typed_reason(body))\n        done(client, channel, ts, f\"{text}\\n*Rejected* by <@{approver}>.\" + reason)\n        return client.chat_postMessage(channel=info[\"requester\"],\n                                       text=f\"Your connection request for *{info['name']}* was rejected.\" + reason)\n    picked = [e[\"selected_option\"][\"value\"] for b in body[\"state\"][\"values\"].values()\n              for e in b.values() if e.get(\"type\") == \"static_select\" and e.get(\"selected_option\")]\n    days = min(int(picked[0]) if picked else DEFAULT_DAYS, MAX_DAYS)\n    done(client, channel, ts, f\"{text}\\n*Approved* for {days} days by <@{approver}>.\")\n    note = (f\"Your connection to *{info['name']}* was approved for {days} days. \"\n            \"The details are secret: they are shown once, only to you.\")\n    client.chat_postMessage(channel=info[\"requester\"], text=note, blocks=[\n        {\"type\": \"section\", \"text\": {\"type\": \"mrkdwn\", \"text\": note}},\n        {\"type\": \"actions\", \"elements\": [{\"type\": \"button\", \"action_id\": \"conn_show\", \"style\": \"primary\",\n                                          \"text\": {\"type\": \"plain_text\", \"text\": \"Show my connection details\"},\n                                          \"value\": json.dumps({**info, \"days\": days})}]}])\n\n\nLABELS = {\"host\": \"Host\", \"url\": \"JDBC URL / Connection URL\", \"httpPath\": \"HTTP Path\", \"accessToken\": \"Access Token\",\n          \"token\": \"Token\", \"credentialFile\": \"JSON key file (save it as client.json)\"}\n\n\n@app.action(\"conn_show\")\ndef show_connection(ack, body, client):\n    ack()\n    info = json.loads(body[\"actions\"][0][\"value\"])\n    if body[\"user\"][\"id\"] != info[\"requester\"]:\n        return\n    view = client.views_open(trigger_id=body[\"trigger_id\"], view={  # must open within 3 seconds\n        \"type\": \"modal\", \"title\": {\"type\": \"plain_text\", \"text\": \"Connection details\"},\n        \"blocks\": [{\"type\": \"section\", \"text\": {\"type\": \"mrkdwn\", \"text\": \"Creating your connection...\"}}]})[\"view\"]\n    expiry = int((time.time() + info[\"days\"] * 86400) * 1000)\n    conn = pvml(\"POST\", f\"/vdbs/{info['vdb']}/users/{info['user']}/connection_strings\",\n                json={\"name\": f\"slack: {info['name']}\", \"description\": \"Created by the PVML Access Slack bot\",\n                      \"expiration\": expiry})[\"DataSourceConnectionInfo\"]\n    blocks = [{\"type\": \"section\", \"text\": {\"type\": \"mrkdwn\", \"text\":\n               f\"*{info['name']}*, valid for {info['days']} days. Copy these into your tool now: \"\n               \"you can not see them again.\"}}]\n    for key, val in conn.items():\n        if key == \"credentialFile\":  # one line, so copying from Slack keeps it valid JSON\n            try:\n                val = json.dumps(json.loads(val))\n            except ValueError:\n                pass\n        if val:\n            blocks.append({\"type\": \"section\", \"text\": {\"type\": \"mrkdwn\",\n                           \"text\": f\"*{LABELS.get(key, key)}*\\n```{val}```\"[:3000]}})\n    client.views_update(view_id=view[\"id\"], view={\n        \"type\": \"modal\", \"title\": {\"type\": \"plain_text\", \"text\": \"Connection details\"},\n        \"close\": {\"type\": \"plain_text\", \"text\": \"Done\"}, \"blocks\": blocks})\n    done(client, body[\"channel\"][\"id\"], body[\"message\"][\"ts\"],\n         f\"Your connection to *{info['name']}* was created (valid for {info['days']} days). \"\n         \"Lost the details? Ask again with `/connection`.\")\n\n\n# ---------- the bot's own PVML key: warn before it expires, fail clearly if it stops working ----------\n_last_alert = {\"rejected\": 0.0, \"expiry\": 0.0}\n\n\ndef alert_owners(kind, text, every_seconds):\n    if time.time() - _last_alert[kind] < every_seconds:\n        return\n    _last_alert[kind] = time.time()\n    try:\n        app.client.chat_postMessage(channel=CHANNEL, text=text)\n    except Exception as e:\n        print(f\"Can not alert the data owners: {e}\")\n\n\n@app.error\ndef on_error(error, body):\n    if not isinstance(error, KeyRejected):\n        print(f\"Error: {error}\")\n        return\n    alert_owners(\"rejected\", \":warning: My PVML API key does not work anymore (expired or revoked). \"\n                 \"Access requests are paused. A PVML admin must give me a new key.\", 3600)\n    if body.get(\"response_url\"):\n        requests.post(body[\"response_url\"], timeout=10, json={\"response_type\": \"ephemeral\", \"text\":\n                      \"Access requests are paused for a moment. The data owners were told.\"})\n\n\ndef check_key_expiry():\n    if not KEY_ID:\n        return\n    try:\n        keys = pvml(\"GET\", \"/token\")[\"tokensMetadata\"] or []\n    except KeyRejected:\n        return alert_owners(\"rejected\", \":warning: My PVML API key does not work anymore (expired or revoked). \"\n                            \"Access requests are paused. A PVML admin must give me a new key.\", 3600)\n    key = next((k for k in keys if k[\"Id\"] == KEY_ID), None)\n    if key:\n        days = (key[\"ExpirationDate\"] / 1000 - time.time()) / 86400\n        if days <= WARN_DAYS:\n            day = time.strftime(\"%b %d, %Y\", time.gmtime(key[\"ExpirationDate\"] / 1000))\n            alert_owners(\"expiry\", f\":warning: My PVML API key expires on {day}. \"\n                         \"Please ask a PVML admin to give me a new key before that.\", 86400)\n\n\ndef key_check_loop():\n    check_key_expiry()\n    timer = threading.Timer(12 * 3600, key_check_loop)  # twice a day\n    timer.daemon = True\n    timer.start()\n\n\nif __name__ == \"__main__\":\n    key_check_loop()\n    SocketModeHandler(app, os.environ[\"SLACK_APP_TOKEN\"]).start()\n

Step 4: Run it and check the result

Run python bot.py. The log shows Bolt app is running!.
In Slack, type /access. You see the list of groups.
Type /access and a group name. The request appears in the owners' channel.
As an approver, click Approve. The buttons change to \"Approved by @you\", and you get a direct message with the MCP servers of the group's VDBs. In PVML, the user is now in the group.
Type /access-like and tag a teammate. The request lists the teammate's groups. Approve it, and you are in the same groups.
Type /connection and a VDB name, approve it, and click Show my connection details. The pop-up shows the connection details once.

Step 5: Run it in production

The app is one small, always-on process. Run only one copy: two copies would send each warning twice.

Save two more files in the same folder as bot.py. Each is plain text: open a text editor, paste the block, and save it with the exact name shown.

requirements.txt:

slack_bolt==1.30.0\nrequests==2.34.2\n

Dockerfile, with no file extension (not Dockerfile.txt). It tells Docker how to build the app, and makes it run as an unprivileged user:

FROM python:3.12-slim\nWORKDIR /app\nCOPY requirements.txt .\nRUN pip install --no-cache-dir -r requirements.txt\nCOPY bot.py .\nRUN chmod 644 bot.py\nUSER nobody\nCMD [\"python\", \"-u\", \"bot.py\"]\n

On a VM with Docker: put the settings from Step 3 in a file bot.env in the same folder (one NAME=value per line, readable only by you). Copy the four files to the VM. Then, on the VM:

docker build -t pvml-access-bot .\ndocker run -d --name pvml-access-bot --restart=always --env-file bot.env pvml-access-bot\ndocker logs pvml-access-bot\n

--restart=always starts the app again after a crash or a reboot. When the log shows Bolt app is running!, delete bot.env from the VM (rm bot.env): the container keeps the settings. To update the code, build again and replace the container (docker rm -f pvml-access-bot, then docker run again).

Example: a free-tier VM on Google Cloud. Run these from the app folder on your computer, with the gcloud CLI signed in to a project with billing turned on. This VM should be free. It has Docker built in, no cloud permissions, and SSH only through Google's secure tunnel (IAP).

gcloud services enable compute.googleapis.com iap.googleapis.com\ngcloud compute instances create pvml-access-bot --zone=us-central1-a \\\n  --machine-type=e2-micro --image-family=cos-stable --image-project=cos-cloud \\\n  --boot-disk-type=pd-standard --no-service-account --no-scopes\ngcloud compute firewall-rules create allow-ssh-from-iap --network=default \\\n  --allow=tcp:22 --source-ranges=35.235.240.0/20\ngcloud compute scp bot.py requirements.txt Dockerfile bot.env \\\n  pvml-access-bot:~ --zone=us-central1-a --tunnel-through-iap\ngcloud compute ssh pvml-access-bot --zone=us-central1-a --tunnel-through-iap\n

In the SSH session, run the docker commands above. To close other ways in, you can delete the default rule that allows SSH from anywhere: gcloud compute firewall-rules delete default-allow-ssh. On AWS or Azure, a small VM with Docker works the same way.

On Kubernetes: build the image for your servers and push it to your registry (on an Apple silicon Mac, add --platform linux/amd64):

docker build --platform linux/amd64 -t YOUR_REGISTRY/pvml-access-bot:1.0 .\ndocker push YOUR_REGISTRY/pvml-access-bot:1.0\n

Put the tokens and the PVML key in a secret, and run one copy (k8s.yaml):

# Create the secret first (values from your secret manager), for example:\n# kubectl create secret generic pvml-access-bot \\\n#   --from-literal=SLACK_BOT_TOKEN=xoxb-... --from-literal=SLACK_APP_TOKEN=xapp-... \\\n#   --from-literal=PVML_API_KEY=...\napiVersion: apps/v1\nkind: Deployment\nmetadata:\n  name: pvml-access-bot\nspec:\n  replicas: 1            # run only one copy\n  selector:\n    matchLabels: {app: pvml-access-bot}\n  template:\n    metadata:\n      labels: {app: pvml-access-bot}\n    spec:\n      containers:\n        - name: bot\n          image: YOUR_REGISTRY/pvml-access-bot:1.0\n          envFrom:\n            - secretRef: {name: pvml-access-bot}\n          env:\n            - {name: PVML_BASE_URL, value: \"https://platform.pvml.com\"}\n            - {name: PVML_WORKSPACE_ID, value: \"YOUR_WORKSPACE_ID\"}\n            - {name: PVML_BOT_USER_ID, value: \"BOT_SERVICE_ACCOUNT_ID\"}\n            - {name: SLACK_APPROVAL_CHANNEL, value: \"C0123456789\"}\n            - {name: SLACK_APPROVERS, value: \"U0123456789,U0987654321\"}\n            - {name: CONN_DEFAULT_DAYS, value: \"30\"}\n            - {name: CONN_MAX_DAYS, value: \"90\"}\n          resources:\n            requests: {cpu: 50m, memory: 64Mi}\n            limits: {memory: 256Mi}\n

kubectl apply -f k8s.yaml\nkubectl logs deploy/pvml-access-bot\n

The same container also runs on AWS ECS, Azure Container Apps and similar services.

Troubleshooting

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

What you see	Why	What to do
\"You are not a user in PVML yet\"	The Slack email is not a user in the PVML workspace.	Invite the person to PVML, or sync users with SCIM.
\"I could not reach the data owners\"	The app is not in the owners' channel.	Type `/invite @PVML Access` in that channel.
\"Access requests are paused\"	PVML does not accept the app's key (expired or revoked).	Create a new key (Step 1) and restart the app.
\"Already handled in PVML\"	Another approver, or an admin in the platform, decided first.	Nothing: the first decision counts.
\"API [compute.googleapis.com] not enabled\" (Google Cloud example)	The project has no billing account, so the first command failed.	Link a billing account to the project, then run the commands again.
\"Failed to lookup instance\" on `gcloud compute scp` or `ssh`	The new VM is not ready for the secure tunnel yet, or it was not created.	Run `gcloud compute instances list`. If the VM is there, wait a minute and try again. If not, run the create command again.
A command does nothing	The app is not running, or a new command is missing in Slack.	Check the log. After changing the manifest, save it in the Slack app settings.

Good to know

Who approved? In PVML, the request shows the app's service account as the approver. The Slack message shows who clicked.
Reject with a reason: when an approver clicks Reject, a box opens on the request for an optional reason. They click Confirm reject, and the requester gets the reason in the direct message.
Several approvers: everyone in the channel sees the request. The first decision wins, and the buttons show who decided.
Requests also show in the platform, under the bell icon. Admins can approve there too.
Connection strings are secrets. The app shows them only in a one-time pop-up, never in a message. Admins can see and revoke them under Connections > ODBC / JDBC, and each one stops working on its expiry date.
MCP URLs are not secrets. Each person signs in with their own company account and gets only their own access.
Works with PVML Cloud and self-hosted PVML. The app needs only outbound access to Slack and to PVML, with no open ports. Set PVML_BASE_URL for self-hosted PVML.
One app per PVML workspace. The API key belongs to one workspace. For more workspaces, run one app per workspace, with different command names (for example /access-finance).

Next steps

Make it your own: for example, send requests to your ticketing tool instead of Slack.
Read more about the API calls in Access Requests, Connections > ODBC / JDBC and GenAI > MCP.
Questions about the PVML API? Contact support@pvml.com.

\n","_postman_id":"3aceca6a-7051-4c07-801d-442fea5a8922","auth":{"type":"bearer","bearer":{"basicConfig":[{"key":"token","value":"{{token}}"}]},"isInherited":true,"source":{"_postman_id":"230ce1f4-4c29-4006-87b5-45620ae91c61","id":"230ce1f4-4c29-4006-87b5-45620ae91c61","name":"PVML Documentation","type":"collection"}}},{"name":"Request to Join a Group","id":"c029b26e-b2ef-41cc-a9c1-23546690a816","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[],"body":{"mode":"raw","raw":"{\n \"userToAdd\": \"{{user_id}}\",\n \"senderId\": \"{{user_id}}\"\n}","options":{"raw":{"language":"json"}}},"url":"https://platform.pvml.com/platform/api/v1/workspaces/{{workspace_id}}/groups/{{group_id}}/events/join","description":"

Sends a request to add a user to a group. The admins of the workspace see it under the bell icon, and with Get Requests to Handle.

Path Parameters

workspace_id (string): The unique identifier of the workspace.
group_id (string): The group to join.

Request Body

userToAdd (string): The user to add to the group. Usually the person who asks.
senderId (string): The user who sends the request. Use the user ID of the API key.

Response Body

Event: the new request, with status pending.

id (string): The request ID.
type (string): join_group or copy_groups.
data (string): A JSON string with the details: for join_group the groupId, groupName, userId and email of the user to add; for copy_groups the source and target users.
status (string): pending, approved, rejected or canceled.
senderId, senderEmail: Who asked.
handledById, handledByEmail, handleTime: Who approved or rejected it, and when (empty while pending).
creationTime (string): When it was sent.

Any workspace member can send a request.

Sends a request to give a user the same groups as another user. For example, a new analyst asks for the same access as a teammate.

Path Parameters

workspace_id (string): The unique identifier of the workspace.
user_id (string): The user who gets the groups.

Request Body

sourceUser (string): The user whose groups are copied.
senderId (string): The user who sends the request. Use the user ID of the API key.

Response Body

Event: the new request, with status pending. Same fields as in Request to Join a Group.

When it is approved, the user is added to every group of the source user. Groups the user already has stay as they are.

Lists the requests that an admin can handle: pending ones and the history.

Path Parameters

workspace_id (string): The unique identifier of the workspace.
user_id (string): The admin's own user ID (the user of the API key).

Response Body

events (array):

id (string): The request ID.
type (string): join_group or copy_groups.
data (string): A JSON string with the details: for join_group the groupId, groupName, userId and email of the user to add; for copy_groups the source and target users.
status (string): pending, approved, rejected or canceled.
senderId, senderEmail: Who asked.
handledById, handledByEmail, handleTime: Who approved or rejected it, and when (empty while pending).
creationTime (string): When it was sent.

💡 Show only pending requests in your approval flow.

Requires the workspace admin or owner role.

Lists the requests a user sent, with their status. Use it to show the user if their request was approved.

Path Parameters

workspace_id (string): The unique identifier of the workspace.
user_id (string): Your own user ID (the user of the API key).

Response Body

events (array): same fields as in Get Requests to Handle.

Returns one request.

Path Parameters

workspace_id (string): The unique identifier of the workspace.
event_id (string): The request ID.

Response Body

event: the request. Same fields as in Get Requests to Handle.

Approves or rejects a request. When a request is approved, PVML makes the change right away: it adds the user to the group (or groups).

Path Parameters

workspace_id (string): The unique identifier of the workspace.
event_id (string): The request ID.
user_id (string): The admin who decides: your own user ID (the user of the API key).

Request Body

result (string): approved or rejected.

Response Body

Status 200. Check the new status with Get Request.

Requires the workspace admin or owner role.

Cancels a pending request. Its status becomes canceled.

Path Parameters

workspace_id (string): The unique identifier of the workspace.
event_id (string): The request ID.

Response Body

Status 200.

Returns what a user sees under the bell icon in the platform: new requests, and other messages from the workspace.

Path Parameters

workspace_id (string): The unique identifier of the workspace.
user_id (string): Your own user ID.

Response Body

events (array): same fields as in Get Requests to Handle. Messages that are not requests have other type values.

Removes notifications from the bell. The requests themselves do not change.

Path Parameters

workspace_id (string): The unique identifier of the workspace.
user_id (string): Your own user ID.

Request Body

eventIds (array of strings, required): The notifications to dismiss.

Response Body

dismissedIds (array): The dismissed IDs.

Members can ask for access, and admins approve or reject the request. In the platform, admins see the requests under the bell icon at the top right. With the API, you can build the same flow into your own tools, for example a Slack bot or your ticketing system.

What a member can ask for

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Request	What happens when it is approved
Join a group	The user is added to the group, and gets all the VDBs of that group.
Same groups as another user	The user is added to every group of that user. Good for a new team member.

Build it into your tools

For example, a Slack bot: people type /access finance analysts, and data owners approve with one click. See Access Requests > Tutorial: Build access requests in Slack for a step-by-step tutorial with working code.

Statuses

pending → approved, rejected or canceled.

💡 The user_id in the path and the senderId are the user of the API key: a person, or the service account of a bot. Only admins can approve.

\n","_postman_id":"0e20fbc3-fb1d-4340-96f4-dbf979a302f4","auth":{"type":"bearer","bearer":{"basicConfig":[{"key":"token","value":"{{token}}"}]},"isInherited":true,"source":{"_postman_id":"230ce1f4-4c29-4006-87b5-45620ae91c61","id":"230ce1f4-4c29-4006-87b5-45620ae91c61","name":"PVML Documentation","type":"collection"}}},{"name":"Datasources","item":[{"name":"Datasource CRUD","item":[{"name":"Connect Postgres","id":"5817f9f6-5a52-4b72-becb-ca10e7c96dc9","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[],"body":{"mode":"raw","raw":"{\n \"name\": \"my postgres datasource\",\n \"description\": \"\",\n \"type\": \"Postgres\",\n \"data\": \"{\\\"hostName\\\": \\\"{{postgres_host}}\\\", \\\"port\\\": 5432, \\\"databaseName\\\": \\\"{{postgres_db_name}}\\\", \\\"username\\\": \\\"{{postgres_username}}\\\", \\\"password\\\": \\\"{{postgres_password}}\\\", \\\"tls\\\": true, \\\"trustServerCertificate\\\": false}\"\n}","options":{"raw":{"language":"json"}}},"url":"https://platform.pvml.com/platform/api/v1/workspaces/{{workspace_id}}/datasources","description":"

Connects a Postgres datasource to the workspace.

Path Parameters

workspace_id (string): The unique identifier of the workspace.

Request Body

name (string): The datasource name.
\n
description (string): A short description.
\n
type (string): Postgres.
\n
data (string): The connection details, as a JSON string:
\n
hostName (string): The database host.
\n
port (number): Usually 5432.
\n
databaseName (string).
\n
username, password (string).
\n
tls (boolean): Use TLS. Recommended.
\n
trustServerCertificate (boolean): Accept the server certificate without checking it. Use only for testing.
\n

Or connect with one URL: set urlMode to true and send connectionString (for example postgresql://user:password@host:5432/db) instead of the fields above.

💡 Run Test Datasource Connection first. After you connect, check lastRefreshStatus with Get Datasource.

Response Body

The response is the new datasource object (status 201) with these fields:

id (string): The unique identifier for the datasource.
\n
name (string): The name of the datasource.
\n
description (string): A brief description of the datasource.
\n
type (string): The type of the datasource, in this case: Postgres.
\n
structuredType (string): The type of the datasource used for the unstructured datasource structure (e.g., Postgres, MySQL, etc.).
\n
workspaceId (string): The unique identifier of the workspace.
\n
data (string): Configuration data for the datasource - always empty. To get this information, use the Get Datasource Connection Details API.
\n
snapshotTimestamp (string): The timestamp of the last snapshot taken for the datasource.
\n
lastRefreshTrigger (string): The timestamp of the last refresh trigger for the datasource.
\n
lastRefreshStatus (string): The status of the last refresh operation. Options:
\n
- init
  \n
- indexing
  \n
- failed / completed
  \n
\n

Connects a BigQuery datasource to the workspace.

Path Parameters

workspace_id (string): The unique identifier of the workspace.

Request Body

name (string): The datasource name.
\n
description (string): A short description.
\n
type (string): BigQuery.
\n
data (string): The connection details, as a JSON string:
\n
projectId (string): The Google Cloud project ID.
\n
credentials (string): The full content of the service account JSON key file, as a string.
\n

💡 Run Test Datasource Connection first. After you connect, check lastRefreshStatus with Get Datasource.

Response Body

The response is the new datasource object (status 201) with these fields:

id (string): The unique identifier for the datasource.
\n
name (string): The name of the datasource.
\n
description (string): A brief description of the datasource.
\n
type (string): The type of the datasource, in this case: BigQuery.
\n
structuredType (string): The type of the datasource used for the unstructured datasource structure (e.g., Postgres, MySQL, etc.).
\n
workspaceId (string): The unique identifier of the workspace.
\n
data (string): Configuration data for the datasource - always empty. To get this information, use the Get Datasource Connection Details API.
\n
snapshotTimestamp (string): The timestamp of the last snapshot taken for the datasource.
\n
lastRefreshTrigger (string): The timestamp of the last refresh trigger for the datasource.
\n
lastRefreshStatus (string): The status of the last refresh operation. Options:
\n
- init
  \n
- indexing
  \n
- failed / completed
  \n
\n

Connects a Databricks datasource to the workspace.

Path Parameters

workspace_id (string): The unique identifier of the workspace.

Request Body

name (string): The datasource name.
\n
description (string): A short description.
\n
type (string): Databricks.
\n
data (string): The connection details, as a JSON string:
\n
host_name (string): The server hostname of the SQL warehouse.
\n
http_path (string): The HTTP path of the SQL warehouse.
\n
token (string): A Databricks personal access token.
\n

💡 Run Test Datasource Connection first. After you connect, check lastRefreshStatus with Get Datasource.

Response Body

The response is the new datasource object (status 201) with these fields:

id (string): The unique identifier for the datasource.
\n
name (string): The name of the datasource.
\n
description (string): A brief description of the datasource.
\n
type (string): The type of the datasource, in this case: Databricks.
\n
structuredType (string): The type of the datasource used for the unstructured datasource structure (e.g., Postgres, MySQL, etc.).
\n
workspaceId (string): The unique identifier of the workspace.
\n
data (string): Configuration data for the datasource - always empty. To get this information, use the Get Datasource Connection Details API.
\n
snapshotTimestamp (string): The timestamp of the last snapshot taken for the datasource.
\n
lastRefreshTrigger (string): The timestamp of the last refresh trigger for the datasource.
\n
lastRefreshStatus (string): The status of the last refresh operation. Options:
\n
- init
  \n
- indexing
  \n
- failed / completed
  \n
\n

Connects a Trino datasource to the workspace.

Path Parameters

workspace_id (string): The unique identifier of the workspace.

Request Body

name (string): The datasource name.
\n
description (string): A short description.
\n
type (string): Trino.
\n
data (string): The connection details, as a JSON string:
\n
address (string): Host and port, for example trino.example.com:443.
\n
username, password (string).
\n
protocol (string): https or http.
\n
customCertificate (string, optional): A CA certificate (PEM) if your server uses a private CA.
\n
clientCertificate, clientKey (string, optional): For mutual TLS.
\n

Or set urlMode to true and send connectionString.

💡 Run Test Datasource Connection first. After you connect, check lastRefreshStatus with Get Datasource.

Response Body

The response is the new datasource object (status 201) with these fields:

id (string): The unique identifier for the datasource.
\n
name (string): The name of the datasource.
\n
description (string): A brief description of the datasource.
\n
type (string): The type of the datasource, in this case: Trino.
\n
structuredType (string): The type of the datasource used for the unstructured datasource structure (e.g., Postgres, MySQL, etc.).
\n
workspaceId (string): The unique identifier of the workspace.
\n
data (string): Configuration data for the datasource - always empty. To get this information, use the Get Datasource Connection Details API.
\n
snapshotTimestamp (string): The timestamp of the last snapshot taken for the datasource.
\n
lastRefreshTrigger (string): The timestamp of the last refresh trigger for the datasource.
\n
lastRefreshStatus (string): The status of the last refresh operation. Options:
\n
- init
  \n
- indexing
  \n
- failed / completed
  \n
\n

Connects a MsSql datasource to the workspace.

Path Parameters

workspace_id (string): The unique identifier of the workspace.

Request Body

name (string): The datasource name.
\n
description (string): A short description.
\n
type (string): MsSql.
\n
data (string): The connection details, as a JSON string:
\n
host (string): The server host.
\n
port (number): Usually 1433.
\n
database (string).
\n
user, password (string).
\n
tls (boolean): Use TLS. Recommended.
\n
trustServerCertificate (boolean): Accept the server certificate without checking it. Use only for testing.
\n

💡 The field names for MSSQL are host, user and database (not hostName, username, databaseName).

💡 Run Test Datasource Connection first. After you connect, check lastRefreshStatus with Get Datasource.

Response Body

The response is the new datasource object (status 201) with these fields:

id (string): The unique identifier for the datasource.
\n
name (string): The name of the datasource.
\n
description (string): A brief description of the datasource.
\n
type (string): The type of the datasource, in this case: MsSql.
\n
structuredType (string): The type of the datasource used for the unstructured datasource structure (e.g., Postgres, MySQL, etc.).
\n
workspaceId (string): The unique identifier of the workspace.
\n
data (string): Configuration data for the datasource - always empty. To get this information, use the Get Datasource Connection Details API.
\n
snapshotTimestamp (string): The timestamp of the last snapshot taken for the datasource.
\n
lastRefreshTrigger (string): The timestamp of the last refresh trigger for the datasource.
\n
lastRefreshStatus (string): The status of the last refresh operation. Options:
\n
- init
  \n
- indexing
  \n
- failed / completed
  \n
\n

Connects a Snowflake datasource to the workspace.

Path Parameters

workspace_id (string): The unique identifier of the workspace.

Request Body

name (string): The datasource name.
\n
description (string): A short description.
\n
type (string): Snowflake.
\n
data (string): The connection details, as a JSON string:
\n
account (string): Your Snowflake account identifier (for example myorg-myaccount).
\n
warehouse (string): The warehouse to run queries on.
\n
username (string): A Snowflake user with key-pair authentication.
\n
privateKey (string): The private key (PEM) of that user.
\n

💡 Run Test Datasource Connection first. After you connect, check lastRefreshStatus with Get Datasource.

Response Body

The response is the new datasource object (status 201) with these fields:

id (string): The unique identifier for the datasource.
\n
name (string): The name of the datasource.
\n
description (string): A brief description of the datasource.
\n
type (string): The type of the datasource, in this case: Snowflake.
\n
structuredType (string): The type of the datasource used for the unstructured datasource structure (e.g., Postgres, MySQL, etc.).
\n
workspaceId (string): The unique identifier of the workspace.
\n
data (string): Configuration data for the datasource - always empty. To get this information, use the Get Datasource Connection Details API.
\n
snapshotTimestamp (string): The timestamp of the last snapshot taken for the datasource.
\n
lastRefreshTrigger (string): The timestamp of the last refresh trigger for the datasource.
\n
lastRefreshStatus (string): The status of the last refresh operation. Options:
\n
- init
  \n
- indexing
  \n
- failed / completed
  \n
\n

Connects a Redshift datasource to the workspace.

Path Parameters

workspace_id (string): The unique identifier of the workspace.

Request Body

name (string): The datasource name.
\n
description (string): A short description.
\n
type (string): Redshift.
\n
data (string): The connection details, as a JSON string:
\n
hostName (string): The cluster endpoint host.
\n
port (number): Usually 5439.
\n
databaseName (string).
\n
username, password (string).
\n
tls, trustServerCertificate (boolean): As for Postgres.
\n

💡 Run Test Datasource Connection first. After you connect, check lastRefreshStatus with Get Datasource.

Response Body

The response is the new datasource object (status 201) with these fields:

id (string): The unique identifier for the datasource.
\n
name (string): The name of the datasource.
\n
description (string): A brief description of the datasource.
\n
type (string): The type of the datasource, in this case: Redshift.
\n
structuredType (string): The type of the datasource used for the unstructured datasource structure (e.g., Postgres, MySQL, etc.).
\n
workspaceId (string): The unique identifier of the workspace.
\n
data (string): Configuration data for the datasource - always empty. To get this information, use the Get Datasource Connection Details API.
\n
snapshotTimestamp (string): The timestamp of the last snapshot taken for the datasource.
\n
lastRefreshTrigger (string): The timestamp of the last refresh trigger for the datasource.
\n
lastRefreshStatus (string): The status of the last refresh operation. Options:
\n
- init
  \n
- indexing
  \n
- failed / completed
  \n
\n

Tests the connection details of a datasource before you connect it.

Path Parameters

workspace_id (string): The unique identifier of the workspace.

Request Body

type (string): The datasource type: Postgres, BigQuery, Databricks, Trino, MsSql, Snowflake, Redshift, MySql, SingleStore or S3.
data (string): The connection details as a JSON string. The fields are the same as in the Connect request of that type.

Response Body

result (string): success (status 200) or failed (status 400).

💡 If the test fails, check the host, port, network access from PVML and credentials.

This endpoint retrieves the details of a specific datasource within a workspace.

Path Parameters

workspace_id(string): The unique identifier of the workspace.
\n
datasource_id (string): The unique identifier for the datasource.
\n

Request Body

This request does not contain a request body.

Response Body

The response will be a datasource object in JSON format and will contain the following fields:

id (string): A unique identifier for the datasource.
\n
name (string): The name of the datasource.
\n
description (string): A description of the datasource. Can be empty.
\n
type (string): The type of the datasource (e.g., \"Postgres\").
\n
workspaceId (string): A unique identifier for the workspace associated with the datasource.
\n
snapshotTimestamp (string): The timestamp of the last snapshot in ISO 8601 format. Defaults to \"0001-01-01T00:00:00Z\" if not set.
\n
lastRefreshTrigger (string): The timestamp of the last refresh trigger in ISO 8601 format. Defaults to \"0001-01-01T00:00:00Z\" if not set.
\n
lastRefreshStatus (string): The status of the last refresh operation.
\n

💡 use the Get Datasource Connection Details request in order to get the datasource connection properties.

This endpoint retrieves a list of datasources for a specific workspace.

Path Parameters

workspace_id (string): The ID of the workspace for which datasources are to be retrieved.

Request Body

This request does not contain a request body.

Response Body

The response will be a datasources object in JSON format and will contain the following fields:

id (string): The ID of the datasource.
\n
name (string): The name of the datasource.
\n
description (string): The description of the datasource.
\n
type (string): The type of the datasource (e.g., Postgres).
\n
workspaceId (string): The ID of the workspace to which the datasource belongs.
\n
data (string): The data associated with the datasource.
\n
snapshotTimestamp (string): The timestamp of the last snapshot of the datasource.
\n
lastRefreshTrigger (string): The trigger for the last refresh of the datasource.
\n
lastRefreshStatus (string): The status of the last refresh of the datasource.
\n

This endpoint retrieves the connection string properties of a specific datasource within a workspace.

Path Parameters

workspace_id(string): The unique identifier of the workspace.
\n
datasource_id (string): The unique identifier for the datasource.
\n

Request Body

This request does not contain a request body.

Response Body

The response will be a datasource object in JSON format and will contain the following fields:

id (string): A unique identifier for the datasource.
\n
name (string): The name of the datasource.
\n
description (string): A description of the datasource. Can be empty.
\n
type (string): The type of the datasource (e.g., \"Postgres\").
\n
workspaceId (string): A unique identifier for the workspace associated with the datasource.
\n
data (string): The datasource connection properties.
\n
snapshotTimestamp (string): The timestamp of the last snapshot in ISO 8601 format. Defaults to \"0001-01-01T00:00:00Z\" if not set.
\n
lastRefreshTrigger (string): The timestamp of the last refresh trigger in ISO 8601 format. Defaults to \"0001-01-01T00:00:00Z\" if not set.
\n
lastRefreshStatus (string): The status of the last refresh operation.
\n

This endpoint allows the user to update a specific datasource within a workspace.

To update name or description, no need to send data (connection string details), just the datasource type.

Path Parameters

workspace_id(string): The unique identifier of the workspace.
\n
datasource_id (string): The unique identifier for the datasource.
\n

Request Body

name (string): The new name for the datasource.
\n
description (string): The new description for the datasource.
\n
type (string): The type of the datasource, e.g., \"Postgres\".
\n

Response Body

Status 200 with an empty body.

This endpoint is used to delete a specific datasource within a workspace.

Path Parameters

workspace_id(string): The unique identifier of the workspace.
\n
datasource_id (string): The unique identifier for the datasource.
\n

Request Body

This request does not require a request body.

Response Body

The response for this request will be empty upon successful deletion of the specified datasource.

This endpoint retrieves the ping status of a specific datasource within a workspace.

Path Parameters

workspace_id(string): The unique identifier of the workspace.
\n
datasource_id (string): The unique identifier for the datasource.
\n

Request Body

This request does not contain a request body.

Response Body

result (string): passed when PVML can reach the datasource.

Data sources can be connected to your PVML workspace using connection string properties, without the need to move or duplicate the data.

Each datasource type requires specific connection parameters, so make sure you provide the appropriate values for the selected type (e.g., Snowflake, Databricks, Postgres, etc.).

After successfully connecting a new datasource, choose a snapshot type.

","_postman_id":"5d6869f7-1c20-431a-9ce3-daa699637122","auth":{"type":"bearer","bearer":{"basicConfig":[{"key":"token","value":"{{token}}"}]},"isInherited":true,"source":{"_postman_id":"230ce1f4-4c29-4006-87b5-45620ae91c61","id":"230ce1f4-4c29-4006-87b5-45620ae91c61","name":"PVML Documentation","type":"collection"}}},{"name":"Snapshot","item":[{"name":"Get Snapshot","id":"dfd79214-d411-49b0-898e-19c21d065400","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"GET","header":[],"url":"https://platform.pvml.com/platform/api/v1/workspaces/{{workspace_id}}/datasources/{{datasource_id}}/tree","description":"

This endpoint retrieves the snapshot, tree structure (schemas) of a specific datasource within a workspace.

Path Parameters

workspace_id(string): The unique identifier of the workspace.
\n
datasource_id (string): The unique identifier for the datasource.
\n

Request Body

This request does not contain a request body.

Response Body

tree: snapshot object containing:

datasourceName (string): Name of the data source.
\n
datasourceType (string): Type of the data source.
\n
schemas: List of schemas, each with:
\n
- schemaName (string): Name of the schema.
  \n
- tables: List of tables in the schema, each with:
  \n
  - tableName (string): Name of the table.
    \n
  - columns: List of columns in the table, each with:
    \n
    - columnName (string): Name of the column.
      \n
    - columnDataType (string): Data type of the column.
      \n
    - filterType (string): Type of filter applicable (used in row-level policies).
      \n
    \n
  \n
\n

Returns the status of the last snapshot of a datasource.

Path Parameters

workspace_id (string): The unique identifier of the workspace.
datasource_id (string): The unique identifier of the datasource.

Response Body

lastRefreshStatus (string): init, indexing, completed, failed or cancelled.
failureReason (string): Why it failed or stopped, if it did.
lastRefreshTrigger (string): When the last snapshot started.
snapshotTimeStamp (string): When the last successful snapshot finished.
snapshotType (string): The type of the last successful snapshot: schema_only or standard.
snapshotScanType (string): The type of the last snapshot run.

Requires the workspace admin or owner role.

Streams the progress of a snapshot refresh (Server-Sent Events).

Path Parameters

workspace_id (string): The unique identifier of the workspace.
datasource_id (string): The unique identifier of the datasource.

Response Body

The response is a stream (text/event-stream). Each progress event has a JSON object: the key is a schema, the value is the percent done (0-100). The stream ends when all schemas reach 100.

💡 To see the status without a stream, use Get Snapshot Status.

Starts a new snapshot of the datasource structure. It runs in the background.

Path Parameters

workspace_id (string): The unique identifier of the workspace.
datasource_id (string): The unique identifier of the datasource.

Query Parameters

profile (boolean, default true):
- true: Standard snapshot (the platform name). PVML reads the structure and data samples. Needed for Differential Privacy and the PII scan.
- false: Schema-only snapshot. Only tables and columns, no data samples. Faster.
\n

Response Body

Status 200 with an empty body. Follow the progress with Stream Snapshot Progress or Get Snapshot Status.

⚠️ Only one snapshot can run at a time.

Requires the workspace admin or owner role.

Stops a snapshot that is running. The previous snapshot stays in use.

Path Parameters

workspace_id (string): The unique identifier of the workspace.
datasource_id (string): The unique identifier of the datasource.

Response Body

Status 200 with an empty body.

After stopping, Get Snapshot Status shows cancelled.

Requires the workspace admin or owner role.

Once the data source is connected, a snapshot of the data schema (the structure of tables and columns) will be pulled.

You can choose between:

Standard snapshot: reads the structure and data samples. Needed for Differential Privacy and the PII scan.
\n
Schema-only snapshot: reads only schemas, tables and columns, no data samples. Faster, but Differential Privacy and the PII scan are not available.
\n

💡 Names in the API: in Refresh Snapshot, profile=true is Standard and profile=false is Schema-only. Get Snapshot Status returns standard or schema_only.

\n","_postman_id":"1810f78f-54ad-4f5f-ae68-2147356e553d","auth":{"type":"bearer","bearer":{"basicConfig":[{"key":"token","value":"{{token}}"}]},"isInherited":true,"source":{"_postman_id":"230ce1f4-4c29-4006-87b5-45620ae91c61","id":"230ce1f4-4c29-4006-87b5-45620ae91c61","name":"PVML Documentation","type":"collection"}}},{"name":"Guide: Relations and identifiers","item":[],"id":"90464d7f-7d80-46f3-a1dc-3e9154f649b9","description":"

Relations and identifiers are metadata that you add to a datasource. They are not in your database itself. PVML uses them to apply your policies to related tables. AI clients that use a VDB through MCP can also read them.

Relations: how tables connect

A relation says: \"this column in table A points to that column in table B\". It is like a foreign key.

Example from the bank tables:

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Referencing table (has the pointer)	Column	Referenced table (is pointed to)	Column
`accounts`	`branch_id`	`branches`	`branch_id`
`transactions`	`account_id`	`accounts`	`account_id`

💡 Which way? The referencing table is the one with many rows per match (many accounts per branch). The referenced table is the one with one row per key (one branch per branch_id).

What relations are used for:

Row filters on related tables. A row policy on branches.city can filter accounts and transactions too. PVML follows the relations, even across several steps. See Guide: Row-level security (RLS), Step 3.
\n
Differential Privacy. DP needs a path from each table to the identifier. Without it, DP blocks the query.
\n
Correct joins in AI clients. When an AI client describes a VDB through MCP, it gets the relations between the tables it can see. They tell it how to join the tables.
\n

Set them with Update Relations. One call sets all relations of one schema. Send an empty list to remove them. In the PVML UI, Pull From Source reads the foreign keys from your database for you.

[SCREENSHOT: relations.png]

Identifiers: who is the \"person\"

An identifier is the column that identifies the person (or entity) you want to protect, for example accounts.account_id or customers.customer_id.

What identifiers are used for:

Differential Privacy protects each identifier. A query must look at many identifiers at once. For example, with DP on the bank schema:
\n
- SELECT COUNT(\\\\*) FROM accounts returns a value close to the truth, for example 4999.3 instead of 5000.
  \n
- SELECT country, AVG(income) FROM accounts GROUP BY country works, with small noise.
  \n
- SELECT \\\\* FROM accounts is blocked: only aggregate queries are allowed.
  \n
- A query about one account (WHERE account_id = 410) returns no result.
  \n
\n
Tables without a relation path to an identifier can not be queried under DP. The logic: if PVML can not tell which person a row belongs to, it can not protect that person, so it blocks the query. Add the relations.
\n

Set identifiers with Update Identifiers, one schema per call.

⚠️ DP also needs a Standard snapshot of the datasource, not Schema-only (see Refresh Snapshot).

\n","_postman_id":"90464d7f-7d80-46f3-a1dc-3e9154f649b9","auth":{"type":"bearer","bearer":{"basicConfig":[{"key":"token","value":"{{token}}"}]},"isInherited":true,"source":{"_postman_id":"230ce1f4-4c29-4006-87b5-45620ae91c61","id":"230ce1f4-4c29-4006-87b5-45620ae91c61","name":"PVML Documentation","type":"collection"}}},{"name":"Identifiers","item":[{"name":"Get Identifiers","id":"4f77d84d-e170-4f63-851d-aa5426f25ed8","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"GET","header":[],"url":"https://platform.pvml.com/platform/api/v1/workspaces/{{workspace_id}}/datasources/{{datasource_id}}/metadata/identifiers","description":"

This endpoint retrieves the identifiers for a specific datasource within a workspace.

Path Parameters

workspace_id(string): The unique identifier of the workspace.
\n
datasource_id (string): The unique identifier for the datasource.
\n

Request Body

This request does not contain a request body.

Response Body

The response will be schemaIdentifiers (array of objects): A list of schema identifier objects, each representing an identifier.

workspaceId (string): The unique ID of the workspace containing the datasource.
\n
datasourceId (string): The unique ID of the datasource associated with the schema.
\n
schema (string): The schema path in the datasource.
\n
identifiers (array of objects): A list of column identifiers within the schema.
\n
- tableName (string): The name of a table in the schema.
  \n
- columnNames (array of strings): A list of column names within the table.
  \n
\n

This endpoint updates the identifiers for a specific datasource within a workspace.

Path Parameters

workspace_id(string): The unique identifier of the workspace.
\n
datasource_id (string): The unique identifier for the datasource.
\n

Request Body

schema (string): The schema path.
\n
identifiers (array): An array of objects containing tableName (string) and columnNames (array of strings).
\n

Response Body

Upon successful update, the server returns a status code of 200 and an empty JSON response.

💡 What is an identifier?

An identifier is the entity you're aiming to keep private in the analysis.

This field specifies the column whose raw data - potentially across multiple rows - you wish to protect when applying a differential privacy.

Note: an identifier does not have to be PII (Personally Identifiable Information) because the concept of privacy here is broader than just personal information.

The identifier is simply the element (like a person, a transaction, or an event) whose presence or absence in the data should not significantly change the query result.

💡 Why can't I just mask the identifier or the PII?

Masking or removing identifiers or PII isn’t enough because other information in the dataset (e.g., role, education, city) can still indirectly identify individuals when combined or cross referenced with external data (e.g., LinkedIn profile).

\n $\"Re-identification%20of%20Sensitive%20Data%20Through%20Cross-Referencing%20External%20Information:%20Why%20Masking%20the%20Identifier/PII%20isn't%20Good%20Enough\"$ \n\n

📘 See Guide: Relations and identifiers.

\n","_postman_id":"d9d5fe9e-2dba-430b-9bea-3c5528ba8193","auth":{"type":"bearer","bearer":{"basicConfig":[{"key":"token","value":"{{token}}"}]},"isInherited":true,"source":{"_postman_id":"230ce1f4-4c29-4006-87b5-45620ae91c61","id":"230ce1f4-4c29-4006-87b5-45620ae91c61","name":"PVML Documentation","type":"collection"}}},{"name":"Descriptions","item":[{"name":"Get Descriptions","id":"fa25a587-5fc0-4592-8083-e49945a8f89e","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"GET","header":[],"url":"https://platform.pvml.com/platform/api/v1/workspaces/{{workspace_id}}/datasources/{{datasource_id}}/metadata/descriptions","description":"

Returns the descriptions of schemas, tables and columns of a datasource.

Path Parameters

workspace_id (string): The unique identifier of the workspace.
datasource_id (string): The unique identifier of the datasource.

Response Body

descriptions (array). Each item has:
- schemaName (string)
- tableName (string): Empty for a schema description.
- columnName (string): Empty for a schema or table description.
- description (string)
\n

This endpoint retrieves the snapshot (tree structure) with descriptions.

Path Parameters

workspace_id(string): The unique identifier of the workspace.
\n
datasource_id (string): The unique identifier for the datasource.
\n
enrich (boolean, query parameter): When set to true, includes descriptions in the tree response.
\n

Request Body

This request does not contain a request body.

Response Body

tree: snapshot object containing:

datasourceName (string): Name of the data source.
\n
datasourceType (string): Type of the data source.
\n
schemas: List of schemas, each with:
\n
- schemaName (string): Name of the schema.
  \n
- tables: List of tables in the schema, each with:
  \n
  - tableName (string): Name of the table.
    \n
  - columns: List of columns in the table, each with:
    \n
    - columnName (string): Name of the column.
      \n
    - columnDataType (string): Data type of the column.
      \n
    - filterType (string): Type of filter applicable (used in row-level policies).
      \n
    - columnDescription (string): The description of the column.
      \n
    \n
  \n
\n

Adds, changes or removes descriptions of schemas, tables and columns.

Path Parameters

workspace_id (string): The unique identifier of the workspace.
datasource_id (string): The unique identifier of the datasource.

Request Body

toAdd (array): Descriptions to add or replace. Each item has schemaName, tableName, columnName and description. For a table description, leave out columnName. For a schema description, leave out tableName and columnName.
toRemove (array): Descriptions to delete. Each item has schemaName, tableName and columnName (no description).

Use full names with the quote style of your database.

Response Body

The request body, as saved.

Writes descriptions for chosen columns, tables or schemas with the workspace System LLM. PVML saves them right away.

💡 This uses the workspace System LLM (see LLMs).

Path Parameters

workspace_id (string): The unique identifier of the workspace.
datasource_id (string): The unique identifier of the datasource.

Request Body

toScan (array, required): The columns to describe. Each item has schemaName, tableName and columnName (full names with quotes).

Response Body

Status 200. The scan runs in the background. Check it with Get Descriptions Scan Status, then read the result with Get Descriptions.

Example result for accounts.income: \"Annual income amount for the account, stored as an integer value (e.g., 25000, 52000)\".

💡 Generated descriptions are a good start. Review them: you know your business better.

Requires the workspace admin or owner role.

Writes descriptions for the whole datasource with the workspace System LLM. For a large database this can take a while.

💡 This uses the workspace System LLM (see LLMs).

Path Parameters

workspace_id (string): The unique identifier of the workspace.
datasource_id (string): The unique identifier of the datasource.

Response Body

Status 200 with an empty body. The scan runs in the background.

⚠️ Only one description scan can run at a time.

Requires the workspace admin or owner role.

Stops a running description scan. Descriptions that are already saved stay.

Path Parameters

workspace_id (string): The unique identifier of the workspace.
datasource_id (string): The unique identifier of the datasource.

Response Body

Status 200 with an empty body.

Requires the workspace admin or owner role.

Returns the status of the last description scan.

Path Parameters

workspace_id (string): The unique identifier of the workspace.
datasource_id (string): The unique identifier of the datasource.

Response Body

lastRefreshStatus (string): init (never ran), indexing, completed, failed or cancelled.
lastRefreshTrigger (string): When it started.

Requires the workspace admin or owner role.

Streams the progress of a description scan (Server-Sent Events).

Path Parameters

workspace_id (string): The unique identifier of the workspace.
datasource_id (string): The unique identifier of the datasource.

Response Body

A text/event-stream with these events: progress, progress_error (one item failed, the scan goes on), done and error.

Requires the workspace admin or owner role.

💡 Why add descriptions?

A description explains in plain words what a schema, table or column means. For example: the column amt_2 is \"annual income of the account holder, in GBP\".

Descriptions help people and AI clients understand your data:

In the platform, users see them next to the tables and columns.
When an AI client describes a VDB through MCP, it gets the descriptions of the tables and columns it can see. This helps it pick the right column, for example amt_2 and not amt_1.

Descriptions are text only. They do not change your data or your policies.

\n","_postman_id":"a90b7d08-20c1-4c3a-b333-3172cc13b32a","auth":{"type":"bearer","bearer":{"basicConfig":[{"key":"token","value":"{{token}}"}]},"isInherited":true,"source":{"_postman_id":"230ce1f4-4c29-4006-87b5-45620ae91c61","id":"230ce1f4-4c29-4006-87b5-45620ae91c61","name":"PVML Documentation","type":"collection"}}},{"name":"Relations","item":[{"name":"Get Relations","id":"801cd1e7-9112-48c8-9472-0bced91254d6","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"GET","header":[],"url":"https://platform.pvml.com/platform/api/v1/workspaces/{{workspace_id}}/datasources/{{datasource_id}}/metadata/relations","description":"

This endpoint retrieves the metadata relations for a specific datasource within a workspace.

Path Parameters

workspace_id(string): The unique identifier of the workspace.
\n
datasource_id (string): The unique identifier for the datasource.
\n

Request Body

This request does not contain a request body.

Response Body

The response will be schemaRelations: a list of schema relations objects, each containing details about how tables and columns are related within a schema.

workspaceId (string): The ID of the workspace where the datasource resides.
\n
datasourceId (string): The ID of the datasource containing the schema.
\n
schema (string): The schema path within the datasource.
\n
relations (array of objects): A list of table-to-table relationships within the schema.
\n
- referencingTable (string): The name of the table that references another table.
  \n
- referencedTable (string): The name of the table being referenced.
  \n
- columnsReferences (array of objects): A list of column-to-column references between the tables.
  \n
  - referencingColumn (string): The column in the referencing table.
    \n
  - referencedColumn (string): The column in the referenced table.
    \n
  \n
\n

This endpoint allows you to send an updated list of relations for a specific datasource within a workspace.

Path Parameters

workspace_id(string): The unique identifier of the workspace.
\n
datasource_id (string): The unique identifier for the datasource.
\n

Request Body

schema (string): The schema path in the datasource.
\n
relations (array):
\n
- referencingTable (string): The referencing table in the relation.
  \n
- referencedTable (string): The referenced table in the relation.
  \n
- columnsReferences (array):
  \n
  - referencingColumn (string): The referencing column in the relation.
    \n
  - referencedColumn (string): The referenced column in the relation.
    \n
  \n
\n

Response Body

The response will show the resulting relations:

schema (string): The schema path in the datasource.
\n
relations (array):
\n
- referencingTable (string): The referencing table in the relation.
  \n
- referencedTable (string): The referenced table in the relation.
  \n
- columnsReferences (array):
  \n
  - referencingColumn (string): The referencing column in the relation.
    \n
  - referencedColumn (string): The referenced column in the relation.
    \n
  \n
\n

Reads the foreign keys from your database and saves them as relations. Relations you added before are kept.

Path Parameters

workspace_id (string): The unique identifier of the workspace.
datasource_id (string): The unique identifier of the datasource.

Response Body

schemaRelations (array): All saved relations, after the pull.

💡 This is the fastest and most exact way to get relations. Run it first, then add missing ones by hand or with Suggest Relations.

Requires the workspace admin or owner role.

Suggests relations from table and column names, with the workspace System LLM. Useful when your database has no foreign keys (for example BigQuery or a data lake).

💡 This uses the workspace System LLM (see LLMs).

Path Parameters

workspace_id (string): The unique identifier of the workspace.
datasource_id (string): The unique identifier of the datasource.

Response Body

schemaRelations (array): The suggestions.

⚠️ Suggestions are not saved. Check them, then save the ones you want with Update Relations.

Requires the workspace admin or owner role.

Compares the foreign keys in your database with the saved relations, and returns the ones that are not saved yet. Nothing is saved.

Path Parameters

workspace_id (string): The unique identifier of the workspace.
datasource_id (string): The unique identifier of the datasource.

Response Body

schemaRelations (array): Per schema, the foreign keys that are missing in PVML. Empty lists mean you are up to date.

💡 Run it after a database change. If it finds something, use Pull From Source to save it.

Requires the workspace admin or owner role.

Relations tell PVML how tables are linked, like foreign keys. For example: accounts.branch_id points to branches.branch_id.

PVML uses relations to:

Apply row filters to related tables. A filter on branches can also filter accounts and transactions.
Run Differential Privacy. DP follows the relations from each table to the identifier.
Show AI clients how to join tables. When an AI client describes a VDB through MCP, it gets the relations between the tables it can see.

📘 See Guide: Relations and identifiers for when and how to use relations.

\n","_postman_id":"6f9daf02-b539-4ccd-b92e-16775c571162","auth":{"type":"bearer","bearer":{"basicConfig":[{"key":"token","value":"{{token}}"}]},"isInherited":true,"source":{"_postman_id":"230ce1f4-4c29-4006-87b5-45620ae91c61","id":"230ce1f4-4c29-4006-87b5-45620ae91c61","name":"PVML Documentation","type":"collection"}}},{"name":"PII Catalog","item":[{"name":"Get Snapshot with PII","id":"47f77b0e-4027-47b1-bc01-a87e3ae1c352","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"GET","header":[],"url":"https://platform.pvml.com/platform/api/v1/workspaces/{{workspace_id}}/datasources/{{datasource_id}}/tree?enrich=false&pii=true","description":"

This endpoint retrieves the datasource snapshot (tree structure) with PIIs tagged (\"pii\": true).

Path Parameters

workspace_id(string): The unique identifier of the workspace.
\n
datasource_id (string): The unique identifier for the datasource.
\n
pii (boolean, query parameter): When set to true, includes PII tag in the tree response.
\n

Request Body

This request does not contain a request body.

Response Body

tree: snapshot object containing:

datasourceName (string): Name of the data source.
\n
datasourceType (string): Type of the data source.
\n
schemas: List of schemas, each with:
\n
- schemaName (string): Name of the schema.
  \n
- tables: List of tables in the schema, each with:
  \n
  - tableName (string): Name of the table.
    \n
  - columns: List of columns in the table, each with:
    \n
    - columnName (string): Name of the column.
      \n
    - columnDataType (string): Data type of the column.
      \n
    - filterType (string): Type of filter applicable (used in row-level policies).
      \n
    - pii (boolean, query parameter): Appears if the field was tagged as PII (equals true).
      \n
    \n
  \n
\n

This endpoint retrieves the PII catalog of a specific datasource in a workspace.

Path Parameters

workspace_id(string): The unique identifier of the workspace.
\n
datasource_id (string): The unique identifier for the datasource.
\n

Request Body

This request does not contain a request body.

Response Body

catalogs: an array containing snapshots of the catalog:

changeTime (string, ISO 8601 format): Represents the timestamp when the PII catalog was last modified, creating this version.
\n
userId (string): The unique ID of the catalog's version editor.
\n
userEmail (string): The email of the user who edited the catalog, creating the version.
\n
datasourceId (string): The unique ID of the datasource.
\n
id (string): The unique id of the catalog snapshot.
\n
workspaceId (string): The unique ID of the workspace containing the datasource.
\n
tree object containing an array of:
\n
- datasourceName (string): Name of the data source.
  \n
- datasourceType (string): Type of the data source.
  \n
- schemas: List of schemas, each with:
  \n
  - schemaName (string): Name of the schema.
    \n
  - tables: List of tables in the schema, each with:
    \n
    - tableName (string): Name of the table.
      \n
    - columns: List of columns in the table, each with:
      \n
      - columnName (string): Name of the column.
        \n
      - columnDataType (string): Data type of the column.
        \n
      - filterType (string): Type of filter applicable (used in row-level policies).
        \n
      - pii (boolean, query parameter): Set to true if the field was tagged as PII.
        \n
      - piiScanIgnore (boolean): Set to true if the field is ignored as PII in future scans.
        \n
      \n
    \n
  \n
\n

💡 The response also has a pagination object: totalRecords, currentPage, totalPages, pageSize, nextPage, prevPage.

\n","auth":{"type":"bearer","bearer":{"basicConfig":[{"key":"token","value":"{{token}}"}]},"isInherited":true,"source":{"_postman_id":"230ce1f4-4c29-4006-87b5-45620ae91c61","id":"230ce1f4-4c29-4006-87b5-45620ae91c61","name":"PVML Documentation","type":"collection"}},"urlObject":{"protocol":"https","path":["platform","api","v1","workspaces","{{workspace_id}}","datasources","{{datasource_id}}","pii","snapshot"],"host":["platform","pvml","com"],"query":[],"variable":[]}},"response":[{"id":"6d26c0e7-ecd3-405c-90a6-4e6baaff1b92","name":"Add to Catalog - 200 Success","originalRequest":{"method":"POST","header":[],"body":{"mode":"raw","raw":"{\n \"tree\": [\n {\n \"schemaName\": \"\\\"bank\\\".\\\"core\\\"\",\n \"tables\": [\n {\n \"tableName\": \"\\\"accounts\\\"\",\n \"columns\": [\n {\n \"columnName\": \"\\\"holder_first_name\\\"\",\n \"columnDataType\": \"text\",\n \"filterType\": \"text\"\n },\n {\n \"columnName\": \"\\\"holder_last_name\\\"\",\n \"columnDataType\": \"text\",\n \"filterType\": \"text\"\n }\n ]\n }\n ]\n }\n ]\n}","options":{"raw":{"language":"json"}}},"url":"https://platform.pvml.com/platform/api/v1/workspaces/{{workspace_id}}/datasources/{{datasource_id}}/pii/snapshot"},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json; charset=utf-8"}],"cookie":[],"responseTime":null,"body":"{\n \"catalogs\": [\n {\n \"changeTime\": \"2026-10-02T11:15:00.000Z\",\n \"userId\": \"8d117eb2-ff29-5364-96b8-6f6f65091ce4\",\n \"userEmail\": \"jane.doe@example.com\",\n \"datasourceId\": \"0f6efbbb-64c2-572d-a7d1-bd7750fce1a1\",\n \"id\": \"catalog-0002\",\n \"workspaceId\": \"b70ad5a7-089b-5a0f-a370-f34719a9621f\",\n \"tree\": [\n {\n \"schemaName\": \"\\\"bank\\\".\\\"core\\\"\",\n \"tables\": [\n {\n \"tableName\": \"\\\"branches\\\"\",\n \"columns\": [\n {\n \"columnName\": \"\\\"branch_id\\\"\",\n \"columnDataType\": \"integer\",\n \"pii\": false,\n \"piiScanIgnore\": false\n },\n {\n \"columnName\": \"\\\"city\\\"\",\n \"columnDataType\": \"text\",\n \"pii\": false,\n \"piiScanIgnore\": false\n },\n {\n \"columnName\": \"\\\"country\\\"\",\n \"columnDataType\": \"text\",\n \"pii\": false,\n \"piiScanIgnore\": false\n }\n ]\n },\n {\n \"tableName\": \"\\\"accounts\\\"\",\n \"columns\": [\n {\n \"columnName\": \"\\\"account_id\\\"\",\n \"columnDataType\": \"bigint\",\n \"pii\": false,\n \"piiScanIgnore\": false\n },\n {\n \"columnName\": \"\\\"branch_id\\\"\",\n \"columnDataType\": \"integer\",\n \"pii\": false,\n \"piiScanIgnore\": false\n },\n {\n \"columnName\": \"\\\"holder_first_name\\\"\",\n \"columnDataType\": \"text\",\n \"pii\": true,\n \"piiScanIgnore\": false\n },\n {\n \"columnName\": \"\\\"holder_last_name\\\"\",\n \"columnDataType\": \"text\",\n \"pii\": true,\n \"piiScanIgnore\": false\n },\n {\n \"columnName\": \"\\\"income\\\"\",\n \"columnDataType\": \"integer\",\n \"pii\": false,\n \"piiScanIgnore\": false\n },\n {\n \"columnName\": \"\\\"is_business\\\"\",\n \"columnDataType\": \"boolean\",\n \"pii\": false,\n \"piiScanIgnore\": false\n }\n ]\n },\n {\n \"tableName\": \"\\\"transactions\\\"\",\n \"columns\": [\n {\n \"columnName\": \"\\\"transaction_id\\\"\",\n \"columnDataType\": \"bigint\",\n \"pii\": false,\n \"piiScanIgnore\": false\n },\n {\n \"columnName\": \"\\\"account_id\\\"\",\n \"columnDataType\": \"bigint\",\n \"pii\": false,\n \"piiScanIgnore\": false\n },\n {\n \"columnName\": \"\\\"amount\\\"\",\n \"columnDataType\": \"numeric\",\n \"pii\": false,\n \"piiScanIgnore\": false\n },\n {\n \"columnName\": \"\\\"transaction_datetime\\\"\",\n \"columnDataType\": \"timestamp without time zone\",\n \"pii\": false,\n \"piiScanIgnore\": false\n }\n ]\n }\n ]\n }\n ]\n },\n {\n \"changeTime\": \"2026-10-01T09:30:00.000Z\",\n \"userId\": \"8d117eb2-ff29-5364-96b8-6f6f65091ce4\",\n \"userEmail\": \"jane.doe@example.com\",\n \"datasourceId\": \"0f6efbbb-64c2-572d-a7d1-bd7750fce1a1\",\n \"id\": \"catalog-0001\",\n \"workspaceId\": \"b70ad5a7-089b-5a0f-a370-f34719a9621f\",\n \"tree\": [\n {\n \"schemaName\": \"\\\"bank\\\".\\\"core\\\"\",\n \"tables\": [\n {\n \"tableName\": \"\\\"branches\\\"\",\n \"columns\": [\n {\n \"columnName\": \"\\\"branch_id\\\"\",\n \"columnDataType\": \"integer\",\n \"pii\": false,\n \"piiScanIgnore\": false\n },\n {\n \"columnName\": \"\\\"city\\\"\",\n \"columnDataType\": \"text\",\n \"pii\": false,\n \"piiScanIgnore\": false\n },\n {\n \"columnName\": \"\\\"country\\\"\",\n \"columnDataType\": \"text\",\n \"pii\": false,\n \"piiScanIgnore\": false\n }\n ]\n },\n {\n \"tableName\": \"\\\"accounts\\\"\",\n \"columns\": [\n {\n \"columnName\": \"\\\"account_id\\\"\",\n \"columnDataType\": \"bigint\",\n \"pii\": false,\n \"piiScanIgnore\": false\n },\n {\n \"columnName\": \"\\\"branch_id\\\"\",\n \"columnDataType\": \"integer\",\n \"pii\": false,\n \"piiScanIgnore\": false\n },\n {\n \"columnName\": \"\\\"holder_first_name\\\"\",\n \"columnDataType\": \"text\",\n \"pii\": true,\n \"piiScanIgnore\": false\n },\n {\n \"columnName\": \"\\\"holder_last_name\\\"\",\n \"columnDataType\": \"text\",\n \"pii\": true,\n \"piiScanIgnore\": false\n },\n {\n \"columnName\": \"\\\"income\\\"\",\n \"columnDataType\": \"integer\",\n \"pii\": false,\n \"piiScanIgnore\": false\n },\n {\n \"columnName\": \"\\\"is_business\\\"\",\n \"columnDataType\": \"boolean\",\n \"pii\": false,\n \"piiScanIgnore\": false\n }\n ]\n },\n {\n \"tableName\": \"\\\"transactions\\\"\",\n \"columns\": [\n {\n \"columnName\": \"\\\"transaction_id\\\"\",\n \"columnDataType\": \"bigint\",\n \"pii\": false,\n \"piiScanIgnore\": false\n },\n {\n \"columnName\": \"\\\"account_id\\\"\",\n \"columnDataType\": \"bigint\",\n \"pii\": false,\n \"piiScanIgnore\": false\n },\n {\n \"columnName\": \"\\\"amount\\\"\",\n \"columnDataType\": \"numeric\",\n \"pii\": false,\n \"piiScanIgnore\": false\n },\n {\n \"columnName\": \"\\\"transaction_datetime\\\"\",\n \"columnDataType\": \"timestamp without time zone\",\n \"pii\": false,\n \"piiScanIgnore\": false\n }\n ]\n }\n ]\n }\n ]\n }\n ],\n \"pagination\": null\n}"}],"_postman_id":"b029bdcb-4b10-4815-b302-cad326f30a22"},{"name":"Start PII Scan","id":"16346eac-11d3-43cd-a007-f10caf2092eb","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[],"url":"https://platform.pvml.com/platform/api/v1/workspaces/{{workspace_id}}/datasources/{{datasource_id}}/pii/scan","description":"

Starts a scan that finds columns with personal data (PII), such as names, emails and phone numbers. It runs in the background, schema by schema.

💡 This uses the workspace System LLM (see LLMs).

Path Parameters

workspace_id (string): The unique identifier of the workspace.
datasource_id (string): The unique identifier of the datasource.

Response Body

The scan list, like Get PII Scans. The new scan is first, with scanStatus scanning per schema.

⚠️ Before you start: the datasource needs a standard snapshot (see Refresh Snapshot), because PVML looks at data samples. Only one scan can run at a time.

💡 The scan only suggests. Review the result and save the columns you agree with in the PII catalog (Add to Catalog).

Requires the workspace admin or owner role.

Lists the PII scans of a datasource, newest first.

Path Parameters

workspace_id (string): The unique identifier of the workspace.
datasource_id (string): The unique identifier of the datasource.

Response Body

catalogs (array). Each scan has startTime and data: id, userEmail (who started it) and scanStatusArr. Each schema in scanStatusArr has its tree (tables, columns, and pii: true/false), scanStatus (scanning, completed, failed) and completionTime.
pagination (object): nextCursor.

Requires the workspace admin or owner role.

Returns one PII scan.

Path Parameters

workspace_id (string): The unique identifier of the workspace.
datasource_id (string): The unique identifier of the datasource.
scan_id (string): The scan id from Get PII Scans.

Response Body

scanData: one scan, in the format of Get PII Scans.

Requires the workspace admin or owner role.

Returns the current PII catalog of the datasource: the columns that are marked as personal data.

Path Parameters

workspace_id (string): The unique identifier of the workspace.
datasource_id (string): The unique identifier of the datasource.

Response Body

catalog: changeTime, and data with userEmail (who saved it last) and tree (schemas, tables, PII columns). tree is null when nothing is marked yet.

Requires the workspace admin or owner role.

💡 What is PII?

PII stands for Personally Identifiable Information. It refers to any data that can be used to identify a specific individual, for example:

Full name
\n
Phone number
\n
Social security number
\n
Credit card or bank account number
\n

By tagging fields as PII, organizations can easily identify protected data, enforce stricter access controls, and tailor policies to restrict access based on user roles, responsibilities, and business use cases.

This approach not only supports compliance with privacy regulations but also minimizes exposure of sensitive data, reduces breach risks, and ensures that only authorized users or systems have access to critical information.

💡 How does the PII Catalog Work?

Begin by either tagging the schemas structure manually or running an automatic PII scan (Start PII Scan)
\n
Resolve conflicts between the scan and the current version by accepting the relevant suggestions from the scan
\n
Tagging fields as ignored means you want to exclude the scan's suggestions for this field (either as PII or as non-PII) - in practice, this means that performing \"merge\" will ignore the scan's tag for these fields.
\n

💡 Merge vs. Replace

Merge takes everything from the scan over the current version, while keeping the extra tags in current version
\n
Replace takes the scan as-is over the current version
\n

\n","_postman_id":"165f3b8b-2846-44c4-8ee3-cc63c2befb14","auth":{"type":"bearer","bearer":{"basicConfig":[{"key":"token","value":"{{token}}"}]},"isInherited":true,"source":{"_postman_id":"230ce1f4-4c29-4006-87b5-45620ae91c61","id":"230ce1f4-4c29-4006-87b5-45620ae91c61","name":"PVML Documentation","type":"collection"}}}],"id":"b5c7f038-0ae0-45cb-98b8-6ce04f9dd28a","description":"

\n\n

Data sources can be connected to your PVML workspace using connection string properties, without the need to move or duplicate the data. Once the data source is connected, a snapshot of the data schema (the structure of tables and columns) will be pulled.

You can choose between:

Standard snapshot: reads the structure and data samples. Needed for Differential Privacy and the PII scan.
\n
Schema-only snapshot: reads only schemas, tables and columns, no data samples. Faster, but Differential Privacy and the PII scan are not available.
\n

💡 Names in the API: in Refresh Snapshot, profile=true is Standard and profile=false is Schema-only. Get Snapshot Status returns standard or schema_only.

\n $\"Connect%20a%20Datasource\"$ \n\n

After the schema snapshot is complete, you can define relations, identifiers, and more.

\n","_postman_id":"b5c7f038-0ae0-45cb-98b8-6ce04f9dd28a","auth":{"type":"bearer","bearer":{"basicConfig":[{"key":"token","value":"{{token}}"}]},"isInherited":true,"source":{"_postman_id":"230ce1f4-4c29-4006-87b5-45620ae91c61","id":"230ce1f4-4c29-4006-87b5-45620ae91c61","name":"PVML Documentation","type":"collection"}}},{"name":"Virtual DBs","item":[{"name":"Create Virtual DB","id":"f0ee22e1-ec0f-45c4-a3e6-d8f64c163a06","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[],"body":{"mode":"formdata","formdata":[{"key":"data","type":"text","value":"{\n \"name\": \"clinic analytics\",\n \"description\": \"VDB for the clinic analytics team\",\n \"datasourceId\": \"{{datasource_id}}\",\n \"createRegularVdbInfo\": {\n \"shouldEnforce\": false,\n \"permissionsIds\": [\n \"{{policy_id}}\"\n ],\n \"entitiesIds\": [\n {\n \"type\": \"user\",\n \"id\": \"{{user_id}}\"\n },\n {\n \"type\": \"group\",\n \"id\": \"{{group_id}}\"\n }\n ],\n \"bypassSystemTablesEnforcement\": false\n }\n}"},{"description":"

Optional image file (PNG/JPG).

\n","key":"image","type":"file","value":null,"disabled":true}]},"url":"https://platform.pvml.com/platform/api/v1/workspaces/{{workspace_id}}/vdbs","description":"

Creates a new VDB (virtual database) on top of a datasource.

Path Parameters

workspace_id (string): The unique identifier of the workspace.

Request Body

Form data with these fields:

data (text): JSON with these properties:
- name (string, required): The name of the VDB.
- description (string): A short description.
- datasourceId (string, required): The datasource the VDB is built on.
- createRegularVdbInfo (object, required): The VDB settings:
  - permissionsIds (array of strings): The policies to attach. Add at least one column policy, otherwise users see no data.
  - entitiesIds (array): The users and groups that get access. Each item is {\"type\": \"user\" | \"group\", \"id\": \"<id>\"}.
  - shouldEnforce (boolean): \"Propagate policies\". When true, PVML derives policies for database views in this VDB from their definitions, based on the source data and the policies of this VDB. Default false.
  - enforcementVdbId (string, optional): Derive the view policies from another VDB instead. Used only when shouldEnforce is true.
  - bypassSystemTablesEnforcement (boolean): When false (default), users and BI tools can query only the system metadata objects (for example information_schema) that their column policy allows. When true, all scanned system metadata is visible without policy limits.
  \n
\n
image (file, optional): An image for the VDB.

Response Body

A vdb object:

vdbId (string): The VDB ID.
datasourceId, datasourceType, workspaceId (string).
name, description (string).
shouldEnforce (boolean).
createdAt, lastModifiedAt, permissionsLastModifiedAt (number): Unix time in milliseconds.
image (string).
permissionsIds (array): The attached policy IDs.
entities (array): The users and groups with access, as {type, id}.

This endpoint allows to get a specific VDB in a workspace.

Path Parameters

workspace_id(string): The unique identifier of the workspace.
\n
vdb_id (string): The unique identifier of the new VDB.
\n
image (boolean): Specifies whether to include image data in the response.
\n

Request Body

This request does not contain a request body.

Response Body

vdb json containing:

vdbId (string): Unique identifier for the VDB.
\n
datasourceId (string): Identifier for the associated data source.
\n
datasourceType (string): Type of the datasource (e.g., Postgres).
\n
workspaceId (string): Identifier for the workspace where the VDB is located.
\n
name (string): Descriptive name of the VDB.
\n
description (string): Additional information or context about the VDB.
\n
createdAt (timestamp, Unix epoch in milliseconds): Timestamp of VDB creation.
\n
lastModifiedAt (timestamp, Unix epoch in milliseconds): Timestamp of the most recent modification to the VDB.
\n
permissionsLastModifiedAt (timestamp, Unix epoch in milliseconds): Timestamp of the last update to policies in the VDB.
\n
image (string): Encoded image representation or thumbnail of the VDB.
\n

This endpoint allows to get the users of a specific VDB in a workspace.

Path Parameters

workspace_id(string): The unique identifier of the workspace.
\n
vdb_id (string): The unique identifier of the VDB.
\n

Request Body

This request does not contain a request body.

Response Body

entities (array):
\n
- type (string): The type of entity (group / user. Note: a service account is considered a user in this context).
  \n
- group (object or null): Contains group-related details if the entity is of type group.
  \n
  - groupId (string): Unique identifier for the group.
    \n
  - workspaceId (string): Identifier for the workspace to which the group belongs.
    \n
  - name (string): Name of the group.
    \n
  - description (string): Description or additional details about the group.
    \n
  - createdAt (timestamp, ISO 8601 format): Timestamp of group creation.
    \n
  - lastModifiedAt (timestamp, ISO 8601 format): Timestamp of the last modification to the group.
    \n
  - image (string): Encoded image representation of the group.
    \n
  \n
- user (object or null): Contains user-related details if the entity is of type user.
  \n
\n

💡 The response also has a pagination object: totalRecords, currentPage, totalPages, pageSize, nextPage, prevPage.

This endpoint allows to get a full VDB in a workspace.

Path Parameters

workspace_id(string): The unique identifier of the workspace.
\n
vdb_id (string): The unique identifier of the new VDB.
\n
/full: returns also permissionsIds and entities in the response.
\n
image (boolean): Specifies whether to include image data in the response.
\n

Request Body

This request does not contain a request body.

Response Body

vdbId (string): Unique identifier for the VDB.
\n
datasourceId (string): Identifier for the associated data source.
\n
datasourceType (string): Type of the datasource (e.g., Postgres).
\n
workspaceId (string): Identifier for the workspace where the VDB is located.
\n
name (string): Descriptive name of the VDB.
\n
description (string): Additional information or context about the VDB.
\n
createdAt (timestamp, Unix epoch in milliseconds): Timestamp of VDB creation.
\n
lastModifiedAt (timestamp, Unix epoch in milliseconds): Timestamp of the most recent modification to the VDB.
\n
permissionsLastModifiedAt (timestamp, Unix epoch in milliseconds): Timestamp of the last update to policies in the VDB.
\n
image (string): Encoded image representation or thumbnail of the VDB (returned if image parameter is set to true).
\n
permissionsIds (array or null): List of policies' IDs associated with the VDB, if any.
\n
entities (array): List of related users or groups associated with the VDB.
\n

This endpoint allows to get all the VDBs in a specific workspace.

Path Parameters

workspace_id(string): The unique identifier of the workspace.

Request Body

This request does not contain a request body.

Response Body

The response is a vdbs object in json format that includes an array of VDBs with the following details on each VDB:

vdbId (string): Unique identifier for the VDB.
\n
datasourceId (string): Identifier for the associated data source.
\n
datasourceType (string): Type of the datasource (e.g., Postgres).
\n
workspaceId (string): Identifier for the workspace where the VDB is located.
\n
name (string): Descriptive name of the VDB.
\n
description (string): Additional information or context about the VDB.
\n
createdAt (timestamp, Unix epoch in milliseconds): Timestamp of VDB creation.
\n
lastModifiedAt (timestamp, Unix epoch in milliseconds): Timestamp of the most recent modification to the VDB.
\n
permissionsLastModifiedAt (timestamp, Unix epoch in milliseconds): Timestamp of the last update to policies in the VDB.
\n
image (string): Encoded image representation or thumbnail of the VDB.
\n

💡 The response also has a pagination object: totalRecords, currentPage, totalPages, pageSize, nextPage, prevPage.

Optional image file (PNG/JPG).

\n","key":"image","type":"file","value":null,"disabled":true}]},"url":"https://platform.pvml.com/platform/api/v1/workspaces/{{workspace_id}}/vdbs/{{vdb_id}}/info","description":"

Updates the name, description, settings and image of a VDB.

Path Parameters

workspace_id (string): The unique identifier of the workspace.
vdb_id (string): The unique identifier of the VDB.

Request Body

Form data with these fields:

data (text): JSON with these properties:
- name (string, required): The VDB name.
- description (string): The VDB description.
- shouldEnforce (boolean, required): See Create Virtual DB.
- enforcementVdbId (string, optional).
- bypassSystemTablesEnforcement (boolean, required): See Create Virtual DB.
\n
image (file, optional): The VDB image.

💡 Note: Fields you leave out are reset. For example, if you do not send image, the image goes back to the default.

Response Body

Status 200 with an empty body.

Adds or removes users and groups that can access a VDB.

Path Parameters

workspace_id (string): The unique identifier of the workspace.
vdb_id (string): The unique identifier of the VDB.

Request Body

entitiesToAdd (array): Users and groups to add. Each item has:
- type (string): user or group.
- id (string): The user ID or group ID.
\n
entitiesToRemove (array): Users and groups to remove, in the same format.

Both arrays are required. Send [] when there is nothing to add or remove.

Response Body

Status 200 with an empty body. If nothing changes (for example the user is already in the VDB), the status is 304 Not Modified.

This endpoint allows to update the policies of a specific VDB in a workspace.

Path Parameters

workspace_id(string): The unique identifier of the workspace.
\n
vdb_id (string): The unique identifier of the VDB.
\n

Request Body

permissionsToAdd (array): A list of policies to be added.
\n
permissionsToRemove (array): A list of policies to be removed. Same format as permissionsToAdd.
\n

Note: Each array can be left empty ([]) if no policies need to be added or removed.

Response Body

Upon successful update, the server returns a status code of 200 and an empty JSON response.

This endpoint allows to delete a specific VDB in a workspace.

Path Parameters

workspace_id(string): The unique identifier of the workspace.
\n
vdb_id (string): The unique identifier of the VDB.
\n

Request Body

This request does not contain a request body.

Response Body

Upon successful deletion, the server returns a status code of 200 and an empty JSON response.

This endpoint allows to directly execute a query using a VDB.

Path Parameters

workspace_id(string): The unique identifier of the workspace.
\n
vdb_id (string): The unique identifier of the VDB.
\n

Request Body

query (string): the SQL query to execute.

Response Body

The response represents a database query result in a tabular format:

Outer Array: Contains rows of the result set.
\n
First Inner Array: Represents the column headers (first row of the table).
\n
Subsequent Inner Arrays: Represent individual rows of data from the query result.
\n

Creates a copy of a VDB, named <name> - copy, with the same users, groups and settings.

Path Parameters

workspace_id (string): The unique identifier of the workspace.
vdb_id (string): The unique identifier of the VDB.

Request Body

duplicateVdbPermission (boolean):
- false: the copy uses the same policies. A change to a policy changes both VDBs.
- true: PVML also copies each policy (<name> - copy). You can change the copy without touching the original VDB.
\n

💡 Use true when you want to try changes safely, for example on a test VDB.

Response Body

Status 201 with duplicateVdb: the new VDB, including regularViewInfo with permissionsIds, groupsIds and directUsersIds.

Requires the workspace admin or owner role.

Lists the policies attached to a VDB, with their data.

Path Parameters

workspace_id (string): The unique identifier of the workspace.
vdb_id (string): The unique identifier of the VDB.

Response Body

permissions (array): Policy objects.

Requires the workspace admin or owner role.

Returns the relations between tables that the user can see in this VDB.

Path Parameters

workspace_id (string): The unique identifier of the workspace.
vdb_id (string): The unique identifier of the VDB.

Response Body

schemaRelations (array): Per schema, the relations (same format as Get Relations).

💡 PVML shows only relations between tables and columns the user can access in this VDB. A relation must not reveal a table the user can not see.

Any workspace member with access to the VDB can call it.

Returns the ID of the MCP server of a VDB. PVML creates one MCP server for every VDB.

Path Parameters

workspace_id (string): The unique identifier of the workspace.
vdb_id (string): The unique identifier of the VDB.

Response Body

mcpId (string): Use it in the MCP requests, for example Get MCP Connection Config.

Any workspace member with access to the VDB can call it.

A virtual database contains a collection of data access policies that determine the scope of data that users can see and interact with, as well as the privacy controls applied to them.

A virtual database has the following properties:

Datasource
\n
Users
\n
Policies
\n

Once a virtual database is set up, you can generate a secure connection string for it (JDBC/ODBC). See Connections > ODBC / JDBC.

This ensures that all data interactions are processed through PVML, with permissions enforced in real time.

\n $\"Generate%20a%20Secure%20Connection%20String%20for%20a%20virtual%20database%20(JDBC/ODBC).\"$ \n\n

You can also use this virtual database in the PVML Notebook, connect AI clients to it through its MCP server, or run SQL queries directly through it like any other database.

🕵🏻‍♂️ Common Mistakes When Configuring a Virtual Database:

Forgetting to Attach a Column-Level Policy:
A virtual database must have a column-level policy to be considered valid. Ensure this is set up.
\n
Not Adding Users:
Even if you're the admin or owner of the workspace, or even if there's only one user or group in your workspace, you must explicitly add the users/groups to the virtual database.
\n

\n","_postman_id":"fd7943c3-453e-44b4-b10a-c74405eb8d12","auth":{"type":"bearer","bearer":{"basicConfig":[{"key":"token","value":"{{token}}"}]},"isInherited":true,"source":{"_postman_id":"230ce1f4-4c29-4006-87b5-45620ae91c61","id":"230ce1f4-4c29-4006-87b5-45620ae91c61","name":"PVML Documentation","type":"collection"}}},{"name":"Policies","item":[{"name":"Guide: Row-level security (RLS)","item":[],"id":"245d231b-5506-4e0c-998b-597d3687f14d","description":"

Row-level security (RLS) means: every user sees only the rows they are allowed to see, in the same table, with the same query.

In this guide we build RLS step by step for a simple example.

The example

A bank has branches in many cities. Its database has three tables in the schema \"bank\".\"core\":

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Table	Columns (short list)
`branches`	`branch_id`, `city`, `country`
`accounts`	`account_id`, `branch_id`, `holder_name`, `income`
`transactions`	`transaction_id`, `account_id`, `amount`

The goal: each branch manager sees only the accounts and transactions of their own city. The head office sees everything.

Step 1: A simple fixed filter

First, a filter that is the same for everyone: show only accounts in the UK.

Call Create Row Policy with this data:

{\n  \"predicate\": \"\\\"bank\\\".\\\"core\\\".\\\"accounts\\\".\\\"country\\\" = 'GBR'\",\n  \"scope\": [\"\\\"bank\\\".\\\"core\\\".\\\"accounts\\\"\"]\n}\n\n

predicate is a normal SQL condition, like the WHERE part of a query. Only rows where it is true are visible.
\n
scope is the list of tables the filter applies to.
\n
Write each column with its full path (database.schema.table.column). See Guide: Writing object names.
\n
The \\\" is only JSON escaping for the API. In the platform, type the predicate as plain SQL: \"bank\".\"core\".\"accounts\".\"country\" = 'GBR'.
\n

Attach the policy to a VDB (together with a column policy). Now SELECT COUNT(\\\\\\*) FROM accounts in this VDB returns only the UK accounts, for example 423 instead of 5,000. The user does not need to add any WHERE clause.

Step 2: A personal filter with user attributes

A fixed filter is the same for every user. But Dana manages London and Marc manages Paris. We do not want one policy per manager. Instead, we use one policy with a user attribute.

2a. Create the attribute (see the Attributes section):

Create Attribute Catalog with name bank.
\n
Define Attributes in it: {\"name\": \"city\", \"type\": \"text\"}.
\n
Set User Attributes: Dana gets city = \"London\", Marc gets city = \"Paris\".
\n

[SCREENSHOT: attributes_catalog_definitions.png]

[SCREENSHOT: attributes_user_values.png]

2b. Use the attribute in the predicate. Write the full attribute name in double curly braces:

{\n  \"predicate\": \"\\\"bank\\\".\\\"core\\\".\\\"branches\\\".\\\"city\\\" = {{bank.city}}\",\n  \"scope\": [\"\\\"bank\\\".\\\"core\\\".\\\"branches\\\"\"]\n}\n\n

When Dana runs a query, PVML replaces {{bank.city}} with 'London'. When Marc runs the same query, it becomes 'Paris'. One policy, many managers.

💡 If Dana moves to Paris, just change her attribute. You do not need to change the policy.

\n\n

The accounts and transactions tables have no city column. How can we filter them by city?

PVML can follow relations between tables (like foreign keys):

accounts.branch_id points to branches.branch_id
\n
transactions.account_id points to accounts.account_id
\n

3a. Tell PVML about the relations with Update Relations (see Guide: Relations and identifiers):

{\n  \"schema\": \"\\\"bank\\\".\\\"core\\\"\",\n  \"relations\": [\n    {\n      \"referencingTable\": \"\\\"accounts\\\"\",\n      \"referencedTable\": \"\\\"branches\\\"\",\n      \"columnsReferences\": [{\"referencingColumn\": \"\\\"branch_id\\\"\", \"referencedColumn\": \"\\\"branch_id\\\"\"}]\n    },\n    {\n      \"referencingTable\": \"\\\"transactions\\\"\",\n      \"referencedTable\": \"\\\"accounts\\\"\",\n      \"columnsReferences\": [{\"referencingColumn\": \"\\\"account_id\\\"\", \"referencedColumn\": \"\\\"account_id\\\"\"}]\n    }\n  ]\n}\n\n

[SCREENSHOT: relations.png]

3b. Add the related tables to the scope:

{\n  \"predicate\": \"\\\"bank\\\".\\\"core\\\".\\\"branches\\\".\\\"city\\\" = {{bank.city}}\",\n  \"scope\": [\n    \"\\\"bank\\\".\\\"core\\\".\\\"branches\\\"\",\n    \"\\\"bank\\\".\\\"core\\\".\\\"accounts\\\"\",\n    \"\\\"bank\\\".\\\"core\\\".\\\"transactions\\\"\"\n  ]\n}\n\n

[SCREENSHOT: rls_scope.png]

Now Dana sees only London branches, the accounts of London branches, and the transactions of those accounts. PVML finds the path transactions → accounts → branches by itself, even across two steps.

💡 Only the tables in the scope are filtered. A related table that is not in the scope shows all its rows. For example, if the scope is only transactions, Dana still sees all accounts.

⚠️ Every table in the scope needs a relation path to the predicate table, and all tables must be in the same schema. Add missing relations first.

Step 4: Other attribute types

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

You want	Attribute type and value	Predicate
One text value	`text`: `\"London\"`	`... .\"city\" = {{bank.city}}`
A number limit	`numeric`: `50000`	`... .\"income\" <= {{bank.max_income}}`
Several values	`complex`, `multiValued: true`, item type `text`: `[\"London\", \"Paris\"]`	`... .\"city\" IN ({{bank.cities}})`
A field of an object	`complex` object with fields `city`, `country`: `{\"city\": \"London\", \"country\": \"GBR\"}`	`... .\"country\" = {{bank.office.country}}`
A yes/no flag	`boolean`: `true`	`{{bank.is_head_office}} = true`

A predicate can be any SQL condition in your database's own SQL, with AND, OR, parentheses, BETWEEN, NOT IN, LIKE and more. An attribute can stand anywhere a value goes, for example ... .\"income\" BETWEEN 0 AND {{bank.max_income}}.

Step 5: Common patterns

The head office sees everything. Add a boolean attribute is_head_office and use OR:

\"bank\".\"core\".\"branches\".\"city\" = {{bank.city}} OR {{bank.is_head_office}} = true\n\n

Managers have is_head_office = false and see their city. Head office users have true and see all rows.

[SCREENSHOT: rls_row_policy_predicate.png]

Set the value for a whole team. Put the attribute on a group (with Set Group Attributes). All group members get it. If a user also has their own value, the user value wins. The logic: the more specific value wins. A value set for one person is more specific than a value set for a whole team.

Rules to remember

No value, no data. If a user has no value for an attribute that a policy needs, their query is blocked. The logic: when PVML is not sure, it says no. A missing value never opens more data.
\n
The attribute must exist before you create the policy.
\n
Several row policies on the same table work together with AND. Each row policy is a limit, and all limits apply. A row is visible only if it passes all of them. If you need OR, write one predicate with OR. See Guide: How policies work together.
\n
Row policies do not hide columns. Use a column policy or masking for that.
\n

Test your policy

Give a test user the attribute values you want to check.
\n
Run a query as this user, for example with Execute Query on Virtual DB.
\n
Open the query in Get Audit Record. The permissions field shows the exact filter PVML applied (filterPermissionPaths).
\n

\n","_postman_id":"245d231b-5506-4e0c-998b-597d3687f14d","auth":{"type":"bearer","bearer":{"basicConfig":[{"key":"token","value":"{{token}}"}]},"isInherited":true,"source":{"_postman_id":"230ce1f4-4c29-4006-87b5-45620ae91c61","id":"230ce1f4-4c29-4006-87b5-45620ae91c61","name":"PVML Documentation","type":"collection"}}},{"name":"Guide: How policies work together","item":[],"id":"2b1e2875-efee-4fd1-9bfb-9dc981cd83c2","description":"

A VDB usually has several policies. This guide explains what happens when they meet. The examples use the bank tables from Guide: Row-level security (RLS).

The logic behind it

PVML follows two simple rules. If you know them, you can guess the result of any combination.

Grants add up. Column, write and routines policies give access. Each one adds more, like keys on a key ring.
Limits stack, and the strictest one wins. Row filters, masking, row limits, timeouts and Privacy policies take away access. All of them apply together. When two limits disagree, PVML always picks the safer result.

Security comes first: PVML never solves a conflict by showing more data.

[SCREENSHOT: vdb_policy_tabs.png]

Quick summary

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Policy type	Several policies in one VDB	Why
Column (read access)	Union: users see every column that any column policy allows	A grant: grants add up
Write	Union	A grant
Routines	Union	A grant
Row (filter)	AND: a row is visible only if it passes all row policies on that table	A limit: all limits apply
Masking, same method on a column	That method is used	No conflict
Masking, different methods on a column	Full mask `*****`	A conflict: the safest result wins
Row limit	The smallest `maxRows`	A conflict: the safest result wins
Timeout	Attach only one per VDB	Keeps the limit clear

Column policies add up (grants)

Policy A allows accounts.account_id. Policy B allows accounts.income. A VDB with both:

SELECT account_id, income FROM accounts works.
SELECT holder_name FROM accounts is blocked.
SELECT * FROM accounts works and returns only account_id and income.

💡 A VDB needs at least one column policy. Without it, users see no data at all.

Row policies narrow each other (limits)

Each row policy is a limit, so all of them apply.

Policy A: country = 'GBR'. Policy B: is_business = true. A VDB with both shows only UK business accounts. It does not show all UK accounts plus all business accounts.

If you want \"UK accounts or business accounts\", write one policy:

\"bank\".\"core\".\"accounts\".\"country\" = 'GBR' OR \"bank\".\"core\".\"accounts\".\"is_business\" = true\n

Two masking policies on one column

If two masking policies use the same method on a column, that method is used. If they use different methods (for example partial and hash), PVML can not know which one you meant. So it picks the safest result: the full mask *****.

Row filters and masking together

Both are limits, so both apply. Dana sees only London accounts, and inside them the names are masked.

Privacy: Differential Privacy and Aggregation Functions Only

Differential Privacy turns results of the schema into noisy aggregates. Non-aggregate queries (SELECT *) are blocked.
Aggregation Functions Only also blocks non-aggregate queries, but returns exact results.
Use Aggregation Functions Only when exact totals are fine and you only want to stop row-level exports. Use Differential Privacy when even exact totals could reveal one person.

Load Control: timeout and row limit

Timeout fails the query when it runs too long.
Row limit does not fail the query. It returns only the first rows.

If several row limits apply, the smallest one wins: the safest result. Attach only one timeout policy to a VDB, so the limit is clear.

\n","_postman_id":"2b1e2875-efee-4fd1-9bfb-9dc981cd83c2","auth":{"type":"bearer","bearer":{"basicConfig":[{"key":"token","value":"{{token}}"}]},"isInherited":true,"source":{"_postman_id":"230ce1f4-4c29-4006-87b5-45620ae91c61","id":"230ce1f4-4c29-4006-87b5-45620ae91c61","name":"PVML Documentation","type":"collection"}}},{"name":"Guide: Masking strategies","item":[],"id":"dc91bf15-3305-4208-a7a0-cc996420be9b","description":"

Masking hides the values of a column in query results. The data in your database does not change. PVML has four masking methods.

The four methods

Example column holder_name, value Johnson:

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Method	Body fields	Result	Good for
Full	`\"unmaskLeft\": 0, \"unmaskRight\": 0`	`*****`	Values nobody should see
Partial	`\"unmaskLeft\": 2`	`Jo*****`	Keep a hint, for example the last 4 digits of a card (`\"unmaskRight\": 4`)
Hash	`\"isHash\": true`	a fixed code, for example `c51e…`	Count, group and join without seeing the value
Regex	`\"regex\": \"[aeiou]\"`	`J*hns*n`	Hide only parts of a value that match a pattern

Each item in the policy data has the column (full path) plus the fields of one method. One policy can use different methods for different columns:

[SCREENSHOT: masking_methods.png]

Full and partial

Full masking always returns *****, whatever the length of the value.
Partial masking keeps unmaskLeft characters at the start and unmaskRight at the end. The rest becomes *****.

[{\"column\": \"\\\"bank\\\".\\\"core\\\".\\\"accounts\\\".\\\"card_number\\\"\", \"unmaskLeft\": 0, \"unmaskRight\": 4}]\n

Hash: masked, but still useful

The same value always gives the same code. So users can still:

count distinct customers: COUNT(DISTINCT holder_name)
group by the column: GROUP BY holder_name
join two tables on it: JOIN ... ON a.holder_name = b.holder_name

…without seeing a single real name.

[{\"column\": \"\\\"bank\\\".\\\"core\\\".\\\"accounts\\\".\\\"holder_name\\\"\", \"isHash\": true, \"unmaskLeft\": 0, \"unmaskRight\": 0}]\n

Regex: mask only part of the value

PVML replaces each part that matches the pattern with ***. Some useful patterns:

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Goal	Pattern	Example
Hide the user part of an email	`^[^@]+`	`dana@example.com` → `***@example.com`
Hide a card number except the last 4 digits	`^[0-9]{4}-[0-9]{4}-[0-9]{4}`	`4532-0151-1283-0366` → `***-0366`
Hide all digits	`[0-9]+`	`192.168.1.100` → `*...*`

💡 In JSON, escape a backslash as \\\\. For example the pattern \\d+ is written \"\\\\d+\".

⚠️ MSSQL supports regex masking only from SQL Server 2025.

Masked columns in functions

If a query uses a masked column inside a function, the result is also masked. For example UPPER(holder_name) returns *****. The logic: a function must not become a way around the mask. With hash masking, the hashed value is used, so COUNT(DISTINCT ...) and joins still work.

Remember

If two masking policies use different methods on one column, the result is the full mask: in a conflict, PVML picks the safest result.

\n","_postman_id":"dc91bf15-3305-4208-a7a0-cc996420be9b","auth":{"type":"bearer","bearer":{"basicConfig":[{"key":"token","value":"{{token}}"}]},"isInherited":true,"source":{"_postman_id":"230ce1f4-4c29-4006-87b5-45620ae91c61","id":"230ce1f4-4c29-4006-87b5-45620ae91c61","name":"PVML Documentation","type":"collection"}}},{"name":"Guide: Differential Privacy","item":[],"id":"3d2343e0-ec34-4d8f-81ea-33eece429922","description":"

Differential Privacy (DP) lets people learn from sensitive data without learning about any single person in it. Analysts, partners and AI clients get totals, averages and trends. Each individual in the data stays protected, with a mathematical guarantee.

With PVML you get this on your live data: no copy, no synthetic dataset, no change to the database.

Who uses Differential Privacy

DP is a proven method, used by large public bodies and tech companies:

U.S. Census Bureau. By law (Title 13), the Bureau must keep every answer confidential. In an internal test, it rebuilt records of more than 300 million people only from the published 2010 tables. With older methods, the data would have needed so much noise that it would be too inaccurate for most uses. So the Bureau used DP for the 2020 Census, starting with the redistricting data that states use to draw voting districts. DP-protected data can be shared and combined with other data with no added risk, also against attacks that do not exist yet (Link). Its first product with formal privacy protection was OnTheMap, which shows where workers live and work (Link).
Google published COVID-19 Community Mobility Reports (2020) with DP. Public health teams saw how movement changed in each region, without data about any one person. (Link)
Apple uses DP to learn which emoji and QuickType words people use, to improve suggestions for everyone. (Link)
LinkedIn gives marketers audience engagement insights through its Audience Engagements API, protected with DP. (Link)
Microsoft collects usage data from millions of devices with DP (Link), and published a U.S. broadband usage dataset by zip code with DP to help close the rural broadband gap (Link).

PVML brings the same method to your own databases, as an off-the-shelf policy. You choose the schema, and PVML applies DP at runtime, to every query. No data science team, no changes to your data or your queries, zero effort on your end.

How it works in PVML

You put a DP policy on a schema. From then on, in every VDB with this policy:

Aggregate queries work (counts, sums, averages and more). PVML adds a small amount of random noise to each result, in real time.
For large groups, the noise is tiny. The result is close to the true value and good for analysis.
One person can not be singled out. Results that would describe one person are not returned.

Example: plan a campaign without seeing customers

The marketing team of a bank wants to know, per country, how many customers it has and their average income. They must never see the data of one customer.

The admin puts a DP policy on the \"bank\".\"core\" schema. A marketing analyst runs:

SELECT country, COUNT(*), AVG(income)\nFROM \"bank\".\"core\".\"accounts\"\nGROUP BY country\n

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

country	True count	DP count	True avg income	DP avg income
AUT	461	461.0	36,132	36,173
AZE	423	423.4	33,844	33,915
DEU	443	442.6	34,465	34,340
ESP	409	408.6	34,672	34,627

The analyst sees the same picture as with the true data, and can plan the campaign. The analyst only sees the DP columns. The true values are shown here only to compare.

What you can run

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

You can use	Example
`COUNT(*)`, `COUNT(DISTINCT ...)`	`SELECT COUNT(DISTINCT account_id) FROM accounts`
`SUM`, `AVG`	`SELECT SUM(income), AVG(income) FROM accounts`
`MIN`, `MAX`	`SELECT MIN(income), MAX(income) FROM accounts`
`WHERE`	`... WHERE is_business = true`
`GROUP BY`	`... GROUP BY country`
`HAVING`	`... GROUP BY country HAVING COUNT(*) > 440`
`JOIN` of related tables	`SUM(t.amount)` per country, from `transactions` joined to `accounts`
Functions on the result	`SELECT ROUND(AVG(income)) FROM accounts`

Queries that return single rows, like SELECT * FROM accounts or a list of account IDs, are not allowed. A query about one account returns no result.

Set it up

Standard snapshot. DP needs the data samples of a Standard snapshot (see Refresh Snapshot).
Identifier. Tell PVML who the \"person\" is, for example accounts.account_id (Update Identifiers).
Relations. Link the other tables to the identifier, for example transactions.account_id to accounts.account_id (Update Relations). Then queries on transactions are protected per account too.
DP policy. Create it on the schema (Create DP Policy). In the platform: Policies > Privacy > Differential Privacy.
VDB. Attach it to a VDB, together with a column policy (Create Virtual DB or Update Virtual DB Policies).

📘 More on identifiers and relations: Datasources > Guide: Relations and identifiers.

Tips for great results

Ask about groups, not people. DP works best on large datasets (roughly 10,000 rows or more) and on groups with many people, for example per country rather than per street.
Round for reports. ROUND(AVG(income)) gives clean numbers for dashboards.
Exact totals are fine? Use Aggregation Functions Only instead. It also allows only aggregate queries, but returns exact results. See Guide: How policies work together.
AI clients get the same protection. An AI client connected to the VDB through MCP can answer questions like \"average income per country\", and every answer is protected by DP.

\n","_postman_id":"3d2343e0-ec34-4d8f-81ea-33eece429922","auth":{"type":"bearer","bearer":{"basicConfig":[{"key":"token","value":"{{token}}"}]},"isInherited":true,"source":{"_postman_id":"230ce1f4-4c29-4006-87b5-45620ae91c61","id":"230ce1f4-4c29-4006-87b5-45620ae91c61","name":"PVML Documentation","type":"collection"}}},{"name":"Guide: Writing object names","item":[],"id":"7769d699-3148-4f0b-a19d-0e973818f14f","description":"

Policies, relations, identifiers and descriptions all name database objects. PVML needs the full path with the right quotes for your database. This is the most common reason for errors.

The easy way

Copy the names from Get Snapshot. It returns every schema, table and column exactly as PVML expects them, with quotes.

A policy must protect exactly the object you mean, so names must match exactly: same path, same case.

Full paths

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Object	Format	Example (Postgres)
Schema	`database.schema`	`\"bank\".\"core\"`
Table	`database.schema.table`	`\"bank\".\"core\".\"accounts\"`
Column	`database.schema.table.column`	`\"bank\".\"core\".\"accounts\".\"income\"`

Some request bodies split the path into fields (for example schema and table in a column policy, or schema and tableName in relations). Then each field holds only its own part, with quotes: \"schema\": \"\\\"bank\\\".\\\"core\\\"\", \"table\": \"\\\"accounts\\\"\".

Quotes and the first part, per database

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Database	Quote	First part	Column example
Postgres	`\"`	database	`\"bank\".\"core\".\"accounts\".\"income\"`
Redshift	`\"`	database	`\"bank\".\"core\".\"accounts\".\"income\"`
Snowflake	`\"`	database	`\"BANK\".\"CORE\".\"ACCOUNTS\".\"INCOME\"`
MSSQL	`\"` (or `[ ]`)	database	`\"bank\".\"dbo\".\"accounts\".\"income\"`
Trino	`\"`	catalog	`\"hive\".\"core\".\"accounts\".\"income\"`
Databricks	`	catalog	`main`.`core`.`accounts`.`income`
BigQuery	`	project	`my-project`.`core`.`accounts`.`income`
MySQL	`	(none, the database is the schema)	`bank`.`accounts`.`income`

In JSON

The policy data field is a JSON string, so the quotes inside it are escaped:

\"data\": \"[{\\\"column\\\": \\\"\\\\\\\"bank\\\\\\\".\\\\\\\"core\\\\\\\".\\\\\\\"accounts\\\\\\\".\\\\\\\"income\\\\\\\"\\\", \\\"unmaskLeft\\\": 0, \\\"unmaskRight\\\": 0}]\"\n

This is hard to write by hand. Tip: build the inner JSON as an object in your code, then convert it to a string (for example JSON.stringify or json.dumps). Databases with backticks (BigQuery, Databricks, MySQL) need no escaping inside the string.

Case

Write names with the same upper and lower case as in the snapshot. Inside quotes, \"Accounts\" and \"accounts\" are different names. Snowflake often stores names in upper case.

In SQL queries

Users who run queries can use the normal names of their database. The full path rule is only for policy and metadata bodies.

\n","_postman_id":"7769d699-3148-4f0b-a19d-0e973818f14f","auth":{"type":"bearer","bearer":{"basicConfig":[{"key":"token","value":"{{token}}"}]},"isInherited":true,"source":{"_postman_id":"230ce1f4-4c29-4006-87b5-45620ae91c61","id":"230ce1f4-4c29-4006-87b5-45620ae91c61","name":"PVML Documentation","type":"collection"}}},{"name":"Get Policies","id":"7bfdcda0-d9f7-48a9-86b4-650e915c205d","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"GET","header":[],"url":"https://platform.pvml.com/platform/api/v1/workspaces/{{workspace_id}}/permissions?type=data_privacy","description":"

Returns all the different policies associated with a specific workspace.

Path Parameters

workspace_id(string): The unique identifier of the workspace.
\n
type (string, optional): Filters the permissions to a specific type. Options:
\n
- data_access: column policy
  \n
- data_filter: row policy
  \n
- data_privacy: Differential Privacy (DP) policy
  \n
- data_masking: dynamic masking policy
  \n
- data_validation: Aggregation Functions Only (platform: Privacy tab)
  \n
\n

Request Body

This request does not contain a request body.

Response Body

permissions: Array of permission objects, each containing:

id (string): Unique identifier for the policy.
\n
name (string): Name of the policy.
\n
description (string): Description of the policy (can be empty).
\n
type (string): Type of policy (e.g., data_access).
\n
workspaceId (string): Identifier of the associated workspace.
\n
data (string): JSON string detailing schema, table, and column-level access.
\n
createdAt (string): ISO 8601 timestamp of policy creation.
\n
lastModifiedAt (string): ISO 8601 timestamp of last modification.
\n
datasourceId (string): ID of the data source.
\n
datasourceName (string): Name of the data source.
\n
datasourceType (string): Type of data source (e.g., Postgres).
\n

\n","auth":{"type":"bearer","bearer":{"basicConfig":[{"key":"token","value":"{{token}}"}]},"isInherited":true,"source":{"_postman_id":"230ce1f4-4c29-4006-87b5-45620ae91c61","id":"230ce1f4-4c29-4006-87b5-45620ae91c61","name":"PVML Documentation","type":"collection"}},"urlObject":{"protocol":"https","path":["platform","api","v1","workspaces","{{workspace_id}}","permissions"],"host":["platform","pvml","com"],"query":[{"key":"type","value":"data_privacy"}],"variable":[]}},"response":[{"id":"ca7376d8-5492-4e7b-8174-3cfdf425fc47","name":"Get Policies - 200 OK","originalRequest":{"method":"GET","header":[],"url":{"raw":"https://platform.pvml.com/platform/api/v1/workspaces/{{workspace_id}}/permissions?type=data_privacy","protocol":"https","host":["platform","pvml","com"],"path":["platform","api","v1","workspaces","{{workspace_id}}","permissions"],"query":[{"key":"type","value":"data_privacy"}]}},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json; charset=utf-8"}],"cookie":[],"responseTime":null,"body":"{\n \"permissions\": [\n {\n \"datasourceId\": \"669ba481-7068-535e-88fd-6626e4d492af\",\n \"datasourceName\": \"MyDB\",\n \"datasourceType\": \"BigQuery\",\n \"id\": \"99727aab-d62d-59f2-8cea-6bc23db7c0df\",\n \"name\": \"doctors core details\",\n \"description\": \"access only to doctors' id and name columns\",\n \"type\": \"data_access\",\n \"workspaceId\": \"5a080071-4995-52ef-8dce-9b5ad367a3d4\",\n \"data\": \"[{\\\"table\\\": \\\"`doctors`\\\", \\\"column\\\": \\\"`id`\\\", \\\"schema\\\": \\\"`my-project`.`clinic`\\\"}, {\\\"table\\\": \\\"`doctors`\\\", \\\"column\\\": \\\"`name`\\\", \\\"schema\\\": \\\"`my-project`.`clinic`\\\"}]\",\n \"createdAt\": \"2026-10-29T23:55:57.023059Z\",\n \"lastModifiedAt\": \"2026-10-29T23:55:57.023059Z\"\n },\n {\n \"datasourceId\": \"669ba481-7068-535e-88fd-6626e4d492af\",\n \"datasourceName\": \"MyDB\",\n \"datasourceType\": \"BigQuery\",\n \"id\": \"ac2ffc71-740d-5e6f-b54e-75ad0e3dce3e\",\n \"name\": \"female patients only\",\n \"description\": \"\",\n \"type\": \"data_filter\",\n \"workspaceId\": \"5a080071-4995-52ef-8dce-9b5ad367a3d4\",\n \"data\": \"{\\\"scope\\\": [\\\"`my-project`.`clinic`.`patients`\\\"], \\\"columns\\\": [\\\"`my-project`.`clinic`.`patients`.`gender`\\\"], \\\"predicate\\\": \\\"`my-project`.`clinic`.`patients`.`gender`='F'\\\"}\",\n \"createdAt\": \"2026-10-29T23:55:57.562049Z\",\n \"lastModifiedAt\": \"2026-10-29T23:55:57.562049Z\"\n },\n {\n \"datasourceId\": \"669ba481-7068-535e-88fd-6626e4d492af\",\n \"datasourceName\": \"MyDB\",\n \"datasourceType\": \"BigQuery\",\n \"id\": \"f2214a61-7e05-5526-85cd-df7b98635e6d\",\n \"name\": \"full access\",\n \"description\": \"access to all schemas, tables and columns\",\n \"type\": \"data_access\",\n \"workspaceId\": \"5a080071-4995-52ef-8dce-9b5ad367a3d4\",\n \"data\": \"[{\\\"table\\\": \\\"*\\\", \\\"column\\\": \\\"*\\\", \\\"schema\\\": \\\"*\\\"}]\",\n \"createdAt\": \"2026-10-29T23:55:56.85125Z\",\n \"lastModifiedAt\": \"2026-10-29T23:55:56.85125Z\"\n },\n {\n \"datasourceId\": \"669ba481-7068-535e-88fd-6626e4d492af\",\n \"datasourceName\": \"MyDB\",\n \"datasourceType\": \"BigQuery\",\n \"id\": \"558dba71-52d0-5090-aed5-379aae99f635\",\n \"name\": \"mask location details\",\n \"description\": \"\",\n \"type\": \"data_masking\",\n \"workspaceId\": \"5a080071-4995-52ef-8dce-9b5ad367a3d4\",\n \"data\": \"[{\\\"regex\\\": \\\"\\\", \\\"column\\\": \\\"`my-project`.`clinic`.`locations`.`latitude`\\\", \\\"isHash\\\": false, \\\"unmaskLeft\\\": 0, \\\"unmaskRight\\\": 0}, {\\\"regex\\\": \\\"\\\", \\\"column\\\": \\\"`my-project`.`clinic`.`locations`.`longitude`\\\", \\\"isHash\\\": false, \\\"unmaskLeft\\\": 0, \\\"unmaskRight\\\": 0}]\",\n \"createdAt\": \"2026-10-29T23:55:57.933032Z\",\n \"lastModifiedAt\": \"2026-10-29T23:55:57.933032Z\"\n },\n {\n \"datasourceId\": \"669ba481-7068-535e-88fd-6626e4d492af\",\n \"datasourceName\": \"MyDB\",\n \"datasourceType\": \"BigQuery\",\n \"id\": \"db0b561c-3dba-5816-9621-0e9c1a2742e1\",\n \"name\": \"patients aggregates only\",\n \"description\": \"\",\n \"type\": \"data_validation\",\n \"workspaceId\": \"5a080071-4995-52ef-8dce-9b5ad367a3d4\",\n \"data\": \"{\\\"header\\\": \\\"aggregation\\\", \\\"aggregationPermission\\\": {\\\"tables\\\": [\\\"`my-project`.`clinic`.`patients`\\\"], \\\"schemas\\\": []}}\",\n \"createdAt\": \"2026-10-29T23:55:57.749851Z\",\n \"lastModifiedAt\": \"2026-10-29T23:55:57.749851Z\"\n },\n {\n \"datasourceId\": \"669ba481-7068-535e-88fd-6626e4d492af\",\n \"datasourceName\": \"MyDB\",\n \"datasourceType\": \"BigQuery\",\n \"id\": \"dff14d57-617b-5a67-9328-887760b4ec3a\",\n \"name\": \"private schema\",\n \"description\": \"\",\n \"type\": \"data_privacy\",\n \"workspaceId\": \"5a080071-4995-52ef-8dce-9b5ad367a3d4\",\n \"data\": \"{\\\"schemas\\\": [\\\"`my-project`.`clinic`\\\"]}\",\n \"createdAt\": \"2026-10-29T23:55:58.124131Z\",\n \"lastModifiedAt\": \"2026-10-29T23:55:58.124131Z\"\n }\n ]\n}"}],"_postman_id":"7bfdcda0-d9f7-48a9-86b4-650e915c205d"},{"name":"Create Column Policy","id":"d2a9217f-d8fa-4c75-a75d-af6371ba1468","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[],"body":{"mode":"raw","raw":"{\n \"name\": \"transactions access test2\",\n \"description\": \"access to transactions columns and tables\",\n \"type\": \"data_access\",\n \"data\": \"[{\\\"table\\\": \\\"*\\\", \\\"column\\\": \\\"*\\\", \\\"schema\\\": \\\"*\\\"}]\"\n}","options":{"raw":{"language":"json"}}},"url":"https://platform.pvml.com/platform/api/v1/workspaces/{{workspace_id}}/datasources/{{datasource_id}}/permissions","description":"

This endpoint allows to create a column policy for a specific datasource, without explicitly choosing the structure (using \"*\" as a select all mechanism).

Path Parameters

workspace_id(string): The unique identifier of the workspace.
\n
datasource_id(string): The unique id of the datasource for this policy.
\n

Request Body

Form data containing:

name(string): The name of the new policy.
\n
description (string): A short description.
\n
type (string): The type of the new policy. Options:
\n
- data_access: column policy
  \n
- data_filter: row policy
  \n
- data_privacy: Differential Privacy (DP) policy
  \n
- data_masking: dynamic masking policy
  \n
- data_validation: Aggregation Functions Only (platform: Privacy tab)
  \n
\n
data (json): Json containing the relevant schema tree structure:
\n
- schema(s): Specifies the schema(s) involved.
  \n
- table(s): Identifies one or more tables within the schema(s) to which access is granted.
  \n
- column(s): Lists the specific columns from each table to which access is granted.
  \n
\n

Response Body

The response is a permission object in json format that includes the details of the newly created policy:

id (string): Unique identifier for the policy.
\n
name (string): Name of the policy, describing its purpose or scope.
\n
description (string): A detailed description of what the policy allows.
\n
type (string): The type of policy, e.g., \"data_access\".
\n
workspaceId (string): Identifier for the workspace to which the policy belongs.
\n
data (string): JSON-encoded string representing the schema, table, and columns to which access is granted.
\n
- Each element in the JSON array represents an access object with the following fields:
  \n
  - table (string): The name of the database table.
    \n
  - column (string): The specific column in the table that is accessible.
    \n
  - schema (string): The schema path for the table within the database.
    \n
  \n
\n
createdAt (timestamp, ISO 8601): Timestamp indicating when the policy was created.
\n
lastModifiedAt (timestamp, ISO 8601): Timestamp indicating when the policy was last modified.
\n
datasourceId (string): Identifier for the data source related to the policy.
\n
datasourceName (string): Name of the data source related to the policy.
\n
datasourceType (string): The type of the data source, e.g., Postgres.
\n

💡 Names must be full paths with the right quotes. See Guide: Writing object names.

How to select a whole schema or table

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

You want	Item in `data`
Everything in the datasource	`{\"schema\": \"\", \"table\": \"\", \"column\": \"*\"}`
A whole schema	`{\"schema\": \"<schema>\", \"table\": \"\", \"column\": \"\"}`
A whole table	`{\"schema\": \"<schema>\", \"table\": \"<table>\", \"column\": \"\"}`
One column	`{\"schema\": \"<schema>\", \"table\": \"<table>\", \"column\": \"<column>\"}`

💡 To mean \"all\" for one part, use an empty string (\"\").

This endpoint allows to create a column policy for a specific datasource with explicit selection of the database structure.

Path Parameters

workspace_id(string): The unique identifier of the workspace.
\n
datasource_id(string): The unique id of the datasource for this policy.
\n

Request Body

Form data containing:

name(string): The name of the new policy.
\n
description (string): The name of the new workspace.
\n
type (string): The type of the new policy. Options:
\n
- data_access: column policy
  \n
- data_filter: row policy
  \n
- data_privacy: Differential Privacy (DP) policy
  \n
- data_masking: dynamic masking policy
  \n
- data_validation: Aggregation Functions Only (platform: Privacy tab)
  \n
\n
data (json): Json containing the relevant schema tree structure:
\n
- schema(s): Specifies the schema(s) involved.
  \n
- table(s): Identifies one or more tables within the schema(s) to which access is granted.
  \n
- column(s): Lists the specific columns from each table to which access is granted.
  \n
\n

Response Body

The response is a permission object in json format that includes the details of the newly created policy:

id (string): Unique identifier for the policy.
\n
name (string): Name of the policy, describing its purpose or scope.
\n
description (string): A detailed description of what the policy allows.
\n
type (string): The type of policy, e.g., \"data_access\".
\n
workspaceId (string): Identifier for the workspace to which the policy belongs.
\n
data (string): JSON-encoded string representing the schema, table, and columns to which access is granted.
\n
- Each element in the JSON array represents an access object with the following fields:
  \n
  - table (string): The name of the database table.
    \n
  - column (string): The specific column in the table that is accessible.
    \n
  - schema (string): The schema path for the table within the database.
    \n
  \n
\n
createdAt (timestamp, ISO 8601): Timestamp indicating when the policy was created.
\n
lastModifiedAt (timestamp, ISO 8601): Timestamp indicating when the policy was last modified.
\n
datasourceId (string): Identifier for the data source related to the policy.
\n
datasourceName (string): Name of the data source related to the policy.
\n
datasourceType (string): The type of the data source, e.g., Postgres.
\n

💡 Names must be full paths with the right quotes. See Guide: Writing object names.

Creates a row policy (row-level security). The policy filters the rows a user can see.

Path Parameters

workspace_id (string): The unique identifier of the workspace.
datasource_id (string): The datasource the policy belongs to.

Request Body

name (string): The policy name.
description (string): A short description.
type (string): data_filter.
data (string): A JSON string with:
- predicate (string, required): A SQL boolean expression, like a WHERE clause. Write every column with its full path: catalog.schema.table.column (or project.dataset.table.column in BigQuery). Use the quote style of your database, for example \"...\" in Postgres and `...` in BigQuery (see Guide: Writing object names). You can combine conditions with AND, OR, IN, LIKE and other SQL operators. The \\\" in the API examples is JSON escaping; in the platform, type the predicate as plain SQL.
- scope (array of strings, required): The tables the filter applies to, as schema.table full paths. It can not be empty.
\n

User attributes

To filter by the user who runs the query, put a user attribute in double curly braces, for example:

\"bank\".\"core\".\"branches\".\"city\" = {{bank.city}}\n

PVML replaces {{bank.city}} with the value of the city attribute (in the bank attribute catalog) of the user who runs the query. The attribute must exist in the workspace first.

📘 For a step-by-step tutorial, see Guide: Row-level security (RLS).

Examples

\"main\".\"hr\".\"employees\".\"country\" = 'UK'
\"main\".\"hr\".\"employees\".\"country\" IN ('UK', 'IE') AND \"main\".\"hr\".\"employees\".\"is_active\" = true

Response Body

A permission object:

id (string): The policy ID.
name, description (string).
type (string): data_filter.
workspaceId, datasourceId (string).
data (string): The policy data as a JSON string. It holds predicate, scope and columns (the columns used in the predicate).
createdAt, lastModifiedAt (string, ISO 8601).

💡 datasourceName and datasourceType are empty in this response. Use Get Policies to see them.

In the platform: Policies > Privacy > Differential Privacy.

Creates a Differential Privacy (DP) policy for one or more schemas. See Guide: Differential Privacy.

Path Parameters

workspace_id (string): The unique identifier of the workspace.
datasource_id (string): The datasource the policy belongs to.

Request Body

name (string): The policy name.
description (string): A short description.
type (string): data_privacy.
data (string): A JSON string with:
- schemas (array of strings): The schemas whose query results get differential privacy.
\n

⚠️ Before you start:

The datasource needs a Standard snapshot, not Schema-only (API: profile=true, see Refresh Snapshot).
Set an identifier for the tables.

Response Body

A permission object:

id (string): The policy ID.
name, description (string).
type (string): data_privacy.
workspaceId, datasourceId (string).
data (string): The policy data as a JSON string. It holds schemas.
createdAt, lastModifiedAt (string, ISO 8601).

💡 datasourceName and datasourceType are empty in this response. Use Get Policies to see them.

Creates an Aggregation Functions Only policy. In the platform: Policies > Privacy > Aggregation Functions Only. Users can run only aggregate queries on the chosen schemas or tables, and get exact results.

💡 In the API the type is data_validation.

Path Parameters

workspace_id (string): The unique identifier of the workspace.
datasource_id (string): The datasource the policy belongs to.

Request Body

name (string): The policy name.
description (string): A short description.
type (string): data_validation.
data (string): A JSON string with:
- header (string): Always aggregation.
- aggregationPermission (object): Where only aggregate queries are allowed:
  - schemas (array of strings): Full schema paths. All tables in them are covered.
  - tables (array of strings): Full table paths (schema.table).
  \n
\n

With this example, users can run SELECT gender, COUNT(*) ... GROUP BY gender on the patients table, but not SELECT *.

Response Body

A permission object:

id (string): The policy ID.
name, description (string).
type (string): data_validation.
workspaceId, datasourceId (string).
data (string): The policy data as a JSON string. It holds header and aggregationPermission.
createdAt, lastModifiedAt (string, ISO 8601).

💡 datasourceName and datasourceType are empty in this response. Use Get Policies to see them.

This endpoint allows to create a masking policy for a specific datasource.

Path Parameters

workspace_id(string): The unique identifier of the workspace.
\n
datasource_id(string): The unique id of the datasource for this policy.
\n

Request Body

name (string): The name of the policy.
\n
description (string): A brief description or additional details about the policy.
\n
type (string): The type of the object, which in this case is \"data_masking\".
\n
data (string): JSON-encoded array containing details of the columns to be masked.
\n
- column (string): The fully qualified column name that is subject to masking.
  \n
- unmaskLeft (number): The number of characters to leave unmasked from the beginning of the value.
  \n
- unmaskRight (number): The number of characters to leave unmasked from the end of the value.
  \n
\n

Response Body

The response is a permission object in json format that includes the details of the newly created masking policy:

id (string): Unique identifier for the policy.
\n
name (string): Name of the policy.
\n
description (string): Description or additional details about the policy.
\n
type (string): Type of the permission, in this case data_masking.
\n
workspaceId (string): Identifier for the workspace to which the policy belongs.
\n
data (string): JSON-encoded string containing schemas details.
\n
- column (string): The fully qualified column name that is subject to masking.
  \n
- unmaskLeft (number): The number of characters to leave unmasked from the beginning of the value.
  \n
- unmaskRight (number): The number of characters to leave unmasked from the end of the value.
  \n
\n
createdAt (timestamp, ISO 8601): The timestamp when the permission was created.
\n
lastModifiedAt (timestamp, ISO 8601): The timestamp when the permission was last modified.
\n
vdbId (string): Identifier for the associated VDB, if applicable.
\n
vdbName (string): Name of the associated VDB, if applicable.
\n
datasourceId (string): Identifier for the associated datasource.
\n
datasourceName (string): Name of the associated datasource.
\n
datasourceType (string): Type of the associated datasource.
\n

📘 PVML also supports hash (\"isHash\": true) and regex (\"regex\": \"...\") masking. See Guide: Masking strategies.

💡 Names must be full paths with the right quotes. See Guide: Writing object names.

Creates a write policy. It allows users of a VDB to change data (INSERT, UPDATE) in specific tables or columns. Without a write policy, a VDB is read-only.

Path Parameters

workspace_id (string): The unique identifier of the workspace.
datasource_id (string): The datasource the policy belongs to.

Request Body

name, description (string).
type (string): data_write.
data (string): A JSON array. Each item allows writes to:
- a column: {\"schema\": ..., \"table\": ..., \"column\": \"<column>\"}, or
- a whole table: {\"schema\": ..., \"table\": ..., \"column\": \"\"} (empty column).
\n

In this example, users can update income and is_business in accounts, and write any column in notes. Updates of other columns are blocked.

⚠️ Before you start:

The database user that PVML uses for this datasource needs write rights in the database. PVML can only allow what the database allows.
A write policy does not give read access. Add a column policy for the columns users need to read.
For a whole table, use an empty column (\"\").

Response Body

A permission object, like the other policy types: id, name, description, type (data_write), workspaceId, datasourceId, data (the JSON array), createdAt, lastModifiedAt.

In the platform: Policies > Load Control.

Creates a timeout policy. PVML stops any query of the VDB that runs longer than the limit. Use it to protect your database from slow or expensive queries.

Path Parameters

workspace_id (string): The unique identifier of the workspace.
datasource_id (string): The datasource the policy belongs to.

Request Body

name, description (string).
type (string): data_timeout.
data (string): A JSON object:
- duration (number, required): The maximum run time in nanoseconds. For example: 30 seconds = 30000000000, 5 minutes = 300000000000.
\n

A query that runs longer is stopped.

Response Body

A permission object, like the other policy types: id, name, description, type (data_timeout), workspaceId, datasourceId, data (duration), createdAt, lastModifiedAt.

In the platform: Policies > Load Control.

Creates a row limit policy. A query of the VDB returns at most this number of rows. Use it to stop large data exports.

Path Parameters

workspace_id (string): The unique identifier of the workspace.
datasource_id (string): The datasource the policy belongs to.

Request Body

name, description (string).
type (string): data_limit.
data (string): A JSON object:
- maxRows (number, required): The maximum number of rows in a result.
\n

💡 The query does not fail. PVML returns only the first rows, up to the limit. For example, with maxRows 100, SELECT * FROM accounts returns 100 rows even if the table has 5,000.

Response Body

A permission object, like the other policy types: id, name, description, type (data_limit), workspaceId, datasourceId, data (maxRows), createdAt, lastModifiedAt.

Creates a routines policy. It lists the stored procedures and user-defined functions that users of a VDB may run. Without a routines policy, a VDB can not run any routine.

Path Parameters

workspace_id (string): The unique identifier of the workspace.
datasource_id (string): The datasource the policy belongs to.

Request Body

name, description (string).
type (string): data_routines.
data (string): A JSON array. Each item has:
- schema (string): The full schema name.
- itemName (string): The routine name, quoted like a table name.
- itemType (string): procedure or function.
\n

In this example, users can run the close_month procedure and the is_weekend function. Any other routine is blocked.

💡 Copy the routine names from Get Snapshot (the procedures and functions of each schema).

⚠️ The routine must exist in the datasource snapshot. Refresh the snapshot after you add new routines to the database.

Response Body

A permission object, like the other policy types: id, name, description, type (data_routines), workspaceId, datasourceId, data (the JSON array), createdAt, lastModifiedAt.

Lists all policies of one datasource, with their data.

Path Parameters

workspace_id (string): The unique identifier of the workspace.
datasource_id (string): The unique identifier of the datasource.

Response Body

permissions (array): Policy objects (see Create Column Policy).

Requires the workspace admin or owner role.

Returns one policy with its data.

Path Parameters

workspace_id (string): The unique identifier of the workspace.
datasource_id (string): The unique identifier of the datasource.
policy_id (string): The policy ID.

Requires the workspace admin or owner role.

Changes a policy. All VDBs that use it get the change right away.

Path Parameters

workspace_id (string): The unique identifier of the workspace.
datasource_id (string): The unique identifier of the datasource.
policy_id (string): The policy ID.

Request Body

The full policy, the same fields as when you create it: name, description, type, data. Fields you leave out are not kept.

Response Body

Status 201 with the updated permission object.

Requires the workspace admin or owner role.

Creates a copy of a policy, named <name> - copy. The copy is not attached to any VDB. Use it as a starting point for a similar policy.

Path Parameters

workspace_id (string): The unique identifier of the workspace.
datasource_id (string): The unique identifier of the datasource.
policy_id (string): The policy to copy.

Response Body

The new permission object.

Requires the workspace admin or owner role.

Deletes a policy. It is removed from every VDB that uses it.

Path Parameters

workspace_id (string): The unique identifier of the workspace.
datasource_id (string): The datasource of the policy.
policy_id (string): The policy ID.

Response Body

Status 200 with an empty body.

💡 Check Get Virtual DB Policies first: users of those VDBs lose what the policy gave them.

Requires the workspace admin or owner role.

PVML provides full granularity in access policies to support any level of security and privacy according to the specific requirements of the business use case. Policies can be attached to a VDB to create a certain scope for a datasource.

The platform groups policies in these tabs. The API name of each type is in brackets.

Column: read access to schemas, tables and columns (data_access)
Row: filters rows (data_filter)
Masking: hides values (data_masking)
Privacy: two kinds:
- Differential Privacy (data_privacy)
- Aggregation Functions Only (data_validation)
\n
Load Control: two kinds:
- Timeout (data_timeout)
- Row limit (data_limit)
\n
Write: INSERT and UPDATE (data_write)
Routines: stored procedures and functions (data_routines)

📘 Guides in this section: Row-level security (RLS), How policies work together, Masking strategies, Differential Privacy, Writing object names.

Column Level Policy

Specifies the parts of a data source that are accessible, including schemas, tables, and individual columns.
\n
A column-level policy must be added to a VDB for it to be valid. Ensure this is set up.
\n

Row Level Policy

Filters the rows a user can see, with a SQL condition like \"main\".\"crm\".\"customers\".\"city\" = 'London'.
You can combine conditions with AND, OR, IN and other SQL operators.
You can use user attributes, for example \"bank\".\"core\".\"branches\".\"city\" = {{bank.city}}. Each user sees only the rows that match their own attributes.
See Guide: Row-level security (RLS) for a full tutorial.

Privacy: Differential Privacy

💡 What is Differential Privacy?

Differential Privacy is a mathematical framework that offers the strongest data safeguard in data-driven systems.
\n
It achieves this by adding controlled noise to the output of a query or algorithm, making it statistically indistinguishable whether a particular individual’s data was included or excluded.
\n
This nominal amount of variance is insignificant in a broader analytical context, but is crucial to create a robust barrier against attempts to extract sensitive information.
\n

\n $\"A%20DP%20algorithm%20makes%20it%20statistically%20indistinguishable%20whether%20a%20particular%20individual’s%20data%20was%20included%20or%20excluded%20in%20the%20computation%20(so%20whether%20there%20were%2010K%20records%20or%209,999%20records).\"$ \n\n

A Differential Privacy policy allows to choose a schema for which outputs will be differentially private.
\n
With a DP policy in place, the user can extract insights about populations (groups of identifiers as defined when connecting the datasource) but cannot access raw data for individual identifiers or very small samples.
\n
This mechanism is based on mathematical Differential Privacy algorithms that are applied in real time and require no additional configurations or alterations to the underlying data.
\n

💡 When should I use a Differential Privacy policy?

When you need to protect the privacy of individuals in the data (e.g., users, transactions, etc.).
\n
When your focus is on statistical analysis rather than retrieving or analyzing values related to individual records.
\n
When working with large datasets (roughly >10K records) rather than small datasets.
\n

⚠️ Note:

To use a Differential Privacy policy, the datasource needs a Standard snapshot, and an Identifier must be configured for the datasource.
\n
Differential Privacy algorithms can be highly complex, thus adding some overhead in query execution times.
\n

📘 See Guide: Differential Privacy for examples, what you can run and how to set it up.

Masking Policy

Hides the values of chosen columns in query results, fully or partly. The data in your database does not change.
With hash masking, users can still join and count on a masked column without seeing its values.
See Guide: Masking strategies.

Privacy: Aggregation Functions Only

Users can run only aggregate queries (COUNT, SUM, AVG with GROUP BY and so on) on the chosen schemas or tables. SELECT * and other row-level queries are blocked.
Results are exact, with no noise. Use it when totals are fine to share, but single rows are not.
In the API the type is data_validation. See Create Aggregation Functions Only Policy.

Write Policy

Allows INSERT and UPDATE in chosen tables or columns. Without it, a VDB is read-only.

Load Control: Timeout and Row Limit

Timeout stops queries that run too long.
Row limit caps the number of rows a query returns.
Together they protect your database and your cloud bill from heavy queries.

Routines Policy

An allow list of stored procedures and functions that users may run.

\n","_postman_id":"19b40658-590d-463a-baa2-168c5fbc9d3c","auth":{"type":"bearer","bearer":{"basicConfig":[{"key":"token","value":"{{token}}"}]},"isInherited":true,"source":{"_postman_id":"230ce1f4-4c29-4006-87b5-45620ae91c61","id":"230ce1f4-4c29-4006-87b5-45620ae91c61","name":"PVML Documentation","type":"collection"}}},{"name":"Connections","item":[{"name":"REST API","item":[{"name":"Create User API Key","id":"227af741-9263-4a29-931d-a3ea5a91d8a1","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[],"body":{"mode":"raw","raw":"{\n \"name\": \"reporting script\",\n \"description\": \"used by the nightly report\",\n \"expiration\": 1766750237000\n}","options":{"raw":{"language":"json"}}},"url":"https://platform.pvml.com/platform/api/v1/workspaces/{{workspace_id}}/users/{{user_id}}/token","description":"

Creates a REST API key for a user (a person or a service account). In the platform: Connections > REST API. Send the key as Authorization: Bearer <key>.

Path Parameters

workspace_id(string): The unique identifier of the workspace.
\n
user_id (string): The unique identifier of the user in the workspace.
\n

Request Body

name (string): A name for the key.
\n
description (string): A string that describes the token's purpose.
\n
expiration (string): The token expiration time represented in Unix epoch time, measured in milliseconds.
\n

Response Body

token (string): The API key. You see it only once.
\n
tokenId (string): A unique identifier for the token instance, used for tracking or revocation.
\n

Lists the API keys of the workspace. The response never includes the secret key itself: PVML shows it only once, when you create it.

Path Parameters

workspace_id (string): The unique identifier of the workspace.

Response Body

tokensMetadata (array). Each item has Id (use it to revoke), Name, Description, TargetUserEmail (the user the key acts as), CreatorUserEmail, CreatedAt, ExpirationDate (Unix time in ms), IsRevoked.

💡 Revoked keys are listed too, so you keep a history.

Requires the workspace admin or owner role.

This endpoint allows to revoke an API token.

Path Parameters

workspace_id(string): The unique identifier of the workspace.

Request Body

tokenId (string): A unique identifier of the token to revoke.

Response Body

Upon successfully revoking the token, the server returns a status code of 200 and an empty JSON response.

API keys for this REST API. In the platform: Connections > REST API.

See the Connections folder for when to use which.

\n","_postman_id":"e71a9430-590a-4251-8588-c307e311e45b","auth":{"type":"bearer","bearer":{"basicConfig":[{"key":"token","value":"{{token}}"}]},"isInherited":true,"source":{"_postman_id":"230ce1f4-4c29-4006-87b5-45620ae91c61","id":"230ce1f4-4c29-4006-87b5-45620ae91c61","name":"PVML Documentation","type":"collection"}}},{"name":"ODBC / JDBC","item":[{"name":"Create ODBC/JDBC Connection String","id":"98e5363a-e669-420f-a902-5dbd35e93204","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[],"body":{"mode":"raw","raw":"{\n \"name\": \"tableau\",\n \"description\": \"connection for the BI team\",\n \"expiration\": 1798761600000\n}","options":{"raw":{"language":"json"}}},"url":"https://platform.pvml.com/platform/api/v1/workspaces/{{workspace_id}}/vdbs/{{vdb_id}}/users/{{user_id}}/connection_strings","description":"

Creates an ODBC/JDBC connection string for one user and one VDB. A BI tool, SQL editor or app uses it to run SQL on the VDB, as that user. In the platform: Connections > ODBC / JDBC > Create New.

See the Connections folder for the full flow and an example.

Path Parameters

workspace_id (string): The unique identifier of the workspace.
vdb_id (string): The unique identifier of the VDB.
user_id (string): The user (person or service account) the tool acts as. The user must have access to the VDB.

Request Body

name (string): A name for the connection string.
description (string): A short description.
expiration (number, required): Expiry time, Unix time in milliseconds. Must be in the future.

Response Body

A DataSourceConnectionInfo object. Its fields depend on the type of the datasource, because PVML looks like that datasource to the client. For example:

BigQuery: host (a BigQuery API endpoint, for example bigquery-proxy.pvml.com:443/bigquery/v2/, without https://) and credentialFile (the JSON key file, as text). Use them with your BigQuery driver or client library as a custom API endpoint and a service account key.
Databricks: host, HTTP path and access token.
Other types: a URL (JDBC URL or connection URL) and, for some types, a token.

⚠️ The response holds secret credentials. Keep it safe. You can see it only once.

To list or revoke connection strings, see Get ODBC/JDBC Connection Strings and Revoke ODBC/JDBC Connection String.

Lists the ODBC/JDBC connection strings in a workspace, like the Connections > ODBC / JDBC page in the platform. The response has no secrets.

Path Parameters

workspace_id (string): The unique identifier of the workspace.

Response Body

connectionStringsMetadata (array). Each item has:
- id (string): The connection string ID. Use it to revoke.
- name, description (string).
- vdbId (string), vdbType (string): The VDB it connects to.
- targetUserEmail (string): The user who uses the connection.
- creatorUserEmail (string): The user who created it.
- createdAt, expirationDateTime (number): Unix time in milliseconds.
- isRevoked (boolean).
\n

Revokes a connection string. The client can no longer connect with it.

Path Parameters

workspace_id (string): The unique identifier of the workspace.

Request Body

connectionStringId (string): The ID from Get ODBC/JDBC Connection Strings.

Response Body

Status 200 with an empty body.

Connection strings for BI tools, SQL editors and apps. In the platform: Connections > ODBC / JDBC.

See the Connections folder for the full flow.

\n","_postman_id":"2569d2a9-3775-4fec-bc21-25476e05c3cf","auth":{"type":"bearer","bearer":{"basicConfig":[{"key":"token","value":"{{token}}"}]},"isInherited":true,"source":{"_postman_id":"230ce1f4-4c29-4006-87b5-45620ae91c61","id":"230ce1f4-4c29-4006-87b5-45620ae91c61","name":"PVML Documentation","type":"collection"}}}],"id":"f47d772e-7c61-473b-bf8d-28d5227a417c","description":"

Connections let tools outside the PVML platform reach PVML. The platform has two kinds, on two tabs of the Connections page:

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Platform tab	What it is	Use it for
REST API	An API key	Calling this API: scripts, apps, SCIM, the admin MCP server
ODBC / JDBC	A connection string for one VDB	Running SQL on a VDB from a BI tool (Tableau, Power BI), a SQL editor or an app

Both are created for a user (a person or a service account) and both have an expiry date. Whatever the tool does, it does as that user: same role, same VDB policies, and every query is in the audit log.

REST API keys

Create one with Create User API Key. Send it in every request as Authorization: Bearer <key>.
The key has the role of its user. A key of a member can not do admin actions.
You see the key only once. List keys with Get API Keys (no secrets in the list) and revoke them with Revoke API Key.

ODBC / JDBC connection strings

A connection string connects a tool to one VDB. To the tool, PVML looks like the database behind the VDB. So you use the normal driver of that database: a VDB on BigQuery is used with the BigQuery driver, a VDB on Databricks with the Databricks driver, and so on. The tool needs no PVML plugin.

Example: the BI team wants Tableau on the \"London branch\" VDB.

Create a service account for the dashboard, for example tableau-london (Users > Create Service Account).
Give it access to the VDB (Virtual DBs > Update Virtual DB Users). The user must have access to the VDB.
Create the connection string (Create ODBC/JDBC Connection String) with a name, a description and an expiry date.
Copy the fields from the response into Tableau. They depend on the datasource type, for example:
- BigQuery: a Host and a JSON key file (in the platform: Download JSON-key file).
- Databricks: a Host, an HTTP Path and an Access Token.
- Other types: a JDBC URL or Connection URL, and for some types a Token.
\n
Tableau now sees only what the VDB allows: the London rows, with masked names. Every dashboard refresh is in the audit log.
When the dashboard is retired, revoke the connection (Revoke ODBC/JDBC Connection String). It also stops working by itself on the expiry date.

⚠️ You see the secret fields only once, in the response. Store them in your tool or secret manager right away.

💡 Why one connection per tool? If one tool is lost or no longer needed, you revoke only its connection. The other tools keep working, and the audit log shows which tool ran which query.

\n","_postman_id":"f47d772e-7c61-473b-bf8d-28d5227a417c","auth":{"type":"bearer","bearer":{"basicConfig":[{"key":"token","value":"{{token}}"}]},"isInherited":true,"source":{"_postman_id":"230ce1f4-4c29-4006-87b5-45620ae91c61","id":"230ce1f4-4c29-4006-87b5-45620ae91c61","name":"PVML Documentation","type":"collection"}}},{"name":"GenAI","item":[{"name":"MCP","item":[{"name":"Get MCPs","id":"bb6b312e-c881-47cb-bc27-87c621b1e35d","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"GET","header":[],"url":"https://platform.pvml.com/platform/api/v1/workspaces/{{workspace_id}}/mcps","description":"

Lists the MCP servers of the workspace (one per VDB).

Path Parameters

workspace_id (string): The unique identifier of the workspace.

Query Parameters (optional)

pageNumber, pageSize (max 500): For pages.
searchText (string): Filter by name.

Response Body

mcps (array). Each item: id, name (the VDB name), description, type (virtual DB), url (the MCP URL), internalReferences.vdbId, createdAt.
pagination (object), when you ask for pages.

Requires the workspace admin or owner role.

Lists the MCP servers that the current user may use. Use it in your app to show each user the AI data sources they can connect to.

Path Parameters

workspace_id (string): The unique identifier of the workspace.

Response Body

mcps (array): The same format as Get MCPs. null when there are none.

Any workspace member can call it.

Returns one MCP server.

Path Parameters

workspace_id (string): The unique identifier of the workspace.
mcp_id (string): The MCP server ID.

Response Body

mcp: See Get MCPs.

Requires the workspace admin or owner role.

Lists the tools of an MCP server, exactly as an AI client sees them.

Path Parameters

workspace_id (string): The unique identifier of the workspace.
mcp_id (string): The MCP server ID.

Response Body

mcpTools (array): name, description (what the AI reads), inputSchema and isAllowed.

A VDB MCP server has two tools:

describe-vdb-<vdb_id>: returns the schema, descriptions and relations of the VDB.
execute-sql-vdb-<vdb_id>: runs a SQL query. Parameters: query (required) and userQuestion (the user's original question, saved in the audit log).

💡 The tool descriptions include the VDB name and description. A clear VDB description helps the AI pick the right VDB.

Requires the workspace admin or owner role.

Returns a ready-to-use config block for AI clients (the mcpServers format of Cursor, Claude Desktop and others).

Path Parameters

workspace_id (string): The unique identifier of the workspace.
mcp_id (string): The MCP server ID.

Response Body

An object with one key, the server name, and its url and headers.

💡 The config never contains a real key. Replace <TOKEN_PLACEHOLDER> with Bearer <your API key>, or remove headers to sign in with OAuth.

Any workspace member with access to the VDB can call it.

Returns the VDB behind an MCP server (the opposite of Get Virtual DB MCP).

Path Parameters

workspace_id (string): The unique identifier of the workspace.
mcp_id (string): The MCP server ID.

Response Body

vdbId (string).

Requires the workspace admin or owner role.

Starts an MCP session with the MCP server of a VDB. AI clients do this for you. Use this request to test the connection.

Path Parameters

workspace_id (string): The unique identifier of the workspace.
vdb_id (string): The VDB ID.

Request Body

A JSON-RPC initialize message.

Response

The server info and capabilities.
The response header Mcp-Session-Id. Send it in the next requests.

Without a valid sign-in, the response is status 401.

The user must be a workspace member with access to the VDB.

From the response headers of Initialize. Not needed for Initialize itself.

\n"}],"body":{"mode":"raw","raw":"{\n \"jsonrpc\": \"2.0\",\n \"id\": 2,\n \"method\": \"tools/list\"\n}","options":{"raw":{"language":"json"}}},"url":"https://platform.pvml.com/platform/api/v1/mcp/workspaces/{{workspace_id}}/vdbs/{{vdb_id}}","description":"

Lists the tools of the VDB MCP server (JSON-RPC tools/list).

Path Parameters

workspace_id (string): The unique identifier of the workspace.
vdb_id (string): The VDB ID.

Send the Mcp-Session-Id header from MCP: Initialize.

From the response headers of Initialize. Not needed for Initialize itself.

\n"}],"body":{"mode":"raw","raw":"{\n \"jsonrpc\": \"2.0\",\n \"id\": 3,\n \"method\": \"tools/call\",\n \"params\": {\n \"name\": \"execute-sql-vdb-{{vdb_id}}\",\n \"arguments\": {\n \"query\": \"select count(*) as accounts from `my-project`.`core`.`accounts`;\",\n \"userQuestion\": \"How many accounts are there?\"\n }\n }\n}","options":{"raw":{"language":"json"}}},"url":"https://platform.pvml.com/platform/api/v1/mcp/workspaces/{{workspace_id}}/vdbs/{{vdb_id}}","description":"

Runs a tool (JSON-RPC tools/call). This example runs SQL with execute-sql-vdb-<vdb_id>.

Path Parameters

workspace_id (string): The unique identifier of the workspace.
vdb_id (string): The VDB ID.

Request Body

params.name: The tool name from MCP: List Tools.
params.arguments: query (SQL) and userQuestion (the user's original question).

Response

The result rows as text, for example [[\"accounts\"],[5000]]. If a policy blocks the query, isError is true.

From the response headers of Initialize. Not needed for Initialize itself.

Lists the tools of the workspace MCP server (for admins). Start the session first with an initialize message, as in MCP: Initialize, but on this URL.

Path Parameters

workspace_id (string): The unique identifier of the workspace.

Tools

create-datasource-aggregation-policy
create-datasource-column-policy
create-datasource-differential-privacy-policy
create-datasource-limit-policy
create-datasource-masking-policy
create-datasource-row-level-policy
create-datasource-timeout-policy
create-virtual-db
delete-datasource-policy
delete-virtual-db
get-current-user
get-datasource-structure
get-user-attributes
get-virtual-db
get-workspace-attributes
list-datasource-policies
list-datasources
list-workspace-groups
list-workspace-users
update-datasource-aggregation-policy
update-datasource-column-policy
update-datasource-differential-privacy-policy
update-datasource-limit-policy
update-datasource-masking-policy
update-datasource-row-level-policy
update-datasource-timeout-policy
update-virtual-db-info
update-virtual-db-policies
update-virtual-db-users-groups

The example response shows the first tools only.

Requires the workspace admin or owner role.

MCP (Model Context Protocol) is the standard way for AI applications to use tools, such as ChatGPT, Claude, Cursor, Copilot Studio or your own agent. PVML gives you two kinds of MCP servers.

1. The MCP server of a VDB (for data questions)

Every VDB gets its own MCP server automatically. An AI client that connects to it can:

describe the VDB: the tables, columns, descriptions and relations the user can see, and
run SQL on the VDB.

The AI works as the user who connected. It gets exactly the same column, row, masking and other policies as that user in a BI tool. The AI can not see more than the user, and every query is in the audit log, including the user's original question. This is the logic of PVML: one set of policies, for every client.

URL: https://platform.pvml.com/platform/api/v1/mcp/workspaces/{workspace_id}/vdbs/{vdb_id}

2. The workspace MCP server (for admins)

With this server, an admin can manage PVML with AI, for example: \"Create a VDB for the sales team with access to the orders table, and mask the email column\". It has tools to list datasources and users, and to create and change VDBs and policies. Only workspace admins and owners can use it.

URL: https://platform.pvml.com/platform/api/v1/mcp/workspaces/{workspace_id}/pvml

\n\n

OAuth (recommended for people): most AI clients support it. Add the URL in the client. The client opens a PVML sign-in page in the browser, and the user logs in to PVML as usual.
API key (for scripts and servers): send Authorization: Bearer <API key>. The key acts as its user, so give it to a service account with only the access it needs.

How to connect a client

Find the VDB's MCP server: Get Virtual DB MCP returns its mcpId.
Get MCP Connection Config returns a ready config block. Paste it in your AI client and replace <TOKEN_PLACEHOLDER> with Bearer <your API key>, or remove the header to use OAuth.

Tips for better AI answers

Add descriptions and relations to the datasource (see Datasources). The AI reads them when it describes the VDB.
Keep each VDB small and focused on one task. The AI gets less noise and uses fewer tokens.

Try it in Postman

The requests MCP: Initialize, MCP: List Tools and MCP: Call Tool show the protocol step by step. MCP uses JSON-RPC over HTTP (\"streamable HTTP\"). Copy the Mcp-Session-Id response header from Initialize into the mcp_session_id variable.

\n","_postman_id":"4c5f8b21-24a0-45d6-9bcc-506bd78e8bad","auth":{"type":"bearer","bearer":{"basicConfig":[{"key":"token","value":"{{token}}"}]},"isInherited":true,"source":{"_postman_id":"230ce1f4-4c29-4006-87b5-45620ae91c61","id":"230ce1f4-4c29-4006-87b5-45620ae91c61","name":"PVML Documentation","type":"collection"}}},{"name":"LLMs","item":[{"name":"Create LLM - OpenAI","id":"843ceed6-540e-4418-b895-c0adee5b718f","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[],"body":{"mode":"raw","raw":"{\n \"name\": \"workspace gpt\",\n \"description\": \"system LLM for the workspace\",\n \"workspaceId\": \"{{workspace_id}}\",\n \"vendorName\": \"openAi\",\n \"modelName\": \"gpt-4.1-2025-04-14\",\n \"token\": \"{{openai_api_key}}\",\n \"llmProps\": {\n \"temperature\": 0.7,\n \"maxTokens\": null\n }\n}","options":{"raw":{"language":"json"}}},"url":"https://platform.pvml.com/platform/api/v1/workspaces/{{workspace_id}}/llms","description":"

Connects an LLM to the workspace.

Path Parameters

workspace_id (string): The unique identifier of the workspace.

Request Body

name (string): A name for the LLM.
description (string): A short description.
workspaceId (string): The workspace ID.
vendorName (string): The vendor, from Get Supported LLMs (for example openAi, anthropic, databricks).
modelName (string): A model of that vendor, from Get Supported LLMs.
token (string): The API key of the model provider. On update, send \"\" to keep the current key.
llmProps (object): Model settings. The keys depend on the vendor:
- OpenAI: temperature, maxTokens.
- Anthropic: maxTokens, reasoningEffort, thinking, temperature (optional).
- Databricks: temperature, url (the serving endpoint URL).
- Azure: azure_endpoint, deploymentName, openai_api_version, temperature.
- OpenAI-compatible and NVIDIA NIM: base_url, model_name, maxTokens.
- Custom: any key-value pairs your model needs.
\n

Response Body

The LLM object: id, name, description, workspaceId, vendorName, modelName, url, llmProps, createTime and lastModifiedAt (Unix time in milliseconds). The token is never returned.

Connects a Databricks model serving endpoint as an LLM. See Create LLM - OpenAI for all fields.

Path Parameters

workspace_id (string): The unique identifier of the workspace.

Request Body

Same as Create LLM - OpenAI, with vendorName databricks and llmProps:

temperature (number).
url (string): The serving endpoint URL.

Response Body

The LLM object: id, name, description, workspaceId, vendorName, modelName, url, llmProps, createTime and lastModifiedAt (Unix time in milliseconds). The token is never returned.

Returns one LLM.

Path Parameters

workspace_id (string): The unique identifier of the workspace.
llm_id (string): The unique identifier of the LLM.

Response Body

The LLM object: id, name, description, workspaceId, vendorName, modelName, url, llmProps, createTime and lastModifiedAt (Unix time in milliseconds). The token is never returned.

Returns all LLMs in the workspace.

Path Parameters

workspace_id (string): The unique identifier of the workspace.

Response Body

workspaceLlms (array): LLM objects (see Get LLM).

Returns the LLM vendors and models PVML supports. Use these values in vendorName and modelName.

Response Body

keysOrder (array): The vendors, in display order.
data (object): For each vendor, the list of model names.

The example shows only part of the list.

Updates an LLM and replaces its API key.

Path Parameters

workspace_id (string): The unique identifier of the workspace.
llm_id (string): The unique identifier of the LLM.

Request Body

The full LLM object, the same fields as Create LLM - OpenAI, plus id. Fields you leave out are reset.

Response Body

The LLM object: id, name, description, workspaceId, vendorName, modelName, url, llmProps, createTime and lastModifiedAt (Unix time in milliseconds). The token is never returned.

Updates an LLM and keeps its API key (send \"token\": \"\").

Path Parameters

workspace_id (string): The unique identifier of the workspace.
llm_id (string): The unique identifier of the LLM.

Request Body

The full LLM object, the same fields as Create LLM - OpenAI, plus id. Fields you leave out are reset.

Response Body

The LLM object: id, name, description, workspaceId, vendorName, modelName, url, llmProps, createTime and lastModifiedAt (Unix time in milliseconds). The token is never returned.

Deletes an LLM.

Path Parameters

workspace_id (string): The unique identifier of the workspace.
llm_id (string): The unique identifier of the LLM.

Response Body

Status 200 with an empty body.

⚠️ You can not delete the LLM while it is the System LLM. Call Remove System LLM first.

Returns the System LLM of the workspace.

Path Parameters

workspace_id (string): The unique identifier of the workspace.

Response Body

llmId (string): The ID of the System LLM. Empty (\"\") means PVML uses its internal model.

Requires the workspace admin or owner role.

Sets an LLM of the workspace as the System LLM. PVML uses it for the PII scan, Scan Descriptions and Suggest Relations.

Path Parameters

workspace_id (string): The unique identifier of the workspace.

Request Body

llmId (string): The LLM ID, from Create LLM or Get LLMs.

Response Body

Status 200 with an empty body.

Requires the workspace admin or owner role.

Removes the System LLM. PVML goes back to its internal model. The LLM itself is not deleted.

Path Parameters

workspace_id (string): The unique identifier of the workspace.

Response Body

Status 200 with an empty body.

Requires the workspace admin or owner role.

An LLM is a connection to a language model of your choice (OpenAI, Anthropic, Google, Azure, Databricks, an OpenAI-compatible server, and more). Use Get Supported LLMs to see the vendors and models you can use.

PVML uses an LLM only for three helper features: the PII scan, Scan Descriptions and Suggest Relations. Policy enforcement never uses an LLM: every query is checked by deterministic rules. This is the System LLM. If you do not set one, PVML uses its internal model.

How to use your own model:

Create an LLM with Create LLM.
Set it as the workspace System LLM with Set System LLM.
To go back to the PVML internal model, call Remove System LLM.

In the PVML UI, the System LLM is under Settings > General:

[SCREENSHOT: system_llm.png]

💡 The token (your model API key) is saved securely and is never returned in responses.

💡 Make sure the API key is valid before you save the LLM.

\n","_postman_id":"cf464df8-5110-4e4d-86d1-0d06809a530f","auth":{"type":"bearer","bearer":{"basicConfig":[{"key":"token","value":"{{token}}"}]},"isInherited":true,"source":{"_postman_id":"230ce1f4-4c29-4006-87b5-45620ae91c61","id":"230ce1f4-4c29-4006-87b5-45620ae91c61","name":"PVML Documentation","type":"collection"}}}],"id":"e16d2861-faa7-4237-940f-ee527c49e433","description":"

\n\n

PVML gives AI applications secure access to your data. Every VDB is exposed as an MCP server, so any AI client can query it with the same policies and audit as any other client.

To help AI clients write correct queries, each VDB comes with a Semantic Layer.

Semantic Layer

When an AI client describes a VDB through MCP, PVML returns only what the VDB allows: its tables and columns, with their descriptions and relations. This is the Semantic Layer.

Benefits:

Fewer tokens: the AI client gets only the tables of this VDB, not the whole database.
Better answers: a small, focused schema with clear descriptions helps the AI client pick the right tables and joins.
Compliance: columns that the VDB does not allow (for example gender for a loan team) never reach the AI client.

The VDB is consumed as an MCP. It defines the scope of data and metadata that the AI client can see.

\n $\"The%20Semantic%20Layer%20(descriptions)\"$ \n\n

System LLM

Some PVML features use an LLM: the PII scan, Scan Descriptions and Suggest Relations. By default PVML uses its internal model. You can connect your own model and set it as the workspace System LLM. See the LLMs section below.

All queries from AI clients go through the PVML engine. Results always follow each user's permissions.

\n","_postman_id":"e16d2861-faa7-4237-940f-ee527c49e433","auth":{"type":"bearer","bearer":{"basicConfig":[{"key":"token","value":"{{token}}"}]},"isInherited":true,"source":{"_postman_id":"230ce1f4-4c29-4006-87b5-45620ae91c61","id":"230ce1f4-4c29-4006-87b5-45620ae91c61","name":"PVML Documentation","type":"collection"}}},{"name":"Audit","item":[{"name":"Get Audit Records","id":"dee99b86-ff6d-435b-b5f0-4f1bc634b5cf","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"GET","header":[],"url":"https://platform.pvml.com/platform/api/v1/workspaces/{{workspace_id}}/query-audit?projectionColumns=id,query,duration,source,startTime,status,endTime,userEmail,datasourceType,userQuestion&pageSize=15&pageNumber=1","description":"

Returns query records from the audit. In the platform: Data Access Audit.

Path Parameters

workspace_id(string): The unique identifier of the workspace.
\n
projectionColumns (string, query): A comma-separated list of specific columns to include in the response. Example values include id, query, duration, source, startTime, status, endTime, userEmail, datasourceType, userQuestion.
\n
pageSize (number, query): The number of results to return per page. Defaults to 15.
\n
pageNumber (number, query): The page number of results to retrieve. Defaults to 1.
\n

Request Body

This request does not contain a request body.

Response Body

data (array): A list of audit entries, each containing details about a specific audited operation:

startTime (timestamp, ISO 8601): The time when the query execution started.
\n
status (string): The status of the query execution (e.g., Success, Failure).
\n
endTime (timestamp, ISO 8601): The time when the query execution ended.
\n
duration (number): The duration of the query execution in milliseconds.
\n
query (string): The SQL query that was executed.
\n
userEmail (string): The email address of the user who executed the query.
\n
datasourceType (string): The type of data source used for the query (e.g., Databricks, Snowflake).
\n
source (string): The source from which the query was initiated (e.g., Connector, API).
\n
id (string): The unique identifier for the query or operation.
\n

pagination (object): Contains pagination details for the response.

totalRecords (number): The total number of query audit entries available.
\n
currentPage (number): The current page number in the results.
\n
totalPages (number): The total number of pages available.
\n
pageSize (number): The number of query audit entries returned per page.
\n
nextPage (number or null): The page number of the next page, or null if there are no more pages.
\n
prevPage (number or null): The page number of the previous page, or null if it is the first page.
\n

Returns one query record from the audit. In the platform: Data Access Audit > Record Details.

Path Parameters

workspace_id(string): The unique identifier of the workspace.
\n
audit_record_id (string): The unique identifier of the audit record.
\n

Request Body

This request does not contain a request body.

Response Body

data (object): Contains detailed information about the record, including:

startTime (timestamp, ISO 8601): The start time of the operation.
\n
status (string): The current status of the operation (e.g., Success, Failure).
\n
endTime (timestamp, ISO 8601): The end time of the operation.
\n
duration (number): The duration of the operation in milliseconds.
\n
query (string): The SQL query executed during the operation.
\n
userId (string): Unique identifier for the user who executed the operation.
\n
userEmail (string): Email address of the user who executed the operation.
\n
datasourceId (string): Unique identifier of the data source used in the operation.
\n
datasourceType (string): The type of data source.
\n
source (string): The source from which the operation was initiated (e.g., Connector, API).
\n
traceId (string): Unique identifier used for tracing the operation.
\n
id (string): Unique identifier for the audit record.
\n
workspaceId (string): Unique identifier of the workspace where the operation occurred.
\n
vdbId (string): Unique identifier for the VDB with which the query was executed.
\n
vdbName (string): Name of the VDB with which the query was executed.
\n

Returns the activity log of the workspace. In the platform: System Audit. It shows who changed what, and when. For example, who created a policy, changed a VDB or revoked a key. (Queries are in Get Audit Records.)

Path Parameters

workspace_id (string): The unique identifier of the workspace.

Query Parameters

pageSize (number, max 500): Items per page.
cursor (string): The nextCursor from the previous page.
Filters: use a field name as the parameter, and a JSON value {\"operator\": \"eq|gte|lte|like\", \"value\": ...}. For example:
- action={\"operator\":\"eq\",\"value\":\"update\"}
- userEmail={\"operator\":\"eq\",\"value\":\"dana@example.com\"}
- timestamp={\"operator\":\"gte\",\"value\":\"2026-10-01T00:00:00.000Z\"} (repeat with lte for a range)
\n

Response Body

data (array). Each item: timestamp, userEmail, action (create, update, delete, ...), description, status, error, resources (type, id, name) and request (the request body).
pagination: nextCursor.

Requires the workspace admin or owner role.

PVML keeps two audit logs. In the platform they are two pages:

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Platform	API	What it records
Data Access Audit	Get Audit Records, Get Audit Record	Every query on a VDB: who ran it, on which VDB, the SQL, the source (BI tool, notebook or AI client), the status, the duration, and the user's question when it came from an AI client.
System Audit	Get Activity Log	Workspace-level actions: who created, changed or deleted a policy, a VDB, a datasource, a user or a connection, and when.

Example: a compliance officer asks \"who looked at customer data last month, and who gave them access?\"

Data Access Audit shows each query on the customer VDB: the user, the time and whether it succeeded or was blocked.
System Audit shows who added that user to the VDB, and when.

\n","_postman_id":"e0ec78de-9933-44b6-b553-d3f577c4100b","auth":{"type":"bearer","bearer":{"basicConfig":[{"key":"token","value":"{{token}}"}]},"isInherited":true,"source":{"_postman_id":"230ce1f4-4c29-4006-87b5-45620ae91c61","id":"230ce1f4-4c29-4006-87b5-45620ae91c61","name":"PVML Documentation","type":"collection"}}}],"auth":{"type":"bearer","bearer":{"basicConfig":[{"key":"token","value":"{{token}}"}]}},"event":[{"listen":"prerequest","script":{"exec":[""],"id":"6ada1329-8184-4ed6-a92d-2d25ec417c25","type":"text/javascript"}},{"listen":"test","script":{"exec":[""],"id":"f8ab2d54-11e4-43ef-8b16-a4c77b732c15","type":"text/javascript"}}],"variable":[{"key":"baseUrl","value":"https://platform.pvml.com"},{"key":"json_web_token_105i","secret":true}]}