> ## 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. # API and automation > Automate Organization administration, Table Pair and Test authoring, and Result reporting with the General Validation API while validations run from the app. 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](https://docs.generalvalidation.com/api/authentication.md). 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](https://docs.generalvalidation.com/api/authentication.md) 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](https://docs.generalvalidation.com/validate-data/runs-and-evidence.md); for recurring controls, see [Validate on an ongoing basis](https://docs.generalvalidation.com/validate-data/ongoing-validation.md). ## 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`](https://docs.generalvalidation.com/errors/idempotency.key_conflict). | | Concurrent edits | Operations that declare `If-Match` require the exact `ETag` you last read. A [`precondition.failed`](https://docs.generalvalidation.com/errors/precondition.failed) response means someone changed the resource first: read it again and review before retrying. A missing header returns [`precondition.required`](https://docs.generalvalidation.com/errors/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`](https://docs.generalvalidation.com/errors/rate.limited). A response with [`auth.identity_provider_unavailable`](https://docs.generalvalidation.com/errors/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](https://docs.generalvalidation.com/administration/errors.md) 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](mailto: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](https://docs.generalvalidation.com/administration/security.md). ## 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. ```bash theme={null} 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](https://docs.generalvalidation.com/api/reference.md). This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.