> For the complete documentation index, see [llms.txt](/llms.txt)

# Glotto documentation

Everything you need to turn an API spec into SDKs, docs, and an MCP server. [Get started](/docs/getting-started) with your first `glotto generate`.

## Every SDK, same error model

This page renders emitted samples for every supported language. They are reproduced in full — emitted bytes, not hand-written prose — on [errors](/docs/errors/).

## Get started

- [Getting started](/docs/getting-started/): Turn one API spec into SDKs, docs, and an MCP server with Glotto.

## Concepts

- [The Glotto IR](/docs/glotto-ir/): GlottoIR is the intermediate representation every codegen target consumes — the single contract between spec ingest and the language engines.
- [The pipeline](/docs/pipeline/): How glotto generate composes spec ingest, normalization, IR build, codegen, and release into one deterministic flow.
- [Drift detection](/docs/drift-detection/): Generated code is committed to Git, and Glotto fails a PR when the committed output no longer matches what the generator produces.
- [Breaking-change detection](/docs/breaking-changes/): Every pull request that changes your spec is classified against the last build — which changes break a caller who upgrades, and which do not.
- [Idempotency keys](/docs/idempotency-key/): Glotto treats the Idempotency-Key as a first-class config concept — auto-injected on mutations whose spec advertises it, so retries are safe.
- [The verification report](/docs/verification-report/): Every regeneration produces a deterministic report: pinned inputs, per-target drift, compile and contract statuses, delivered to CI and the release PR.
- [Endpoint migration](/docs/endpoint-migration/): Rename or re-version an endpoint without breaking your SDK — aliases keep the old method working against the new operation, and deprecated marks it.

## Guides

- [The MCP server](/docs/mcp-server/): Glotto generates a multi-mode Model Context Protocol server — Tools Mode, Code Mode, and Dynamic Mode — that your API's consumers point their AI clients at.
- [The generated docs site](/docs/generated-docs-site/): Glotto emits an Astro docs site your customers own — reference pages, multi-language snippets, search, and theming — from the same IR as the SDKs.
- [Deployment & single-tenant](/docs/deployment/): Run Glotto as the shared SaaS, or as a dedicated single-tenant cell in your own region/VNet running the same control-plane code.
- [Multi-VCS release flow](/docs/multi-vcs-release/): Glotto opens regenerate-and-release PRs across GitHub, GitLab, and Bitbucket through one provider-agnostic VCS abstraction.
- [Custom code](/docs/custom-code/): Add your own code to a generated SDK and keep it across regenerations — customer-owned extensions and patch preservation.
- [Migrate from Stainless](/docs/migrate-from-stainless/): Convert a stainless.yml to glotto.yml with one command, review the migration report, and move your SDKs, docs, and MCP server across — custom code kept.
- [How Glotto compares](/docs/sdk-generation-comparison/): Two questions decide an SDK generator: is the output idiomatic, and how do you keep every language in parity? How Glotto compares to the alternatives.
- [Connect a VCS provider](/docs/vcs-connect/): Connect GitHub, GitLab, or Bitbucket once, and Glotto tags your downstream repo to publish Go, Swift, and PHP SDKs and open release PRs for you.
- [The generated CLI](/docs/generated-cli/): A ready-to-run command-line client for your API: one command per operation, with spec-derived flags, auth, environments, uploads, and retries.
- [Migrate from Fern](/docs/migrate-from-fern/): Convert a Fern project — generators.yml and docs.yml — to glotto.yml with one command, pin your SDK's member names, and keep every inbound docs link working.
- [The API-surface graph](/docs/graph/): A machine-readable graph of your API surface: operations, models, auth schemes, events and the typed edges between them, in one deterministic graph.json.
- [The generated Terraform provider](/docs/terraform/): A publishable terraform-plugin-framework provider for your API — resources, data sources, Registry docs and acceptance tests, all derived from your spec.
- [The published spec repo](/docs/spec-repo/): Your API specification kept in a git repo you own — base, post-transform and code-sample-decorated — provably current on every build, on any of four forges.

## Using the SDKs

- [Authentication](/docs/authentication/): Bearer tokens, API keys, OAuth2 client credentials, and basic auth: how every generated SDK takes credentials, with env-var fallback and typed scopes.
- [Retries & timeouts](/docs/retries/): Automatic retries with backoff, and how to tune them.
- [Pagination](/docs/pagination/): Iterate results automatically or fetch one typed page at a time.
- [Errors](/docs/errors/): A failed request throws a typed ApiError carrying the status, method, path, parsed body, headers, and request id, plus per-status-family subclasses.
- [Idempotency](/docs/idempotency/): Glotto auto-injects a fresh Idempotency-Key UUID on writes, so a retried call can't create two resources — per operation, or for every mutation.
- [Streaming](/docs/streaming/): Consume server-sent events and streamed responses.
- [Webhooks](/docs/webhooks/): Verifying inbound webhook signatures with the helpers your SDKs emit when the spec declares webhooks.
- [Polling](/docs/polling/): Waiting for an async operation to finish with the generated poll helpers.
- [Telemetry hooks](/docs/telemetry/): Observe every request with the client's log / metric / trace callbacks.
- [Agent primitives](/docs/agent-primitives/): Token counting, context budgeting, vector math, structured decode and budget-aware retry — emitted with your SDK.
- [Forward compatibility](/docs/forward-compatibility/): A server-added enum value or response field reaches an SDK generated months earlier — without crashing, and without losing data.
- [File uploads & downloads](/docs/file-transfers/): Send files and consume binary responses without losing bytes or metadata.

