glotto.yml API surface

API surface

skip & only

skip:                    # exclude an operation from specific targets (by operationId)
  createWidget: [go, java]
only:                    # emit an operation ONLY for the listed targets
  internalPing: [typescript]

Per-operation target exclusion, keyed by operationId. An operationId may not appear in both.

skip and only are per target language. To withhold an endpoint from everything Glotto generates — including your docs site and your MCP server — use exclude instead.

exclude

exclude:                 # withhold an operation from EVERY generated artifact
  - createInternalAudit  # by operationId...
  - "post /internal/import"   # ...or by position (Stainless's spelling)

An entry addresses its operation either by operationId or by its position — "<method> <path>", the spelling Stainless’s unspecified_endpoints uses. The two are interchangeable: excluding an operation by position produces byte-identical output to excluding it by name. The verb is case-insensitive; the path is compared exactly, written as the template your spec declares (/pets/{petId}). Position is the only spelling available for an operation whose operationId your spec omits, since the name Glotto synthesizes for it appears nowhere you can read.

The target-agnostic deny-list. Where skip removes an operation from the SDKs you name, exclude removes it from every artifact in the run: all 13 SDKs, the Terraform provider, the CLI and graph targets, the docs site (its reference pages, sitemap, llms.txt, search index and the co-served openapi.json, across every documented version), and the generated MCP server — where the operation is registered as no tool and gets no handler.

Reach for exclude rather than listing every target in skip: an exclude entry stays correct when you add a target later, whereas an enumerated skip list silently re-exposes the endpoint the day a new target joins.

Notes:

• An operation named here is treated as if your spec never declared it, so an aliases entry pointing at it does not materialize — an alias can’t resurrect an excluded endpoint. To withhold an alias, remove its aliases entry.
• An operation may not be named by both exclude and only (contradictory) — and that holds however each side spells it, so exclude: ["post /pets"] alongside only: { createPet: … } is reported just as naming createPet on both sides is. Appearing in both exclude and skip is fine — exclude simply subsumes the narrower entry.
• An entry naming an operationId your spec doesn’t carry is ignored, so a config can outlive a spec change.
• exclude is a deny-list, not an allow-list: operations you don’t name keep shipping. A new endpoint added to your spec is published until you exclude it.

Migrating from Stainless? This is the counterpart to unspecified_endpoints.

client_methods

client_methods:
  - getStatus        # client.getStatus() instead of client.system.getStatus()
  - ping

A list of operationIds to hoist onto the client root so they hang directly off the client (e.g. client.getStatus()), rather than under a resource. Handy for health/status endpoints that don’t belong to a resource. Absent → no client-level methods.

aliases & deprecated

aliases:
  createRecord: upsertRecord        # keep the old method, routed to the new operation
  createExport:                     # …and when the PATH moved too, say where it used to be
    target: createExportV2
    path: /v1/exports

deprecated:
  createRecord:                     # a plain string works too: `createRecord: Use upsertRecord.`
    default: Use upsertRecord instead.
    python: Use upsert_record() instead.

aliases maps a method name you want to keep exposing → the operationId it should resolve to, so renaming or re-versioning an endpoint doesn’t break your users’ call sites — and Breaking-change detection stops reporting the rename as breaking. A plain string is enough when the rename leaves the path alone. When the path moves — and with it the resource Glotto derives from it — use the { target, path } form, where path is where the superseded method was served; it places the method on the surface your users already call, and never changes what it requests. Both of its fields are required.

deprecated maps an operationId → the migration message, rendered in each language’s own construct (@deprecated, @Deprecated, [Obsolete], #[deprecated], // Deprecated:, …). The object form’s default is required; the other keys are per-target overrides. Both absent → unchanged output.

See Endpoint migration for the full workflow.

streaming

streaming:
  on_event:
    - { data: "[DONE]", action: done }      # terminate the stream on this sentinel
    - { event_type: error, action: fatal_error }
    - { fallthrough: true, action: skip }   # drop anything else unrecognized, keep going

Termination / error / tolerance handlers for SSE & NDJSON stream iterators. Each rule has exactly one matcher — data (the event payload equals this sentinel), event_type (the SSE event: name; null matches untyped events), or fallthrough: true (catch-all) — and an action: break (stop), done (clean end), fatal_error (raise), or skip (drop the matched event and continue).

skip is the opt-in counterpart to the strict-by-default decode: because rules match the raw payload before any JSON parse, a skip-matched frame is dropped before it would be decoded, so a fallthrough: skip (or a targeted data: skip) lets you tolerate benign non-JSON noise — keepalive / control frames, vendor sentinels — without the stream surfacing a parse error. With no skip rule, an unrecognized non-JSON frame still surfaces the parse error (the strict default is unchanged).

streaming:
  dual_mode:
    createChatCompletion:                      # operationId
      param_discriminator: stream              # required — the request field selecting the mode
      stream_event_model: ChatCompletionChunk  # optional — the per-event model
      params_type_name: ChatCompletionParams   # optional — names the shared params model
      method_suffix: streaming                 # optional — default "streaming"

dual_mode handles the one endpoint, two modes shape every major AI API uses: a request field selects between a streamed sequence and a single buffered body, and the two return different types. Glotto emits two methods from the one operation — createChatCompletion (buffered) and createChatCompletionStreaming — removes the discriminator from both signatures, and pins the right value on the wire for each. Optional/additive: with no dual_mode block, output is unchanged.

The per-event type is read from the spec when the endpoint documents a streaming media type alongside application/json; otherwise name it with stream_event_model. An entry that can’t be applied is reported as GLOTTO_CONFIG_DUAL_MODE_REFUSED rather than silently ignored. See Streaming → Dual-mode endpoints.

query_settings

query_settings:
  array_format: comma    # or repeat (default)

How an array-typed query parameter is serialized onto the request URL: repeat (?tags=a&tags=b, the OpenAPI form/explode default) or comma (?tags=a,b). A single, client-wide policy; defaults to repeat.