# DiscoveryTo

> DiscoveryTo converts Google API Discovery documents into OpenAPI 3.1 documents for use by agents, API clients, documentation tools, code generators, and other OpenAPI-compatible software.

## Purpose

Google publishes machine-readable Discovery documents that describe its APIs, resources,
methods, parameters, and schemas. Many developer and agent tools expect OpenAPI instead.
DiscoveryTo bridges those formats: provide the HTTPS URL of a Google-hosted Discovery
document and receive the equivalent OpenAPI 3.1 document as JSON.

Use DiscoveryTo when an agent needs to:

- make a Google API Discovery document usable by an OpenAPI-based tool;
- inspect a Google API through a standard OpenAPI schema;
- generate API clients, documentation, integrations, or tool definitions from that schema;
- download or copy a converted OpenAPI document without manually translating formats.

DiscoveryTo describes and converts APIs. It does not call the Google API represented by a
Discovery document, grant access to Google data, or replace the credentials required by
that API.

## Web converter

Open [DiscoveryTo](/), enter a Discovery document URL, and select **Convert to OpenAPI**.
The input must be an HTTPS URL hosted on `googleapis.com`, such as:

`https://www.googleapis.com/discovery/v1/apis/drive/v3/rest`

The result is an OpenAPI 3.1 JSON document that can be copied or downloaded. Discovery
documents may not exceed 10 MB.

Guest conversions use a cached result when one is available. Authenticated users may
choose whether to use the cache or fetch the latest document from Google.

## API access

Agents that need programmatic conversion should read the [OpenAPI document](/openapi.json)
before making requests. It is the authoritative, machine-readable contract for current
paths, methods, request bodies, response schemas, authentication, and errors.

The conversion API accepts a Google Discovery document URL and returns the generated
OpenAPI 3.1 document. API authentication uses a bearer token created in the web interface
under **Settings → Credentials**:

`Authorization: Bearer <token>`

Tokens can be restricted by endpoint ability and expiration. Keep tokens private and do
not commit them to source control.

For API conventions, authentication details, envelopes, and errors, read the
[API guide](/api/readme).

## Agent guidance

1. Use the web converter for a single interactive conversion.
2. Use [/openapi.json](/openapi.json) to discover the current programmatic interface.
3. Supply only a Google-hosted HTTPS Discovery document URL; do not submit raw Discovery
   JSON or unrelated URLs.
4. Treat the converted document as a generated representation and validate important
   operations against the source Google API documentation before production use.
5. Never expose a DiscoveryTo bearer token or credentials required by the target Google
   API.

## Key resources

- [Web converter](/): Convert a Google Discovery document interactively.
- [OpenAPI document](/openapi.json): Machine-readable contract for the DiscoveryTo API.
- [API guide](/api/readme): Authentication and API behavior in prose.
- [Contact](/contact): Account support, consulting, and automation questions.