Discovering operations

Docs inside the package

The SDK ships a generated markdown reference so a coding agent (or you) can find the right operation by reading files in node_modules — no network, no extra tooling:

• docs/catalog.md — one grep-friendly line per operation, grouped by domain.
• docs/README.md — how to find and call an operation.
• docs/operations/<domain>/<operationId>.md — variables, a call example, gateway notes (idempotency, result caps, org guards), and the exact response shape.
• Field-level types are TypeScript — grep the type name from the operation page in dist/generated/operationTypes.d.ts.

Live discovery endpoints

The API also documents itself at runtime, which covers the two things static docs cannot — your key’s actual authorization, and operations newer than your installed SDK:

• GET /api/v1/operations — the catalog as JSON, with a per-key authorized flag on every operation.
• GET /api/v1/operations/:operationId — full detail for one operation, including operations added after your SDK release. Input-object variables are expanded to their nested fields, so a mutation’s variable shape is spelled out rather than left as an opaque type name.
• GET /api/v1/help — the whole API as one markdown document (no key required).

Organization feature gates also affect authenticated discovery: unavailable operations are omitted from the list and return 404 unknown_operation by id. The public SDK and help catalog deliberately exclude unlisted operations.

Untyped escape hatch

Operations added to the API after your SDK version still work — untyped:

await goliath.execute('someBrandNewOperation', { id: '...' })

execute() treats the operation as a mutation for retry safety because it does not know the operation’s type. Prefer typed methods when available; do not pass an idempotency key to a read operation.

Versioning

The SDK’s typed surface is generated from the same operation catalog the API executes, and the package version follows semver for that surface. Added operations, optional inputs, and response fields are additive changes; removed operations or incompatible input/output changes are breaking changes. If a method you expect is missing, your installed release predates the operation: use execute() now, and pick up the types with the next SDK upgrade.