iOS quickstart

RoadieKit is a small Swift SDK for chat, embeddings, and AI image generation and editing. It authenticates each device anonymously — no login screen and no provider key in the app — calling Roadie’s native /v1 surface for chat and embeddings and the OpenAI-compatible surface at /openai/v1 for images. Roadie holds your provider keys (BYOK), meters usage per device, and enforces free-vs-pro limits.

Prerequisites

In the dashboard:

Create a project (its development and production environments are created for you).
Connect an OpenAI provider credential (BYOK). Image generation uses gpt-image-1, so an OpenAI key is required. See Providers & BYOK.
Create a publishable key (rd_pk_…). It ships in the app and can only mint device tokens — it cannot call model endpoints.
For local development, create a secret key (rd_sk_…) or pre-mint a client token to use as a static bearer while you build (see step 2).
For production device auth, enable device attestation on the project (Apple App Attest). See Mobile device auth.

1. Install RoadieKit

Add RoadieKit with Swift Package Manager. In Xcode, choose File → Add Package Dependencies… and enter https://github.com/paroaria/roadiekit.git, or add it to Package.swift:

dependencies: [
    .package(url: "https://github.com/paroaria/roadiekit.git", from: "0.2.0"),
],
targets: [
    .target(name: "YourApp", dependencies: [
        .product(name: "RoadieKit", package: "roadiekit"),
    ]),
]

RoadieKit requires iOS 18+.

2. Configure the client

A Roadie client needs a RoadieConfig (where the gateway lives) and a token provider (how each request is authenticated). Swap the provider between local development and production without changing any call site:

StaticTokenProvider — a fixed bearer read from the run scheme’s ROADIE_STATIC_TOKEN environment variable (an rd_sk_… key or a pre-minted client token). The working simulator / dev path.
AppAttestTokenProvider — silently mints a per-device client token via Apple App Attest, using the publishable key. The production path; it needs a real device (App Attest is unavailable in the simulator).

import RoadieKit

func makeRoadie() -> Roadie {
    let config = RoadieConfig(
        baseURL: URL(string: "https://gateway.roadie.paroaria.ai")!,
        publishableKey: "rd_pk_…"   // used only by App Attest device auth
    )

    let tokenProvider: any TokenProvider
    if let token = ProcessInfo.processInfo.environment["ROADIE_STATIC_TOKEN"],
       !token.trimmingCharacters(in: .whitespacesAndNewlines).isEmpty {
        // Local dev / simulator: an rd_sk_… secret key or a pre-minted client token.
        tokenProvider = StaticTokenProvider(token: token)
    } else {
        // Production: App Attest silently mints a per-device client token.
        tokenProvider = AppAttestTokenProvider(config: config)
    }

    return Roadie(config: config, tokenProvider: tokenProvider)
}

Keep configuration out of source: read the base URL and publishable key from Info.plist (RoadieBaseURL / RoadiePublishableKey) and inject ROADIE_STATIC_TOKEN from the run scheme so it is never committed or shipped in a Release build.

3. Chat and embeddings

Chat and embeddings are the simplest calls and live on Roadie’s native /v1 surface. Send a message and read the reply:

let roadie = makeRoadie()

let response = try await roadie.chat.create(
    ChatRequest(
        model: "openai/gpt-4o",
        messages: [.user("Give me one tip for shipping an iOS app.")]
    )
)
print(response.text)

Stream the reply token-by-token with roadie.chat.stream(_:) (an AsyncThrowingStream of typed events), and embed text with roadie.embeddings.create(_:). See the RoadieKit reference for the full chat, streaming, and embeddings API, and the Send a message tutorial for an end-to-end walkthrough.

4. Generate an image

images.generate creates an image from a prompt alone and returns the generated image’s raw PNG bytes:

let png = try await roadie.images.generate(
    prompt: "A watercolor fox on a transparent background.",
    size: .square,
    background: .transparent,
    quality: .high
)

let image = UIImage(data: png)

The image model defaults to gpt-image-1 (set RoadieConfig.imageModel to change it), and n defaults to 1. size is one of .auto, .square, .landscape, .portrait; background is .transparent, .opaque, or .auto (when omitted, generate defaults to .opaque and edit to .transparent); quality is .low, .medium, .high, or .auto.

5. Edit an image

images.edit takes the source PNG bytes and a prompt and returns the generated image’s raw PNG bytes. mask is optional; when present, only the masked region is regenerated.

// `sourceImage` and `mask` are PNG bytes (Data). `mask` may be nil.
let outputPNG: Data = try await roadie.images.edit(
    image: sourceImage,
    mask: mask,
    prompt: "Replace the background with a sunlit forest.",
    size: .auto,
    background: .transparent,
    quality: .high
)

let image = UIImage(data: outputPNG)

6. Handle errors

Every HTTP or decoding failure is thrown as a RoadieError; task cancellation is Swift’s own CancellationError. Branch on error.kind:

do {
    let png = try await roadie.images.edit(image: sourceImage, prompt: prompt)
    // …use the bytes…
} catch let error as RoadieError {
    switch error.kind {
    case .insufficientQuota:
        // The device crossed its free tier — show your paywall.
        break
    case .rateLimited:
        // Over the tier's rate limit — back off and retry shortly.
        break
    case .contentRejected:
        // The prompt or image was declined by the content policy.
        break
    case .tokenUnavailable:
        // No token: set ROADIE_STATIC_TOKEN (dev) or enable App Attest (prod).
        break
    default:
        // .unauthorized / .forbidden / .notFound / .invalidRequest /
        // .server / .timedOut / .network / .decoding
        break
    }
} catch {
    // CancellationError — the surrounding task was cancelled.
}

RoadieKit handles two cases for you: it re-mints once on a 401 (an expired client token) and retries transient network and 5xx failures. An insufficientQuota error is your cue to show the paywall — see Free → Pro with StoreKit.

Next steps

Anonymous device auth

How App Attest mints per-device client tokens with no account.

Free → Pro with StoreKit

Convert the free tier to a paid subscription and flip the device’s plan.

Send a message

Set up the SDK, send a chat message through Roadie, and get a reply.

RoadieKit reference

The full chat, embeddings, and image API, plus the token providers.

Android quickstart

The same for Android, with the Kotlin SDK and Play Integrity device auth.

Get started

Core concepts

Guides

SDKs

iOS quickstart

Prerequisites

1. Install RoadieKit

2. Configure the client

3. Chat and embeddings

4. Generate an image

5. Edit an image

6. Handle errors

Next steps

Anonymous device auth

Free → Pro with StoreKit

Send a message

RoadieKit reference

Android quickstart

​Prerequisites

​1. Install RoadieKit

​2. Configure the client

​3. Chat and embeddings

​4. Generate an image

​5. Edit an image

​6. Handle errors

​Next steps

Anonymous device auth

Free → Pro with StoreKit

Send a message

RoadieKit reference

Android quickstart

Prerequisites

1. Install RoadieKit

2. Configure the client

3. Chat and embeddings

4. Generate an image

5. Edit an image

6. Handle errors

Next steps