The Validio API is built using GraphQL and enables interaction with the Validio platform via any GraphQL client.

Base URL

The base URL is the URL you will use to access your Validio instance. The URL will usually take the following format: https://<my-company>.validio.io

Authentication

To authenticate your requests to the GraphQL API, you need to pass the Authorization header. The header value should be of format <access-key>:<access-secret>. Refer to Create API key on how to create credentials.

👍

You can use environment variables to avoid storing credentials on disk. The variables to set are VALIDIO_ENDPOINT, VALIDIO_ACCESS_KEY and VALIDIO_SECRET_ACCESS_KEY.

Namespaces

Namespaces organize and isolate resources into managed groups. Resources created in one namespace are only visible and accessible within that namespace, enabling teams to work independently without affecting each other's configurations.

Common use cases:

• Team separation: Give each team its own namespace to manage their sources and validators independently
• Environment isolation: Use separate namespaces for development, staging, and production
• IaC management: Assign a dedicated namespace to resources deployed via Infrastructure as Code to prevent conflicts with manually created resources

Specifying a Namespace

When using the CLI or SDK, you can target a specific namespace in two ways:

1. Per-request: Pass the -n or --namespace flag with CLI commands, or include the namespace in your API request
2. Default namespace: Configure a default using validio config ns <namespace> (CLI) or set default_namespace in your ValidioConfig (SDK)

Managing Namespaces via CLI

Create a namespace and assign members or API keys with roles:

# Create a namespace and add a member as Admin
validio namespaces create my-namespace [--role ADMIN --member <user-uuid>]

# Add an API key to an existing namespace as Viewer
validio namespaces update my-namespace [--role VIEWER --api-key <key-id>]

📘

The API key that is used when creating the namespace will be added as ADMIN by default.

For information on creating and managing namespaces in the UI, see Managing Namespaces.

Pagination and Filtering

Some API endpoints support input types that are used for pagination and filtering. They can be used to even further control what response you'll get from the API. Not all queries support this, but you can see in the API specification which do. For more information, see the Validio GraphQL API Reference.

The filters work exactly like any other input type and can be specified as variable values. What values are expected can be found by referencing the API specification.

Pagination works in such a way that every query supporting this returns a PageInfo type. The start and end cursor are identifiers to where the returned dataset starts or ends. As long as the hasNextPage is true there is more data to fetch. The next page can be fetched by passing a PaginationInput where the after value is set to the endCursor from the last response.

📘

The pagination input type also has a field for limit which controls how many results each pages should contain. You can find an example on how to use pagination to iterate over multiple pages until all data is fetched in the Validio SDK Recipes.

Query Examples

By inspecting the GraphQL schema you can find the data you're interested in and how to get, create or update it. You can find common queries and how to use them in our Validio SDK Recipes.

API Rate Limits

The default Validio API rate limit is 200 requests per second.

API Integration Patterns

The Validio API supports comprehensive CRUD operations across all major entities — Sources, Validators, Incidents, Catalog Assets, Channels, and Notification Rules — making it possible to programmatically synchronize data quality information across your entire stack.

Successful implementations leverage standard patterns, such as:

• Push-based workflows - Validio sends data quality information to external systems in real-time (via webhooks) or on scheduled intervals (via APIs)
• Pull-based workflows - External systems query the Validio API to retrieve data quality information on-demand

The Validio API enables bidirectional integrations with external systems such as the following data catalogs, notifications systems, ticket management platforms, and CI/CD tooling: