Using the API

General Validation API v1 coordinates validation through the hosted metadata control plane. Customer-owned integrations call /api/v1 on the API origin. Validation compute and customer data remain in your Azure environment. The API supports the same resource lifecycle as the application:

Connect a Discovery Source and import its catalog.
Prepare Datasets and inspect their readiness and schema.
Pair a source and target Dataset.
Read the fixed validation functions and author Tests.
Submit Runs, follow their items, and review result metadata.

Start with API authentication and the endpoint reference. A machine caller needs an API application role and an activated Organization in its Entra directory. The hosted browser app uses a separate registration and delegated bearer tokens.

Resources and capabilities

Resource family	What it covers
Organization	Organization settings, membership, and invitations. Activation and invitation acceptance require a signed-in person.
Execution Environment	Customer Azure environment configuration, provisioning operations, and readiness.
Billing	Entitlement state, available plans, and hosted checkout or billing-portal redirects.
Discovery	Sources, ADF and Fabric metadata, catalog import, and access preparation.
Datasets	Imported metadata, schema fields, readiness, and supported preparation actions.
Dataset Pairs	Source and target boundaries, filters, join keys, and Pair-specific authoring capabilities.
Validation Functions and Tests	Fixed function definitions and Test creation, replacement, inspection, and deactivation.
Runs	Submission at all-Test, Pair, or Test scope; status, items, cancellation, retries, and result metadata.
Support	Owner-controlled, time-bounded grants for metadata support access.

GET /api/v1/installation/capabilities reports the API version, effective caller role, limits, and published runtime contract versions. The historical installation path remains the capabilities endpoint for the hosted service. Environment readiness is separate: an advertised runtime version does not prove your execution environment has finished its required upgrade. Each operation declares its authorization and side effects. Workloads use cumulative GV.APIReader, GV.APIContributor, or GV.APIOwner roles. Human users use their Organization membership role. Organization activation and invitation acceptance require delegated GV.Access; application tokens cannot perform those two actions.

Handle requests and responses

Use each operation’s declared method, path, request schema, and headers:

Idempotency: send Idempotency-Key when required. Reuse it only for an identical retry of the same logical action, including after a lost response.
Concurrent edits: retain the exact strong ETag and send it as If-Match when required. A 412 means reread and review the current resource before submitting another change.
Pagination: pass nextCursor unchanged and retain the same parent, search, filters, sort, and direction. Cursors do not grant access.
Asynchronous work: retain the accepted operation or Run identity, follow its Location, and respect Retry-After. Submission is not completion.
Failures: parse application/problem+json. Use its stable code, type, safe diagnostic fields, and requestId for remediation or support. See the error reference.

A successful HTTP response does not mean a validation passed. When a Run reaches a terminal state, inspect overallStatus. Treat fail, error, and no_results as unsuccessful validation outcomes in a pipeline gate. Use Runs and results for the lifecycle and validation in a pipeline for orchestration.

What result responses contain

The API returns verdicts, counts, reason codes, hashes, configuration metadata, and validated references to customer artifacts. Exact source and target values, deltas, credentials, and row evidence are not transported through vendor APIs. A pointer to an artifact is not permission to read it. The browser can retrieve permitted previews directly from customer storage using the person’s delegated identity and customer RBAC. Workload API roles do not provide that storage access. /callbacks/v1 is the authenticated customer execution delivery protocol, configured with the execution environment; it is not a general integration route for uploading customer data.

Retrieve the deployed contract

This public reference covers request schemas and examples, response status codes, and headers. The authenticated OpenAPI document supplies the exact response body schemas and examples for the current service:

curl --fail-with-body \
  --header "Authorization: Bearer ${gv_access_token}" \
  "${gv_api_origin}/openapi.json" \
  --output general-validation-openapi.json

Use the API origin and a token with at least Reader access. Opening the URL in a browser tab alone does not attach a bearer token. The API’s Swagger UI at /docs and its documentation routes are also authenticated. /openapi-agent.json is a generated projection for tool clients. It simplifies some request unions and includes guidance in operation descriptions; the canonical /openapi.json remains authoritative for schema validation. See Connect a Microsoft Foundry agent. Repository snapshots use placeholder origins and application IDs. The deployed document publishes the configured authority; use those real values for your integration. Review contract changes before regenerating typed clients. General Validation manages hosted releases, while your customer execution environment has its own readiness and upgrade lifecycle.

Service capabilities

Discovery

Datasets

Dataset Pairs

Validation Functions

Validation Tests

Runs

Organization

Execution Environment

Billing

Support

Using the API

Resources and capabilities

Handle requests and responses

What result responses contain

Retrieve the deployed contract

​Resources and capabilities

​Handle requests and responses

​What result responses contain

​Retrieve the deployed contract

Resources and capabilities

Handle requests and responses

What result responses contain

Retrieve the deployed contract