Kotlin SDK Models and Data Types

The Figranium Kotlin SDK uses strongly typed data classes, typealiases, and kotlinx.serialization for all API payloads. This page documents the public model layer: JSON typealiases, the Task data class, execution types, and supporting configuration structs.

Typealiases

The SDK provides two typealiases for convenience:

Models.kt

typealias JSONObject = Map<String, JsonElement>
typealias RuntimeVariables = Map<String, JsonElement>
typealias TaskMode = String
typealias TaskOutcome = String

Use JSONObject when you need to accept or return arbitrary JSON shapes, such as task inputs or execution results. RuntimeVariables is the type for variable overrides at execution time.

TaskVariable

TaskVariable declares a typed variable on a task.

Models.kt

@Serializable
data class TaskVariable(
    val type: String,
    val value: JsonElement,
    val autoCreated: Boolean? = null
)

Task

Task defines a browser automation workflow. It is a @Serializable data class with all properties exposed directly.

Models.kt

@Serializable
data class Task(
    val name: String,
    val url: String,
    val mode: String,
    val description: String = "",
    val id: String? = null,
    val wait: Double? = null,
    val selector: String? = null,
    val rotateUserAgents: Boolean? = null,
    val rotateProxies: Boolean? = null,
    val rotateViewport: Boolean? = null,
    val humanTyping: Boolean? = null,
    val stealth: StealthConfig? = null,
    val autoSolveCaptcha: Boolean? = null,
    val translation: TaskTranslation? = null,
    val actions: List<Action>? = null,
    val variables: Map<String, TaskVariable>? = null,
    val schedule: Schedule? = null,
    val output: TaskOutput? = null,
    val extractionScript: String? = null,
    val extractionFormat: String? = null,
    val includeHtml: Boolean? = null,
    val includeShadowDom: Boolean? = null,
    val disableRecording: Boolean? = null,
    val statelessExecution: Boolean? = null,
    val downloadCabinetId: String? = null,
    val cabinetId: String? = null,
)

The primary constructor requires name, url, and mode. All other fields are optional and default to null.

Action

Action is the atomic unit of a task. It is a @Serializable data class.

Models.kt

@Serializable
data class Action(
    val type: String,
    val id: String? = null,
    val disabled: Boolean? = null,
    val selector: String? = null,
    val targetSelector: String? = null,
    val value: String? = null,
    val clickType: String? = null,
    val typeMode: String? = null,
    val key: String? = null,
    val varName: String? = null,
    val method: String? = null,
    val headers: String? = null,
    val body: String? = null,
    val conditionVar: String? = null,
    val conditionVarType: String? = null,
    val conditionOp: String? = null,
    val conditionValue: String? = null,
    val captchaType: String? = null,
    val timeout: Double? = null,
    val cabinetId: String? = null,
    val markAsUploaded: Boolean? = null,
)

The primary constructor requires type. All other fields are optional. The Actions object helpers auto-generate an id in the format act_<type>_<uuid> when id is null.

ExecuteTaskOptions

ExecuteTaskOptions is passed to runTask and other execution methods to override variables and configure the run.

Models.kt

@Serializable
data class ExecuteTaskOptions(
    val variables: RuntimeVariables? = null,
    val taskVariables: RuntimeVariables? = null,
    val webhookUrl: String? = null,
    val runId: String? = null
)

ExecutionResult

ExecutionResult is the generic return type for task executions. T is the deserialized data type.

Models.kt

@Serializable
data class ExecutionResult<T>(
    val data: T? = null,
    val outcome: String? = null,
    val success: Boolean? = null,
    val error: String? = null,
    val runId: String? = null
)

Execution

Execution represents a single recorded run.

Models.kt

@Serializable
data class Execution(
    val id: String,
    val timestamp: Double,
    val method: String? = null,
    val path: String? = null,
    val status: String? = null,
    val outcome: String? = null,
    val durationMs: Double? = null,
    val source: String? = null,
    val mode: String? = null,
    val taskId: String? = null,
    val taskName: String? = null,
    val url: String? = null,
    val result: JsonElement? = null
)

