- The GraphQL API is built using GraphQL and enables interaction with the Validio platform through any GraphQL client. It exposes the same functionality as the Validio UI, so you can read, create, update, and delete resources programmatically.
- The CSV Export API is a set of read-only REST endpoints that return Validio data as CSV, for reporting, archival, and ingestion into BI tools or data warehouses.
GraphQL API reference
Every query, mutation, and type in the GraphQL API.
GraphQL basics
If you’re unfamiliar with GraphQL, start with the basics.
CSV Export API
Export sources, validators, incidents, and more as CSV.
Which API to use
Use the GraphQL API by default. It covers the whole platform, and it’s the only option for changes, such as creating a source, updating a validator’s threshold, or muting an incident. Use the CSV Export API when you want rows rather than objects: to feed a BI tool, to archive incident or activity history beyond your retention window, or to hand data to someone who works in spreadsheets. The same endpoints back the Export buttons in the Validio UI.Endpoints
Both APIs are served from your Validio instance. The base URL, writtenhttps://your-validio-instance on these pages, is the URL you use to access Validio. An installation that Validio hosts is on a validio.io address, while a VPC installation uses your own domain.
When you configure the Validio SDK or CLI, you give the base URL, and the client adds the
/api path.
Authentication
Both APIs use the sameAuthorization header, with the value <access-key>:<access-secret>. For how to create an API key, and how the CLI and SDK find credentials, see Authentication.
Working with the GraphQL API
These pages cover the concepts that apply to GraphQL API requests:- GraphQL basics: The GraphQL concepts to know before you start.
- Namespaces: Target the namespace your resources live in.
- API integration patterns: Synchronize data quality information with the rest of your stack.
- Pagination and rate limits: Page through large result sets, and stay within the request budget.
- API errors: The stable error codes to branch on.
Resource names and safe retries
We recommend that you always setresourceName when you create a resource through the API. A resource name identifies a resource without its generated ID, and it is unique within a namespace for sources, credentials, windows, segmentations, filters, and validators.
If you leave resourceName out, Validio generates one from the display name with a random suffix, such as orders_table_x7k2p. A create request that is retried, for example after a timeout, then creates a second copy of the resource. With an explicit resourceName, the retried request fails because the name already exists in the namespace, and you can look up the existing resource by its resource name instead, with a query such as sourceByResourceName or validatorByResourceName.
Query examples
By inspecting the GraphQL schema, you can find the data you’re interested in and how to get, create, or update it. For how the schema is organized, see the Validio GraphQL API reference. For common operations and how to use them, see the SDK recipes.Templated debug queries
ThevalidatorMetricDebugInfo query returns the SQL that reproduces an incident. Set templated: true on its input to receive that SQL with {{ validio_... }} placeholders in place of the incident’s literal values, so one query can be re-bound to other incidents. The default is false.
A templated query is expanded automatically when it is executed, so it can be passed straight to validatorMetricDebugRecords without being resolved first. For the placeholders themselves, see Debug query syntax.