> For the complete documentation index, see [llms.txt](https://docs.veza.com/4yItIzMvkpAvMVFAamTf/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.veza.com/4yItIzMvkpAvMVFAamTf/developers/api/query-builder.md).

# Query APIs

Creating new queries, interacting with saved queries, and running query specs

The Query Builder APIs enable programmatic creation, execution, and management of assessment queries, using the Veza the [Query Builder](https://docs.veza.com/4yItIzMvkpAvMVFAamTf/features/search/query-builder.md). You can use these operations to develop your own tools and integrate Veza search with external services and automation.

Queries created with these endpoints can define risks and have rules and alerts associated with them. Even if you and your team create and manage queries primarily from the user interface, this documentation may still be of interest for learning how queries are constructed and handled within Veza.

You can use these methods to:

* [List saved queries](https://docs.veza.com/4yItIzMvkpAvMVFAamTf/developers/api/query-builder/listassessmentqueries.md)
* [Save a query](https://docs.veza.com/4yItIzMvkpAvMVFAamTf/developers/api/query-builder/createassessmentquery.md)
* [Get a saved query](https://docs.veza.com/4yItIzMvkpAvMVFAamTf/developers/api/query-builder/getassessmentquery.md)
* [Update a query](https://docs.veza.com/4yItIzMvkpAvMVFAamTf/developers/api/query-builder/updateassessmentquery.md)
* [Update query owners](https://docs.veza.com/4yItIzMvkpAvMVFAamTf/developers/api/query-builder/updateassessmentquerypermissions.md)
* [Reset a query](https://docs.veza.com/4yItIzMvkpAvMVFAamTf/developers/api/query-builder/resetassessmentquery.md)
* [Delete a query](https://docs.veza.com/4yItIzMvkpAvMVFAamTf/developers/api/query-builder/deleteassessmentquery.md)
* [Get query destination nodes](https://docs.veza.com/4yItIzMvkpAvMVFAamTf/developers/api/query-builder/getassessmentquerydestinationnodes.md)
* [Get query nodes](https://docs.veza.com/4yItIzMvkpAvMVFAamTf/developers/api/query-builder/getassessmentquerynodes.md)
* [Get query result](https://docs.veza.com/4yItIzMvkpAvMVFAamTf/developers/api/query-builder/getassessmentqueryresult.md)
* [Get query spec destination nodes](https://docs.veza.com/4yItIzMvkpAvMVFAamTf/developers/api/query-builder/getassessmentqueryspecdestinationnodes.md)
* [Get query spec nodes](https://docs.veza.com/4yItIzMvkpAvMVFAamTf/developers/api/query-builder/getassessmentqueryspecnodes.md)
* [Get query spec results](https://docs.veza.com/4yItIzMvkpAvMVFAamTf/developers/api/query-builder/getassessmentqueryspecresult.md)
* [Create async query nodes](https://docs.veza.com/4yItIzMvkpAvMVFAamTf/developers/api/query-builder/createassessmentquerynodesasync.md)

For more information about query options, see [Query Builder Parameters](https://docs.veza.com/4yItIzMvkpAvMVFAamTf/developers/api/query-builder/parameters.md).

#### Base URL

These endpoints are available under `{{VezaURL}}/api/v1/`. You must use the appropriate prefix when calling the API, for example:

```bash
curl -x GET 'https://your-org.vezacloud.com/api/v1/assessments/queries'
```

#### Authentication

You can create and manage [API tokens](https://docs.veza.com/4yItIzMvkpAvMVFAamTf/developers/api/authentication.md) for your user account from **Administration** > *API Keys*. Each API call must include the API key in the request header, passed as a bearer authentication token.

#### Getting started

The [Usage Examples](https://docs.veza.com/4yItIzMvkpAvMVFAamTf/developers/api/query-builder/usage-examples.md) page consolidates some sample requests and responses.

An understanding of Veza's usage of [graph terminology](https://docs.veza.com/4yItIzMvkpAvMVFAamTf/developers/api/query-builder/terminology.md) can be helpful. To learn more about the query object and options, see [here](https://docs.veza.com/4yItIzMvkpAvMVFAamTf/developers/api/query-builder/parameters.md). For more information about how to interpret the query response body, see [Query Builder Results](https://docs.veza.com/4yItIzMvkpAvMVFAamTf/developers/api/query-builder/results.md). To make a saved query filterable by the dashboard **Accounts** filter, see [Add account variables to a saved query](https://docs.veza.com/4yItIzMvkpAvMVFAamTf/developers/api/query-builder/account-variables.md).

You can start working with pre-built and saved queries using the `/assessments/queries` endpoint. When you are ready to try running your own queries, see the [`/assessments/query_spec`](https://docs.veza.com/4yItIzMvkpAvMVFAamTf/developers/api/query-builder/getassessmentqueryspecresult.md) operations to run test queries without saving them.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.veza.com/4yItIzMvkpAvMVFAamTf/developers/api/query-builder.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
