> ## Documentation Index
> Fetch the complete documentation index at: https://docs.generalvalidation.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Using the API

> Use the General Validation SaaS API for Organization administration, discovery, dataset preparation, validation authoring, and Runs.

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:

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

Start with [API authentication](/api-authentication) and the
[endpoint reference](/api/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](/errors).

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](/runs-results-and-evidence) for the lifecycle and
[validation in a pipeline](/validating-on-an-ongoing-basis) 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:

```bash theme={null}
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](/connect-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.