Figranium Kotlin SDK Quickstart

The Figranium Kotlin SDK lets you drive a Figranium server from Kotlin: build tasks with typed action helpers, run them with coroutines, and stream results as Flow. This quickstart walks you from an empty project to running your first task in a handful of lines.

Prerequisites

Kotlin 2.2 or later
A JVM toolchain of 17 (or Android minSdk 23)
A running Figranium instance (http://localhost:11345 by default)
An API key generated from the Figranium web UI

Install the SDK

Add the Gradle dependency. See Installation for the full manifest snippet.

build.gradle.kts

dependencies {
    implementation("dev.figranium:figranium:0.1.0")
}

Create a client

Store your API key securely (for example, in environment variables or Android Keystore) so it never lands in source control.

quickstart.kt

import dev.figranium.sdk.*
import kotlinx.serialization.json.*

val client = Figranium(
    baseUrl = "http://localhost:11345",
    authentication = FigraniumAuthentication.ApiKey(
        value = System.getenv("FIGRANIUM_API_KEY") ?: ""
    ),
)

See Client configuration for every constructor option and Authentication for API key setup.

Define and save a task

Use Actions helpers to describe the browser workflow. variable("query") produces the template token {\$query} that is replaced at runtime.

quickstart.kt

val task = Task(
    name = "Search example",
    url = "https://example.com",
    mode = "scrape",
    variables = mapOf(
        "query" to TaskVariable(type = "string", value = JsonPrimitive("figranium")),
    ),
    actions = listOf(
        Actions.type("#search", variable("query")),
        Actions.click("button[type=submit]"),
        Actions.waitFor(".results"),
        Actions.getContent(selector = ".results", varName = "html"),
    )
)

val saved = client.tasks.save(task)

See Actions for every helper and Variables for typed variable declarations.

Run the task

Use runTask (a shortcut for client.tasks.run) and pass runtime variable overrides in ExecuteTaskOptions.

quickstart.kt

import kotlinx.serialization.json.JsonElement

val result: ExecutionResult<JsonElement> = client.runTask(
    id = saved.id!!,
    input = ExecuteTaskOptions(
        variables = mapOf("query" to JsonPrimitive("browser automation"))
    ),
)

println(result.success)
println(result.outcome)
println(result.data)

Watch the execution

Poll the execution and emit only when the status changes. The flow finishes when the run reaches a terminal state.

quickstart.kt

client.executions.watch(result.runId ?: "").collect { execution ->
    println("${execution.status} ${execution.outcome}")
}

See Streaming for executions.stream() and browser.selectorStream().

Handle errors

Every HTTP, transport, and timeout failure throws FigraniumException. Inspect status and code to branch on the failure kind.

quickstart.kt

try {
    val result = client.runTask<JsonElement>(saved.id!!, ExecuteTaskOptions())
} catch (error: FigraniumException) {
    println("${error.status} ${error.code} ${error.requestId}")
}

See Errors for the full list of codes.

Complete example

quickstart.kt

import dev.figranium.sdk.*
import kotlinx.serialization.json.*

val client = Figranium(
    baseUrl = "http://localhost:11345",
    authentication = FigraniumAuthentication.ApiKey(
        value = System.getenv("FIGRANIUM_API_KEY") ?: ""
    ),
)

val task = Task(
    name = "Search example",
    url = "https://example.com",
    mode = "scrape",
    variables = mapOf(
        "query" to TaskVariable(type = "string", value = JsonPrimitive("figranium")),
    ),
    actions = listOf(
        Actions.type("#search", variable("query")),
        Actions.click("button[type=submit]"),
        Actions.waitFor(".results"),
        Actions.getContent(selector = ".results", varName = "html"),
    )
)

try {
    val saved = client.tasks.save(task)
    val result: ExecutionResult<JsonElement> = client.runTask(
        id = saved.id!!,
        input = ExecuteTaskOptions(
            variables = mapOf("query" to JsonPrimitive("browser automation"))
        ),
    )
    println(result.data)
} catch (error: FigraniumException) {
    println("[${error.status}] ${error.code}: ${error.message}")
}

Direct execution without saving

For one-off runs, skip tasks.save and call client.scrape, client.agent, or client.headful directly. These use the same task shape, but the server does not persist them.

direct.kt

import kotlinx.serialization.json.*

val result: ExecutionResult<JsonElement> = client.scrape(
    input = mapOf(
        "url" to JsonPrimitive("https://example.com"),
        "selector" to JsonPrimitive("body"),
    )
)
println(result.data)

Next steps

Action helpers

Every helper you can use to build a task, from navigation to CAPTCHA solving.

Streaming

Collect live executions with client.executions.stream().

Handle errors

FigraniumException fields, codes, and cancellation semantics.

Tasks resource

Save, version, list, and run tasks programmatically.

Introduction

JavaScript SDK

Python SDK

Swift SDK

Kotlin SDK

Figranium Kotlin SDK Quickstart

Prerequisites

Complete example

Direct execution without saving

Next steps

Action helpers

Streaming

Handle errors

Tasks resource

​Prerequisites

​Complete example

​Direct execution without saving

​Next steps

Action helpers

Streaming

Handle errors

Tasks resource

Prerequisites

Complete example

Direct execution without saving

Next steps