Provider API discovery

Alter natively catalogs a structured API surface for every supported provider: operation IDs, methods, paths, and the parameter, request, and response schemas available from that provider’s source. Coverage depends on provenance. A published machine-readable spec can supply a broad surface; a reviewed fragment contains the operations Alter has explicitly cataloged. An agent can ask, mid-run, “what Gmail operations are cataloged?” and get a structured answer through the same SDK it calls Gmail with — no context-stuffed API docs or guessed paths.

Where the catalog comes from

Provider specs come from a published machine-readable API description (OpenAPI or an equivalent format) where one is available, or from a reviewed code fragment otherwise. URL-backed sources refresh on a daily default cadence; fragments change with reviewed Alter releases. Every served response carries the catalog’s content-change time (changed_at / changedAt), last ingestion time (fetched_at / fetchedAt), and provenance:

• provider — fetched from the provider’s own published spec. The normal case.
• fragment — a hand-maintained catalog for providers that publish no machine-readable spec. Reviewed and versioned like code.
• directory — sourced from a third-party spec directory. Treated as lower-trust: descriptive prose is withheld until reviewed; paths, methods, and schemas still serve.

After a provider has a successfully ingested version, an outage or malformed upstream document does not replace it: Alter keeps serving the last known-good version and flags staleness internally. A spec update that would remove a large share of a provider’s operations is quarantined rather than served — sudden catalog collapse is treated as an upstream error, not a change.

How to consume it

• SDK — client.provider_specs (Python) / client.providerSpecs (TypeScript): list a provider’s operations, search them, and fetch one operation’s full parameter/request/response schemas. See the SDK references: Python, TypeScript.
• CLI — alter providers operations list <provider>, alter providers operations get <provider> <operation-id>, and alter providers spec status <provider> for freshness/provenance. See the CLI reference.
• Dashboard — every provider’s detail page shows its cataloged operations with the spec’s version, freshness, and provenance.
• MCP — the Alter Docs MCP server exposes list_providers, list_operations, and get_operation_schema tools, so an agent connected to it can browse provider surfaces during development.

Dual-family provider names

A few provider names exist both as an OAuth provider and as a managed-secret provider (for example github and stripe). Provider-specific discovery calls always take a kind (oauth or managed), so their signatures stay consistent whether or not a name currently appears in both families. Only the top-level catalog list can omit kind; doing so returns both families.

Discovery is not authorization

The catalog describes what a provider’s API can do — it never widens what a given grant may do. Executing an operation still goes through the grant’s scopes and every applicable policy. Discovery data is public provider documentation; it contains no tenant data and no credentials.