> ## Documentation Index
> Fetch the complete documentation index at: https://figranium.dev/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# SettingsResource: API Keys, AI Models, and Proxies

> Configure Figranium server settings with the Swift SDK. Manage API keys, user agents, AI models, themes, and proxy lists programmatically.

The `SettingsResource` on `client.settings` lets you read and write server-level configuration. You can rotate API keys, change the user agent, set AI provider models, switch themes, and manage proxy lists. Most of these operations require session authentication (`.session`) because they affect the entire server instance.

```swift SettingsResource.swift theme={null}
import Figranium

let client = Figranium(authentication: .session)
```

<Warning>
  Settings methods typically require `.session` authentication. API-key access is usually insufficient for administrative endpoints such as API key rotation and proxy management.
</Warning>

## Methods

<AccordionGroup>
  <Accordion title="`getAPIKey` / `setAPIKey`">
    Read or rotate the server's API key.

    * **HTTP endpoints:** `GET /api/settings/api-key` and `POST /api/settings/api-key`
    * **Signatures:**
      * `getAPIKey(options: RequestOptions = .init()) async throws -> JSONObject`
      * `setAPIKey(_ key: String? = nil, options: RequestOptions = .init()) async throws -> JSONObject`

    Pass `nil` to `setAPIKey` to let the server generate a new key automatically.

    ```swift api_key.swift theme={null}
    let current = try await client.settings.getAPIKey()
    let updated = try await client.settings.setAPIKey("fig_new_key_123")
    ```
  </Accordion>

  <Accordion title="`getUserAgent` / `setUserAgent`">
    Read or change the browser user agent selection.

    * **HTTP endpoints:** `GET /api/settings/user-agent` and `POST /api/settings/user-agent`
    * **Signatures:**
      * `getUserAgent(options: RequestOptions = .init()) async throws -> JSONObject`
      * `setUserAgent(_ selection: String?, options: RequestOptions = .init()) async throws -> JSONObject`

    ```swift user_agent.swift theme={null}
    let current = try await client.settings.getUserAgent()
    let updated = try await client.settings.setUserAgent("Mozilla/5.0 ...")
    ```
  </Accordion>

  <Accordion title="`getAIModels` / `setAIModels`">
    Read or update the AI model configuration.

    * **HTTP endpoints:** `GET /api/settings/ai-models` and `POST /api/settings/ai-models`
    * **Signatures:**
      * `getAIModels(options: RequestOptions = .init()) async throws -> JSONObject`
      * `setAIModels(_ models: JSONObject, options: RequestOptions = .init()) async throws -> JSONObject`

    ```swift ai_models.swift theme={null}
    let current = try await client.settings.getAIModels()
    let updated = try await client.settings.setAIModels([
        "default": .string("gpt-4o"),
        "vision": .string("gpt-4o-vision"),
    ])
    ```
  </Accordion>

  <Accordion title="`getTheme` / `setTheme`">
    Read or change the UI theme.

    * **HTTP endpoints:** `GET /api/settings/theme` and `POST /api/settings/theme`
    * **Signatures:**
      * `getTheme(options: RequestOptions = .init()) async throws -> JSONObject`
      * `setTheme(_ theme: String, options: RequestOptions = .init()) async throws -> JSONObject`

    ```swift theme.swift theme={null}
    let current = try await client.settings.getTheme()
    let updated = try await client.settings.setTheme("dark")
    ```
  </Accordion>

  <Accordion title="Proxy management">
    Manage the proxy list used by browser sessions.

    * **HTTP endpoints:**
      * `GET /api/settings/proxies`
      * `POST /api/settings/proxies`
      * `POST /api/settings/proxies/import`
      * `PUT /api/settings/proxies/{id}`
      * `DELETE /api/settings/proxies/{id}`
      * `DELETE /api/settings/proxies`
      * `POST /api/settings/proxies/default`
      * `POST /api/settings/proxies/rotation`
    * **Signatures:**
      * `listProxies(options: RequestOptions = .init()) async throws -> JSONObject`
      * `addProxy(_ proxy: ProxyInput, options: RequestOptions = .init()) async throws -> JSONObject`
      * `importProxies(_ proxies: [ProxyInput], options: RequestOptions = .init()) async throws -> JSONObject`
      * `updateProxy(_ id: String, proxy: ProxyInput, options: RequestOptions = .init()) async throws -> JSONObject`
      * `deleteProxy(_ id: String, options: RequestOptions = .init()) async throws -> JSONObject`
      * `deleteProxies(_ ids: [String], options: RequestOptions = .init()) async throws -> JSONObject`
      * `setDefaultProxy(_ id: String?, options: RequestOptions = .init()) async throws -> JSONObject`
      * `setProxyRotation(_ input: JSONObject, options: RequestOptions = .init()) async throws -> JSONObject`

    ```swift proxies.swift theme={null}
    let proxy = ProxyInput(
        server: "http://proxy.example.com:8080",
        username: "user",
        password: "pass",
        label: "US East"
    )

    let added = try await client.settings.addProxy(proxy)
    let listed = try await client.settings.listProxies()
    let updated = try await client.settings.updateProxy("proxy_123", proxy: proxy)
    let _ = try await client.settings.deleteProxy("proxy_123")
    let _ = try await client.settings.setDefaultProxy("proxy_123")
    ```

    `ProxyInput` contains `server`, optional `username`, `password`, `label`, `isRotatingPool`, and `estimatedPoolSize`.
  </Accordion>

  <Accordion title="`providerKeys` / `setProviderKeys`">
    Read or write provider-specific API keys. The SDK normalizes the URL path and body key name based on the provider string.

    * **HTTP endpoints:** `GET /api/settings/{provider}-api-key` (or `/api/settings/openai-api-key` for OpenAI)
    * **Signatures:**
      * `providerKeys(_ provider: String, options: RequestOptions = .init()) async throws -> JSONObject`
      * `setProviderKeys(_ provider: String, keys: [String], options: RequestOptions = .init()) async throws -> JSONObject`

    For `"openai"`, the SDK calls `/api/settings/openai-api-key` and sends `"openAiApiKeys"` in the body. For any other provider, it calls `/api/settings/{provider}-api-key` and sends `"{provider}ApiKeys"`.

    ```swift provider_keys.swift theme={null}
    let openai = try await client.settings.providerKeys("openai")
    let _ = try await client.settings.setProviderKeys("openai", keys: ["sk-..."])

    let anthropic = try await client.settings.providerKeys("anthropic")
    let _ = try await client.settings.setProviderKeys("anthropic", keys: ["sk-ant-..."])
    ```
  </Accordion>
</AccordionGroup>

## Related resources

<CardGroup cols={2}>
  <Card title="Authentication" icon="lock" href="/docs/sdk/swift/authentication">
    Use `.session` authentication for settings endpoints.
  </Card>

  <Card title="Request options" icon="sliders" href="/docs/sdk/swift/request-options">
    Pass custom headers and per-request timeouts.
  </Card>

  <Card title="Errors" icon="alert-triangle" href="/docs/sdk/swift/errors">
    Handle `FigraniumError` responses.
  </Card>

  <Card title="Client configuration" icon="user-cog" href="/docs/sdk/swift/client-configuration">
    Configure base URL, timeouts, and default headers.
  </Card>
</CardGroup>