StreamEvent

StreamEvent wraps a Server-Sent Events payload.

Models.kt

data class StreamEvent<T>(
    val data: T,
    val event: String? = null,
    val id: String? = null,
    val retry: Int? = null,
    val raw: String
)

The SDK uses StreamEvent<JsonElement> for execution and selector streams.

Supporting data classes

StealthConfig

Models.kt

@Serializable
data class StealthConfig(
    val allowTypos: Boolean? = null,
    val idleMovements: Boolean? = null,
    val overscroll: Boolean? = null,
    val deadClicks: Boolean? = null,
    val fatigue: Boolean? = null,
    val naturalTyping: Boolean? = null,
    val cursorGlide: Boolean? = null,
    val randomizeClicks: Boolean? = null,
)

TaskTranslation

Models.kt

@Serializable
data class TaskTranslation(
    val enabled: Boolean,
    val targetLanguage: String
)

TaskOutput

Models.kt

@Serializable
data class TaskOutput(
    val provider: String = "baserow",
    val credentialId: String,
    val tableId: String,
    val onError: String? = null
)

Schedule

Models.kt

@Serializable
data class Schedule(
    val enabled: Boolean,
    val frequency: String? = null,
    val intervalMinutes: Int? = null,
    val hour: Int? = null,
    val minute: Int? = null,
    val daysOfWeek: List<Int>? = null,
    val dayOfMonth: Int? = null,
    val cron: String? = null,
    val lastRun: Double? = null,
    val lastRunStatus: String? = null,
    val lastRunDurationMs: Double? = null,
    val nextRun: Double? = null,
)

Other types

Type	Key fields
`TaskSummary`	`id: String`, `name: String`, `description: String?`
`TaskVersion`	`id: String`, `timestamp: Double`, `name: String?`, `mode: String?`
`Cabinet`	`id: String`, `name: String`, `isDefault: Boolean?`, `itemCount: Int?`, `createdAt: Double?`
`CabinetItem`	`id: String`, `name: String`, `kind: String`, `status: String`, `size: Int?`, `createdAt: Double?`, `sourceTaskId: String?`, `sourceRunId: String?`
`Capture`	`name: String`, `url: String`, `size: Int`, `modified: Double`, `type: String`
`BrowserSession`	`sessionId: String`, `status: String`, `wsEndpoint: String?`
`SelectorCandidate`	`css: String`, `xpath: String?`, `confidence: Double?`
`HealthStatus`	`status: String`, `version: String?`
`RequestOptions`	`headers: Map<String, String>`, `timeoutMillis: Long?`

Actions

Build action lists with typed helpers.

Variables

Declare and reference task variables.

Tasks resource

Save, version, and execute tasks.

Execution resource

Run scrape, agent, and headful executions.

Introduction

JavaScript SDK

Python SDK

Swift SDK

Kotlin SDK

Kotlin SDK Models and Data Types

Typealiases

TaskVariable

Task

Action

ExecuteTaskOptions

ExecutionResult

Execution

StreamEvent

Supporting data classes

StealthConfig

TaskTranslation

TaskOutput

Schedule

Other types

Actions

Variables

Tasks resource

Execution resource

​Typealiases

​TaskVariable

​Task

​Action

​ExecuteTaskOptions

​ExecutionResult

​Execution

​StreamEvent

​Supporting data classes

​StealthConfig

​TaskTranslation

​TaskOutput

​Schedule

​Other types

​Related

Actions

Variables

Tasks resource

Execution resource

Typealiases

TaskVariable

Task

Action

ExecuteTaskOptions

ExecutionResult

Execution

StreamEvent

Supporting data classes

StealthConfig

TaskTranslation

TaskOutput

Schedule

Other types

Related