# API Reference | Swift AI Autocomplete Docs

> For the complete documentation index, see [llms.txt](https://ai-autocomplete.com/llms.txt). A markdown version of any page on this site is available by appending `.md` to its URL path — the homepage is at `/index.md`.

API Reference guide for integrating the AI Autocomplete SDK with Swift. Code examples, setup, and API reference.

Source: https://ai-autocomplete.com/docs/swift/api-reference

---

Every public surface in one place — the configuration, the SwiftUI and UIKit views, and the controller that drives them.

## Configuration

Passed to every entry point. All fields except apiConfig have defaults — set only what you need.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `apiConfig` Required | `APIConfig` | — | Auth + endpoint configuration: .apiKey(...) or .accessToken(...). See Authentication. |
| `requestTimeout` | `TimeInterval` | `15` | Per-request timeout, in seconds. |
| `optionOverrides` | `[String: (String) -> [SuggestionOption]]` | `[:]` | Client-side options per suggestion type — see Advanced. |
| `maskCompletedText` | `Bool` | `false` | Withholds completed-param text from requests and telemetry. The onSubmit result is unaffected. |
| `additionalContext` | `JSONValue?` | `nil` | Optional user context sent with every request as additional_context. Include whatever your app knows (a profile, preferences, workspace or session state) to personalize suggested parameters and options. Seeds the controller property of the same name. |
| `customPlaceholder` | `String?` | `nil` | Overrides the server-suggested placeholder for an empty input. |
| `dropdownTrigger` | `.auto \| .manual \| .hidden` | `.auto` | When the dropdown may open: on focus (.auto), only after a pill tap (.manual), or never (.hidden). |
| `closeDropdownOnBlur` | `Bool` | `true` | Close the dropdown when the input loses focus. |
| `showNonTappableOptions` | `Bool` | `false` | Show header / informational rows in the option list. |
| `optionsPosition` | `.above \| .below` | `.below` | Render the dropdown above or below the input. |
| `pillPlacement` | `.inline \| .dropdown \| .hidden` | `.dropdown` | Where unfilled-parameter pills render: inline in the input, in a bar inside the dropdown, or hidden. |
| `autoFocus` | `Bool` | `true` | Focus the input when the Tier 1 view appears. |
| `onSubmit` | `((AutocompleteResult) -> Void)?` | — | Called with the AutocompleteResult when the query is submitted. |
| `onError` | `((AIAutocompleteError) -> Void)?` | — | Called on the main actor for every terminal error. See Advanced. |
| `onFocus` | `(() -> Void)?` | — | Called when the input gains focus. |
| `onBlur` | `(() -> Void)?` | — | Called when the input loses focus. |

## AIAutocomplete (SwiftUI)

The Tier 1 SwiftUI view. Style it with .aiAutocompleteAppearance(_:) — native modifiers like .font(_:) can't reach the wrapped UIKit view.

| Prop | Type | Description |
| --- | --- | --- |
| `init(configuration:appearance:)` | `(Configuration, AIAutocompleteAppearance)` | Creates the view with its own controller. |
| `init(controller:appearance:)` | `(AIAutocompleteController, AIAutocompleteAppearance)` | Wraps a controller you hold — share it with Tier 2 code or tests. |
| `.submitButton { }` | `@ViewBuilder () -> some View` | Supplies the trailing submit button's visuals; the SDK wires the tap to submit + reset. |
| `.submitButtonHidden(_:)` | `Bool = true` | Hides the trailing submit button entirely — no built-in arrow and no custom content. Submission still works via the keyboard return key. |
| `.dropdownHidden(_:)` | `Bool = true` | Detaches the dropdown from the input: the view renders the input alone, and you anchor .aiAutocompleteDropdown to any view sharing the same controller — e.g. a card wrapping the input alongside other controls. |
| `.focused(_:)` | `FocusState<Bool>.Binding` | Two-way bridge between a @FocusState Boolean and the input's first-responder state. |
| `.aiAutocompleteAppearance(_:)` | `AIAutocompleteAppearance` | Sets the appearance for every AIAutocomplete and AIAutocompleteDropdown in the subtree. |

## AIAutocompleteDropdown (SwiftUI)

The Tier 2 dropdown, paired with your own input through a shared controller.

| Prop | Type | Description |
| --- | --- | --- |
| `AIAutocompleteDropdown(controller:appearance:)` | `View` | Standalone dropdown view — place it yourself; it self-sizes vertically. |
| `.aiAutocompleteDropdown(_:appearance:)` | `View modifier` | Floats the dropdown over the modified view on the configured edge — the same placement Tier 1 uses. |
| `controller.textBinding` | `Binding<String>` | Binding<String> over the controller for wiring TextField / TextEditor; writes route through updateText(_:). |

## AIAutocompleteView (UIKit)

The Tier 1 UIKit view. It reports its height through intrinsicContentSize and starts/stops fetching on window attach/detach.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `init(configuration:appearance:showsDropdown:)` | `(Configuration, AIAutocompleteAppearance, Bool)` | — | Creates the view with its own controller. showsDropdown: false renders the input only. |
| `init(controller:appearance:showsDropdown:)` | `(AIAutocompleteController, AIAutocompleteAppearance, Bool)` | — | Wraps an existing controller. |
| `controller` | `AIAutocompleteController` | — | The backing controller — read state or call actions directly. |
| `appearance` | `AIAutocompleteAppearance` | — | Assign a new value to restyle in place. |
| `submitButtonView` | `UIView?` | `nil` | Custom submit button view; nil uses the built-in button. |
| `showsSubmitButton` | `Bool` | `true` | Hide or show the submit button. |
| `focus() / blur()` | `() -> Bool` | — | Make or resign first responder. Returns whether the change took effect. |
| `reset()` | `() -> Void` | — | Clears state for a fresh session (same as controller.reset()). |

### AIAutocompleteDropdownView (UIKit)

The Tier 2 dropdown for UIKit — add it near your input and share the controller.

| Prop | Type | Description |
| --- | --- | --- |
| `init(controller:appearance:)` | `(AIAutocompleteController, AIAutocompleteAppearance)` | Creates the dropdown over a shared controller. |
| `moveHighlight(by:)` | `(Int) -> Void` | Moves the keyboard highlight by a delta (hardware arrow keys). |
| `selectHighlighted()` | `() -> Bool` | Selects the highlighted option; returns false when nothing is highlighted. |
| `clearHighlight()` | `() -> Void` | Clears the keyboard highlight. |

## AIAutocompleteController

The @MainActor, @Observable state machine behind every tier. SwiftUI views that read its properties re-render automatically.

### State

| Prop | Type | Description |
| --- | --- | --- |
| `text` | `String` | The raw input string, with {{PLACEHOLDER}} tokens inline. |
| `segments` | `[Segment]` | Render-ready spans, in order: .text runs, .completed pill spans, and .identified spans (LLM-identified, not re-editable). |
| `completedParams` | `[CompletedParamState]` | Filled parameters, in order, with their cached options for re-edit. |
| `identifiedParams` | `[IdentifiedParamState]` | Spans of the user's own text the server identified as parameters — see Advanced. Tentative: each response replaces the set, and an entry drops out when its text stops matching. |
| `suggestions` | `[Suggestion]` | Current suggestion pills from the server. |
| `additionalContext` | `JSONValue?` | Mutable: update it as the session evolves and the next request carries the new value. Assigning never fires a request of its own; survives reset(). See Personalization. |
| `filteredOptions` | `[SuggestionOption]` | Tappable options for the active suggestion, after filtering and overrides. |
| `dropdownPillSuggestions` | `[Suggestion]` | Pills for the dropdown's pill bar (pillPlacement: .dropdown, or re-edit). |
| `activeIndex` | `Int` | Index of the active suggestion; -1 when none. |
| `isDropdownOpen` | `Bool` | Whether the dropdown should be visible — derived from focus, trigger mode, and caret position. |
| `isLoading` | `Bool` | A fetch is in flight. |
| `isReady` | `Bool` | Mirrors the server's is_ready flag — the query has enough filled parameters to submit. |
| `isFocused` | `Bool` | The input has first-responder status. |
| `placeholder` | `String?` | Server-suggested placeholder for an empty input. |
| `newParamID` | `UUID?` | ID of a freshly promoted param — drives the shimmer; clear with clearNewParamID(). |
| `editingParam` | `CompletedParamState?` | The completed param being re-edited, if any. |
| `error` | `AIAutocompleteError?` | Last surfaced error; clear with dismissError(). |

### Actions

| Prop | Type | Description |
| --- | --- | --- |
| `start()` | `() -> Void` | Fires the initial fetch. Idempotent — safe to call from multiple onAppear hooks. |
| `stop()` | `() -> Void` | Cancels in-flight work; state is preserved. |
| `reset()` | `() -> Void` | Clears all state and rotates the session ID. |
| `updateText(_:)` | `(String) -> Void` | Sets the input text — recomputes segments, promotes exact matches, debounces the fetch. |
| `selectOption(_:)` | `(SuggestionOption) -> Void` | Promotes an option into a completed param and immediately refetches suggestions conditioned on the answer (what an option tap calls). |
| `setActivePill(_:)` | `(Int) -> Void` | Makes the pill at the index active and opens its options. |
| `removeLastParam()` | `() -> Void` | Removes the most recent completed param. |
| `removeIdentifiedParam(atCaret:)` | `(Int) -> Bool` | Deletes the identified chip whose trailing edge sits at the caret offset; returns whether one was removed. Custom inputs call this on Backspace. |
| `submit()` | `() -> Void` | Builds the AutocompleteResult and calls onSubmit. Does not reset. |
| `submitAndReset()` | `() -> Void` | submit(), then reset(), then start() — the full Tier 2 submit flow. |
| `setFocused(_:)` | `(Bool) -> Void` | Reports focus changes from a custom input; drives isDropdownOpen and onFocus/onBlur. |
| `startEditingParam(_:)` | `(UUID) -> Void` | Enters re-edit mode for a completed param (what a pill tap calls). |
| `exitEditMode()` | `() -> Void` | Leaves re-edit mode without changing the param. |
| `dismissError()` | `() -> Void` | Clears the error property. |
| `clearNewParamID()` | `() -> Void` | Clears newParamID after your UI has shown the new-param effect. |

## AutocompleteResult

Handed to onSubmit. Properties are camelCase — the SDK converts to the API's snake_case on the wire.

| Prop | Type | Description |
| --- | --- | --- |
| `query` | `String` | The human-readable query with parameters filled in. |
| `rawQuery` | `String` | The query with {{PLACEHOLDER}} tokens — send this to your backend. |
| `completedParams` | `[CompletedParam]` | Every filled parameter: placeholder, type, and text. |