API and automation - General Validation

General Validation publishes a versioned API at https://api.generalvalidation.com for the metadata the app manages. Workloads call it with a Microsoft Entra application token and one of the API application roles described in API authentication. This page describes what the API covers in this release, the conventions every operation follows, and where the API stops.

What the API is for

Use the API for the parts of General Validation that are metadata:

Organization. Read and rename the Organization, list members and change or remove their access, and create, list, and revoke invitations. Activating an Organization and accepting an invitation require a signed-in person; a machine client cannot do either.
Billing. Read the Organization’s billing entitlement. Owners can also read the subscription and billing options and start checkout or the billing portal.
Table Pairs and Tests. Save Table references, create Table Pairs, update a Table Pair’s name, join keys, and filters, create and update Tests, read the fixed catalog of twelve Test functions, and archive a Table Pair. Archiving keeps the pair’s Run history and Results. The authoring API accepts no SQL; a Test is a function, column mapping, and settings.
Runs and Results. List Runs, read a Run’s status, and read each Test’s Result metadata: verdict, compared and mismatch counts, and reason code.

The API applies the same three roles as the app: Reader, Contributor, and Owner, granted through the application roles GV.APIReader, GV.APIContributor, and GV.APIOwner. The Organization must already be activated by a person in the same Microsoft Entra directory. The API resolves the Organization from the token’s verified directory; a caller cannot choose another Organization’s scope. See API authentication for the role table and how to set up a caller.

What runs from the app

Starting a Run and importing its Result happen in the app with the signed-in user’s Fabric access. When you click Run validation on a Table Pair, or Run all in the workspace header, your browser submits the Run to the Spark job in your dedicated workspace and records the Fabric job ID. Refresh Result polls the job and imports the summary from your Results Lakehouse. Setting up the Environment and browsing workspaces and Tables work the same way: those calls go from your browser directly to Microsoft. A Contributor token can prepare a Run, which freezes the Table Pair and its Tests, but the API cannot submit that Run to Fabric, poll it, or read its evidence. The API holds no Fabric or OneLake access, so it cannot perform those steps on your behalf. In this release the API does not execute validations unattended, schedule them, or send notifications. Automate authoring and reporting through the API, and run validations from the app. For the Run lifecycle, see Runs, Results, and evidence; for recurring controls, see Validate on an ongoing basis.

Conventions

Convention	What to do
Base URL	Every operation is under `https://api.generalvalidation.com/api/v1`.
Format	Requests and responses are JSON over HTTPS. Send `Authorization: Bearer` with your application token on every request.
Idempotency	Operations that declare `Idempotency-Key` require one. Reuse a key only for an identical retry of the same action, including after a lost response; a key reused for a different action returns `idempotency.key_conflict`.
Concurrent edits	Operations that declare `If-Match` require the exact `ETag` you last read. A `precondition.failed` response means someone changed the resource first: read it again and review before retrying. A missing header returns `precondition.required`.
Pagination	Collections that page return `nextCursor`. Pass it back unchanged as `cursor` with the same filters. Cursors are opaque.
Rate limits	A `429` response carries `Retry-After` and the code `rate.limited`. A response with `auth.identity_provider_unavailable` also carries `Retry-After`. Wait at least that long before retrying.
Problems	Failures return `application/problem+json` with a stable `code`, a `title`, a `detail`, and a `requestId`. Look the code up in Error codes and include the request ID when you contact support.

Never infer that an operation succeeded from a retry alone; read the resource back. A successful read of a Run is not a verdict: check the Run’s status and each Test’s Result, and treat failed and error as unsuccessful outcomes in a pipeline gate. Contact support@generalvalidation.com with the error code and the request ID or Run ID.

Data boundary

The API returns metadata only: Organization and membership records, Table references, Table Pair and Test definitions, Run status, and Result verdicts, counts, and reason codes. It never returns rows, exact values, or mismatch evidence, and it accepts no Fabric or OneLake tokens, rows, or SQL. Exact values and mismatched rows are read by your browser directly from OneLake with your own Microsoft identity when you open View details on a Run. An API application role grants no access to your Fabric tenant or storage, and a reference to a Run’s folder in a response is not permission to read it. Filter values you set through the API are saved with the Table Pair as configuration, so do not enter secrets or personal data as filter values. See Security and the data boundary.

Agents and tools

Tool clients can load a reduced schema at https://api.generalvalidation.com/openapi-agent.json. It is a projection of the same schema generated for tool use. The canonical schema at https://api.generalvalidation.com/openapi.json remains authoritative for validation and client generation. Both require a bearer token with at least the GV.APIReader role; opening the URL in a browser tab does not attach one.

curl --fail-with-body \
  --header "Authorization: Bearer ${gv_access_token}" \
  "https://api.generalvalidation.com/openapi-agent.json" \
  --output general-validation-openapi-agent.json

The published document carries the live service’s server and authentication metadata, so use the values it reports rather than placeholders. Review contract changes before regenerating a typed client. For each operation’s method, path, minimum role, and schemas, see the API reference.

​What the API is for

​What runs from the app

​Conventions

​Data boundary

​Agents and tools

What the API is for

What runs from the app

Conventions

Data boundary

Agents and tools