## Languages

- [React Native](/docs/react-native/): A Hermes-safe, Metro-friendly React Native SDK, not a re-skin of the web client: secure token storage, NetInfo-aware retries, background-aware streams.
- [TypeScript](/docs/typescript/): Glotto's reference target: an ESM-first, tree-shakable TypeScript client with typed error classes, async-iterator pagination, and SSE streaming.
- [Python](/docs/python/): An httpx-based Python SDK with typed dataclasses or pydantic v2 models and both async and sync clients — iterator pagination, SSE streaming, and typed errors.
- [Go](/docs/go/): An idiomatic Go module: context.Context-first methods, pull pagination, typed errors for errors.As, and unknown response fields kept on decode.
- [Java](/docs/java/): A buildable Java library with Gson models, resource sub-clients, CompletableFuture async twins, and unchecked ApiError exceptions — nothing to wrap.
- [Kotlin](/docs/kotlin/): A coroutine-first Kotlin client: suspend functions, Flow streaming and pagination, sealed-type errors, plus Android-native and Multiplatform targets.
- [C#](/docs/csharp/): An idiomatic .NET client that takes the HttpClient you supply, with resource accessors, a CancellationToken on every method, and await foreach paging.
- [PHP](/docs/php/): A Composer-installable PHP SDK with strict_types, resource objects, and a swappable PSR-18 transport — typed ApiError exceptions and lazy paging.
- [Ruby](/docs/ruby/): An idiomatic Ruby gem with snake_case resource objects, immutable Data.define models, persistent connections, and rescuable typed error classes.
- [Rust](/docs/rust/): An idiomatic Rust crate built on serde types: Result-returning operations with an ApiErrorKind enum to match on, cursor pagination, and SSE streaming.
- [Swift](/docs/swift/): An idiomatic Swift package of Codable types with throwing operations and an APIErrorKind enum, plus Keychain storage and connectivity-aware retries.
- [Dart](/docs/dart/): An idiomatic Dart package with fromJson/toJson models, Stream-based pagination and SSE, plus async token storage and connectivity-aware retries for Flutter.
- [Elixir](/docs/elixir/): A functional Elixir Hex package built on Req: struct models, lazy Stream pagination and SSE, and ApiError structs whose kind is a documented atom.

## Reference

- [CLI reference](/docs/cli/): Every command in the published glotto CLI — init, schema, workspace, generate, mcp, verify-attestation, login, logout — with flags and exit codes.
- [glotto.yml reference](/docs/glotto-yml/): The complete glotto.yml configuration reference — every key, its shape, and accepted values.
- [glotto.yml client behavior](/docs/glotto-yml-client-behavior/): Configure generated client runtime behavior, transforms, naming, casing, and parameters.
- [glotto.yml model shaping](/docs/glotto-yml-model-shaping/): Shape generated models, enum types, required inputs, and auto-populated values.
- [glotto.yml API surface](/docs/glotto-yml-api-surface/): Control which operations Glotto emits, aliases, streaming behavior, and query serialization.
- [glotto.yml project settings](/docs/glotto-yml-project-settings/): Configure diagnostics, code owners, MCP, generated docs, licensing, releases, and hosted binding.
- [Diagnostics reference](/docs/diagnostics/): The SDK-readiness lint rules and the entry point for every GLOTTO_ diagnostic, with severities and resolution guidance.
- [Diagnostics configuration](/docs/diagnostics-config/): Tune SDK-readiness rules and resolve every glotto.yml validation diagnostic.
- [Migration diagnostics](/docs/diagnostics-migrations/): Every diagnostic emitted while migrating from Stainless or Fern, with the required follow-up.
- [Fatal diagnostics](/docs/diagnostics-fatal/): Fatal configuration, workspace, spec-ingestion, source-retrieval, and transform diagnostics.
- [SDK generation diagnostics](/docs/diagnostics-sdk-generation/): Fatal SDK-generation diagnostics, including reserved and colliding model names across every target.
- [Runtime diagnostics](/docs/diagnostics-runtime/): Diagnostics raised by generated SDKs at application runtime.
- [Transforms reference](/docs/transforms/): The glotto.yml transforms that rewrite your OpenAPI spec for cleaner SDKs, with arguments and examples.