Provider discovery

client.provider_specs serves Alter’s provider API catalog: every supported provider’s operations with parameter, request, and response schemas, refreshed daily. Available on App and Agent clients.

List providers with a cataloged spec

import asyncio

from alter_sdk import App

async def main() -> None:
    async with App(api_key="...") as app:
        specs = await app.provider_specs.list()      # every cataloged provider
        oauth_only = await app.provider_specs.list(kind="oauth")

        for spec in specs:
            print(spec.provider_kind, spec.provider_id, spec.operation_count, spec.changed_at, spec.fetched_at)

asyncio.run(main())

Each ProviderSpec carries provider_kind ("oauth" | "managed"), provider_id, version, provenance, operation_count, changed_at (when the current content version landed), fetched_at (last refresh attempt), and title.

List a provider’s operations

page = await app.provider_specs.list_operations("oauth", "provider-id", search="items", limit=50)
for op in page.items:
    print(op.method, op.path_template, "-", op.summary)

if page.has_more:
    more = await app.provider_specs.list_operations(
        "oauth", "provider-id", search="items", limit=50, offset=page.offset + page.limit
    )

page.spec carries the serving spec’s metadata, so the consumer always sees how fresh the catalog is.

Fetch one operation’s full schema

op = await app.provider_specs.get_operation("oauth", "provider-id", "items/create")

print(op.method, op.path_template)
print(op.params_schema)     # parameter definitions (name / in / required / type)
print(op.request_schema)    # request-body shape
print(op.response_schema)   # response shape

Spec metadata for one provider

spec = await app.provider_specs.get("managed", "provider-id")
print(spec.version, spec.provenance, spec.changed_at, spec.fetched_at)

Errors

Condition	Raised
Unknown provider / no cataloged spec	GrantNotFoundError
Unknown operation id	GrantNotFoundError
kind not "oauth" / "managed"; empty provider id; provider id containing ?, #, or a control character	AlterValueError (raised locally, before any network call)
Empty or over-200-character search; limit outside 1–500; negative offset	AlterValueError (raised locally, before any network call)
Empty or over-512-character operation id, or one containing a control character	AlterValueError (raised locally, before any network call)

Some provider names exist in both families; the kind argument disambiguates. Operation ids are opaque query values, so reserved characters such as /, ?, and # are supported. Discovery data is public provider documentation; retrieving it never touches credentials and never widens what a grant may execute.