Provider discovery

client.providerSpecs 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 { App } from "@alter-ai/alter-sdk";

const app = new App({ apiKey: "..." });
try {
  const specs = await app.providerSpecs.list();        // every cataloged provider
  const oauthOnly = await app.providerSpecs.list("oauth");

  for (const spec of specs) {
    console.log(spec.providerKind, spec.providerId, spec.operationCount, spec.fetchedAt);
  }
} finally {
  await app.close();
}

Each ProviderSpec carries providerKind (string; current values are "oauth" and "managed"), providerId, version, provenance, nullable sourceUrl, contentHash, operationCount, changedAt (a Date for when the current content version landed), fetchedAt (a Date for the last refresh attempt), nullable title, and nullable specVersion.

List a provider’s operations

const page = await app.providerSpecs.listOperations("oauth", "provider-id", {
  search: "items",
  limit: 50,
});
for (const op of page.items) {
  console.log(op.method, op.pathTemplate, "-", op.summary);
}

if (page.hasMore) {
  const more = await app.providerSpecs.listOperations("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

const op = await app.providerSpecs.getOperation("oauth", "provider-id", "items/create");

console.log(op.method, op.pathTemplate);
console.log(op.paramsSchema);    // parameter definitions (name / in / required / type)
console.log(op.requestSchema);   // request-body shape
console.log(op.responseSchema);  // response shape

Spec metadata for one provider

const spec = await app.providerSpecs.get("managed", "provider-id");
console.log(spec.version, spec.provenance, spec.fetchedAt);

Errors

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

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