Configuration

ApiClient is safe to pass across concurrency domains (Sendable). Create one client for a shared API configuration, then use RequestOptions only where a call needs different behavior.

Client initializers

The static-token initializer is the usual production setup:

let client = ApiClient(
    baseURL: "https://api.insion.co",
    token: "<token>",
    headers: ["X-Application": "ios"],
    timeout: 30,
    maxRetries: 3
)

Its exact signature is:

ApiClient(
    baseURL: String = ApiEnvironment.default.rawValue,
    token: String,
    headers: [String: String]? = nil,
    timeout: Int? = nil,
    maxRetries: Int? = nil,
    urlSession: Networking.URLSession? = nil
)

The token is sent as Authorization: Bearer <token>. Omit baseURL for the SDK's default environment. The SDK defaults to a 60-second request timeout and two retries. A supplied urlSession controls networking directly, so the timeout setting is ignored when one is provided.

For short-lived credentials, use the alternative async token-provider initializer. The closure is invoked when credentials are needed, allowing refresh logic without rebuilding the client:

let client = ApiClient(token: {
    try await tokenStore.freshAccessToken()
})

Per-request options

Every API method ends with requestOptions: RequestOptions? = nil. These options do not mutate the client and apply only to that invocation.

let response = try await client.listRecords(
    limit: 50,
    requestOptions: .init(
        timeout: 15,
        maxRetries: 0,
        additionalHeaders: ["X-Request-ID": requestID]
    )
)

Do not use additionalQueryParameters or additionalBodyParameters to replace a required typed field. Put required API data in the method arguments or request struct so the compiler and the SDK's encoder preserve the intended shape.

Custom networking

Pass a configured Networking.URLSession as urlSession if you need platform-specific transport behavior. The SDK uses its own default URL session otherwise. Because cancellation is part of Swift concurrency, cancelling the enclosing task is the appropriate way to stop an in-flight call:

let task = Task {
    try await client.listUsers(limit: 100)
}

task.cancel()

Handle cancellation alongside ApiError in calling code, especially in UI flows where a view may disappear while a request is pending.