### setup Usage

Source: https://figranium.dev/docs/sdk/js/resources/auth

Example of creating the first admin account on a fresh server.

```ts
const result = await figranium.auth.setup({
  name: "Admin User",
  email: "admin@example.com",
  password: "secure-password-123",
});

console.log(result.success);
```

--------------------------------

### checkSetup Usage

Source: https://figranium.dev/docs/sdk/js/resources/auth

Example of checking if the server requires initial setup.

```ts
const { setupRequired } = await figranium.auth.checkSetup();

if (setupRequired) {
  console.log("Server needs first-time setup");
}
```

--------------------------------

### setup Method Definition

Source: https://figranium.dev/docs/sdk/js/resources/auth

Type definition for the setup method.

```ts
figranium.auth.setup(
  input: { name: string; email: string; password: string },
  options?: RequestOptions
): Promise<{ success: boolean }>
```

--------------------------------

### Install and Build Dependencies

Source: https://figranium.dev/docs/mcp-integration

Install project dependencies and compile the source code.

```bash
npm install
npm run build
```

--------------------------------

### Example .env configuration file

Source: https://figranium.dev/docs/configuration

A comprehensive example of an .env file including server settings, PostgreSQL database configuration, and optional service integrations.

```bash
PORT=11345
SESSION_SECRET=super_secret_key_12345
ALLOWED_IPS=127.0.0.1,192.168.1.0/24
ALLOW_PRIVATE_NETWORKS=false
TRUST_PROXY=true
AUTH_RATE_LIMIT_MAX=20
DATA_RATE_LIMIT_MAX=500
NOVNC_PORT=54311
SESSION_COOKIE_SECURE=true
MAX_CONCURRENT_EXECUTIONS=3

# Optional PostgreSQL configuration (Recommended: Neon)
DB_TYPE=postgres
DB_POSTGRESDB_HOST=ep-example-123456.us-east-2.aws.neon.tech
DB_POSTGRESDB_PORT=5432
DB_POSTGRESDB_USER=figranium_owner
DB_POSTGRESDB_PASSWORD=your_neon_password
DB_POSTGRESDB_DATABASE=neondb
DB_POSTGRESDB_SSL=true

# Optional CloakBrowser engine
USE_CLOAK_ENGINE=true
CLOAKBROWSER_LICENSE_KEY=your_cloakbrowser_license_key

# Optional CAPTCHA solving (remote endpoint; local model runs by default)
CAPTCHA_SOLVER_URL=https://solver.example.com
CAPTCHA_SOLVER_KEY=your-client-key
```

--------------------------------

### Full Task Execution Example

Source: https://figranium.dev/docs/sdk/js/quickstart

A complete example demonstrating client initialization, task definition, saving, execution, and error handling.

```ts
import { actions, Figranium, FigraniumError, variable, type Task } from "@figranium/sdk";

const client = new Figranium({
  ...(process.env.FIGRANIUM_BASE_URL ? { baseUrl: process.env.FIGRANIUM_BASE_URL } : {}),
  apiKey: process.env.FIGRANIUM_API_KEY ?? "",
});

const task: Task = {
  name: "Example search",
  description: "Searches a page and extracts its visible content",
  url: "https://example.com",
  mode: "agent",
  variables: { query: { type: "string", value: "figranium" } },
  actions: [
    actions.waitFor("body"),
    actions.set("activeQuery", variable("query")),
    actions.getContent("body", "pageText"),
  ],
};

try {
  const saved = await client.tasks.save(task);
  const result = await client.runTask(saved.id!, {
    variables: { query: "browser automation" },
  });
  console.log(result.data);
} catch (error) {
  if (error instanceof FigraniumError) {
    console.error(error.status, error.code, error.message);
  } else {
    throw error;
  }
}
```

--------------------------------

### Install Dependencies with yarn

Source: https://figranium.dev/docs/local-development

Install project dependencies using yarn.

```bash
yarn install
```

--------------------------------

### getTheme usage example

Source: https://figranium.dev/docs/sdk/js/resources/settings

Example of retrieving the current UI theme and logging it to the console.

```TypeScript
const { theme } = await figranium.settings.getTheme();
console.log(theme);
```

--------------------------------

### Install Dependencies with npm

Source: https://figranium.dev/docs/local-development

Install project dependencies using npm.

```bash
npm install
```

--------------------------------

### Install Dependencies with pnpm

Source: https://figranium.dev/docs/local-development

Install project dependencies using pnpm.

```bash
pnpm install
```

--------------------------------

### Install @figranium/sdk with bun

Source: https://figranium.dev/docs/sdk/js/installation

Installs the Figranium SDK using bun. Requires Node.js 18 or newer.

```bash
bun add @figranium/sdk
```

--------------------------------

### Build and Start with Docker Compose

Source: https://figranium.dev/docs/multi-arch

Execute this command to compile the source code and start the application containers in detached mode.

```bash
docker compose up --build -d
```

--------------------------------

### Start Web Dashboard

Source: https://figranium.dev/docs/cli-tool

Starting the web dashboard at `http://localhost:11345` by running `figranium` with no arguments. Customize port with `--port`.

```APIDOC
## Start Web Dashboard (Default)

### Description
Running `figranium` without arguments starts the full web dashboard at `http://localhost:11345`.

### Command
```bash
figranium
```

### Option
- `--port <number>` - Start on a custom port.

### Example
```bash
figranium --port 8080
```

```

--------------------------------

### setTheme usage example

Source: https://figranium.dev/docs/sdk/js/resources/settings

Example of setting the UI theme to solarized-dark.

```TypeScript
await figranium.settings.setTheme("solarized-dark");
```

--------------------------------

### Start the Backend Server

Source: https://figranium.dev/docs/local-development

Run the backend server for local development.

```bash
pnpm run server
```

--------------------------------

### Run the Server

Source: https://figranium.dev/docs/mcp-integration

Start the Figranium MCP server.

```bash
npm start
```

--------------------------------

### Full task definition example

Source: https://figranium.dev/docs/sdk/js/actions

A complete example of a Task object, demonstrating navigation, interaction, conditional logic, and data extraction using the actions helper library.

```ts
import { actions, variable, type Task } from "@figranium/sdk";

const task: Task = {
  name: "Search and screenshot",
  url: "https://example.com",
  mode: "agent",
  variables: { query: { type: "string", value: "figranium" } },
  actions: [
    actions.navigate("https://example.com"),
    actions.waitFor("#search"),
    actions.type("#search", variable("query")),
    actions.press("Enter", "#search"),
    actions.waitFor(".results"),
    actions.if({
      selector: ".no-results",
      conditionOp: "exists",
    }),
    actions.stop("no_results"),
    actions.end(),
    actions.getContent(".results", "resultText"),
    actions.screenshot("results"),
  ],
};
```

--------------------------------

### setProviderKeys usage example

Source: https://figranium.dev/docs/sdk/js/resources/settings

Example of setting API keys for the Gemini provider with two keys. This replaces any existing keys for that provider.

```TypeScript
await figranium.settings.setProviderKeys("gemini", ["sk-gemini-1", "sk-gemini-2"]);
```

--------------------------------

### GET /api/executions/list - Lightweight list response (variant)

Source: https://figranium.dev/docs/rest-api

Example JSON response for the GET /api/executions/list endpoint. Returns an 'executions' array with summary metadata (id, taskId, status, startedAt, finishedAt, durationMs) without full logs or result payloads. Requires API-key authentication.

```json
{
  "executions": [
    {
      "id": "exec_abc123",
      "taskId": "task_1",
      "status": "success",
      "startedAt": "2026-08-05T18:04:12.335Z",
      "finishedAt": "2026-08-05T18:04:16.535Z",
      "durationMs": 4200
    }
  ]
}
```

--------------------------------

### Start Figranium with docker compose up

Source: https://figranium.dev/docs/docker-compose

Starts the application in detached mode. Pulls the Figranium Docker image from GHCR, starts the container, maps ports, and mounts local directories to persist tasks, settings, and captures.

```bash
docker compose up -d
```

--------------------------------

### GET /api/executions/list - Lightweight list response

Source: https://figranium.dev/docs/rest-api

Example JSON response for the GET /api/executions/list endpoint. Returns an 'executions' array with summary metadata (id, taskId, taskName, status, startedAt, durationMs) without full logs or result payloads. Requires API-key authentication.

```json
{
  "executions": [
    {
      "id": "exec_abc123",
      "taskId": "task_1",
      "taskName": "Scraper",
      "status": "success",
      "startedAt": "2026-08-05T18:04:12.335Z",
      "durationMs": 4200
    }
  ]
}
```

--------------------------------

### Install @figranium/sdk with pnpm

Source: https://figranium.dev/docs/sdk/js/installation

Installs the Figranium SDK using pnpm. Requires Node.js 18 or newer.

```bash
pnpm add @figranium/sdk
```

--------------------------------

### Run Server in Production Mode

Source: https://figranium.dev/docs/local-development

Start the server with production environment settings.

```bash
NODE_ENV=production pnpm run server
```

--------------------------------

### Install @figranium/sdk with npm

Source: https://figranium.dev/docs/sdk/js/installation

Installs the Figranium SDK using npm. Requires Node.js 18 or newer for built-in fetch, or a modern browser.

```bash
npm install @figranium/sdk
```

--------------------------------

### Install Figranium globally

Source: https://figranium.dev/docs/cli-tool

Install the Figranium package globally using npm.

```bash
npm install -g figranium
```

--------------------------------

### Install @figranium/sdk with yarn

Source: https://figranium.dev/docs/sdk/js/installation

Installs the Figranium SDK using yarn. Requires Node.js 18 or newer.

```bash
yarn add @figranium/sdk
```

--------------------------------

### Add start to Main Task

Source: https://figranium.dev/docs/modular-workflows

Shows how to insert a 'start' action in a main task to invoke a child task by its ID. The child task runs at that point in the workflow.

```json
[
  { "type": "navigate", "value": "https://example.com" },
  { "type": "start", "value": "cookie-handler-task-id" },
  { "type": "click", "selector": ".main-content" }
]
```

--------------------------------

### login Usage

Source: https://figranium.dev/docs/sdk/js/resources/auth

Example of authenticating with a session-enabled client.

```ts
import { Figranium } from "@figranium/sdk";

const sessionClient = new Figranium({
  baseUrl: "http://localhost:11345",
  session: true,
});

const result = await sessionClient.auth.login({
  email: "admin@example.com",
  password: "secure-password-123",
});

console.log(result.success);
```

--------------------------------

### getProviderKeys usage example

Source: https://figranium.dev/docs/sdk/js/resources/settings

Example of retrieving API keys for the OpenAI provider. The response is normalized into a standard Record<string, string[]> and the keys are accessed via the openAiApiKeys property.

```TypeScript
const keys = await figranium.settings.getProviderKeys("openai");
console.log(keys.openAiApiKeys);
```

--------------------------------

### POST /api/browser/open Response

Source: https://figranium.dev/docs/rest-api

Example response returned upon successfully launching a browser session.

```json
{
  "sessionId": "sess_a1b2c3",
  "status": "launched",
  "wsEndpoint": "ws://localhost:11345/devtools/browser/sess_a1b2c3"
}
```

--------------------------------

### me Usage

Source: https://figranium.dev/docs/sdk/js/resources/auth

Example of retrieving the currently authenticated user.

```ts
const { user } = await sessionClient.auth.me();

console.log(user.name);
console.log(user.email);
```

--------------------------------

### Repeating Group Data Structure Example (JSON)

Source: https://figranium.dev/docs/data-extraction

Example output of a repeating group named 'products' with container selector '.product-card'. Shows the structured array of objects with fields like name, price, in_stock, and image.

```json
{
  "products": [
    {
      "name": "Wireless Headphones",
      "price": "$99.99",
      "in_stock": true,
      "image": "https://example.com/images/headphones.jpg"
    },
    {
      "name": "Mechanical Keyboard",
      "price": "$149.00",
      "in_stock": false,
      "image": "https://example.com/images/keyboard.jpg"
    }
  ]
}
```

--------------------------------

### POST /api/browser/open Request Body

Source: https://figranium.dev/docs/rest-api

Example request body for launching a browser session.

```json
{
  "url": "https://example.com",
  "mode": "headful",
  "devTools": false,
  "headless": false
}
```

--------------------------------

### GET /api/settings/proxies

Source: https://figranium.dev/docs/rest-api

Lists configured proxies, rotation settings, and the default proxy.

```APIDOC
## GET /api/settings/proxies

### Description
Lists configured proxies, rotation settings, and the default proxy.

### Method
GET

### Endpoint
/api/settings/proxies

### Response
#### Success Response (200)
- **proxies** (array) - List of proxy objects.
- **defaultProxyId** (string) - ID of the default proxy.
- **includeDefaultInRotation** (boolean) - Whether the default proxy is included in rotation.
- **rotationMode** (string) - Rotation mode (e.g., "round-robin").

#### Response Example
{
  "proxies": [
    { "id": "host", "server": "host_ip", "label": "Host IP (no proxy)" },
    { "id": "proxy_a1b2c3", "server": "http://1.2.3.4:8080", "label": "US Proxy" }
  ],
  "defaultProxyId": "host",
  "includeDefaultInRotation": false,
  "rotationMode": "round-robin"
}
```

--------------------------------

### GET /api/settings/theme

Source: https://figranium.dev/docs/rest-api

Returns the currently persisted UI theme.

```json
{ "theme": "dark" }
```

--------------------------------

### GET /api/settings/ollama-api-key

Source: https://figranium.dev/docs/rest-api

Returns the configured Ollama instances.

```APIDOC
## GET /api/settings/ollama-api-key

### Description
Returns the configured Ollama instances.

### Method
GET

### Endpoint
/api/settings/ollama-api-key

```

--------------------------------

### GET /api/settings/gemini-api-key

Source: https://figranium.dev/docs/rest-api

Returns the configured Gemini API keys.

```APIDOC
## GET /api/settings/gemini-api-key

### Description
Returns the configured Gemini API keys.

### Method
GET

### Endpoint
/api/settings/gemini-api-key

```

--------------------------------

### GET /api/settings/openai-api-key

Source: https://figranium.dev/docs/rest-api

Returns the configured OpenAI API keys.

```APIDOC
## GET /api/settings/openai-api-key

### Description
Returns the configured OpenAI API keys.

### Method
GET

### Endpoint
/api/settings/openai-api-key

```

--------------------------------

### GET /api/settings/selector-finder

Source: https://figranium.dev/docs/rest-api

Returns the default selector finder preference.

```json
{ "selectorFinder": "highlight" }
```

--------------------------------

### First-time server setup with auth.checkSetup and auth.setup

Source: https://figranium.dev/docs/sdk/js/authentication

No credentials are needed. Calls auth.checkSetup() to detect an uninitialized server, then auth.setup() to create the first administrator user with name, email, and password.

```TypeScript
const client = new Figranium({ baseUrl: "https://figranium.example", session: true });

const { setupRequired } = await client.auth.checkSetup();
if (setupRequired) {
  await client.auth.setup({
    name: "Admin",
    email: "admin@example.com",
    password: "a-strong-password",
  });
}
```

--------------------------------

### Task ID Validation Example

Source: https://figranium.dev/docs/modular-workflows

The start action sanitizes the task ID, preserving only alphanumeric characters, underscores, and hyphens. This example shows a start action with a template variable; if the variable resolves to a non-conforming string like '../../api/clear-cookies?', the action fails with 'Invalid task id.' and no request is made.

```json
{
  "type": "start",
  "value": "{{ user_input }}"
}
```

--------------------------------

### Accessing Child Task Output with block.output

Source: https://figranium.dev/docs/modular-workflows

After a start action, the child task's extraction result is available in block.output. This JSON example shows a start action followed by a navigate action that uses the output in the URL.

```json
[
  { "type": "start", "value": "get-auth-token-task-id" },
  {
    "type": "navigate",
    "value": "https://api.example.com/data?token={$block.output}"
  }
]
```

--------------------------------

### GET /api/data/captures

Source: https://figranium.dev/docs/rest-api

Lists all captured files (screenshots, recordings).

```APIDOC
## GET /api/data/captures

### Description
Lists all captured files (screenshots, recordings).

### Method
GET

### Endpoint
/api/data/captures

```

--------------------------------

### HTTP Request Block JSON Example

Source: https://figranium.dev/docs/action-blocks

Example configuration for the http_request block that performs a GET request to an API endpoint, includes an Authorization header using a variable, and stores the parsed response in the variable apiResponse. After execution, {$apiResponse} contains the parsed JSON response.

```json
{
  "type": "http_request",
  "method": "GET",
  "value": "https://api.example.com/products?page={$page}",
  "headers": "{\"Authorization\": \"Bearer {$token}\"}",
  "varName": "apiResponse"
}
```

--------------------------------

### GET /api/settings/claude-api-key

Source: https://figranium.dev/docs/rest-api

Returns the configured Claude (Anthropic) API keys.

```APIDOC
## GET /api/settings/claude-api-key

### Description
Returns the configured Claude (Anthropic) API keys.

### Method
GET

### Endpoint
/api/settings/claude-api-key

```

--------------------------------

### setup

Source: https://figranium.dev/docs/sdk/js/resources/auth

Creates the first admin account on a fresh Figranium server. Call this only when checkSetup returns { setupRequired: true }. No credentials are required for this call.

```APIDOC
## POST /api/auth/setup

### Description
Creates the first admin account on a fresh Figranium server. Call this only when checkSetup returns { setupRequired: true }. No credentials are required for this call.

### Method
POST

### Endpoint
/api/auth/setup

### Parameters
#### Request Body
- **name** (string) - Required - The name of the admin user.
- **email** (string) - Required - The email address of the admin user.
- **password** (string) - Required - The password for the admin account.

### Request Example
{
  "name": "Admin User",
  "email": "admin@example.com",
  "password": "secure-password-123"
}

### Response
#### Success Response (200)
- **success** (boolean) - Indicates whether the setup was successful.

#### Response Example
{
  "success": true
}
```

--------------------------------

### GET /api/schedules/status/all

Source: https://figranium.dev/docs/rest-api

Returns runtime status of the scheduler and all active jobs.

```json
{
  "running": true,
  "scheduledCount": 2,
  "tasks": [
    {
      "taskId": "c1f7a08b",
      "cron": "0 9 * * *",
      "nextRun": "2024-07-23T09:00:00.000Z"
    }
  ]
}
```

--------------------------------

### Start Web Dashboard

Source: https://figranium.dev/docs/cli-tool

Launch the web dashboard, optionally specifying a custom port.

```bash
figranium
figranium --port 8080   # Start on a custom port
```

--------------------------------

### Get Content (get_content) block JSON example

Source: https://figranium.dev/docs/action-blocks

Example configuration for the get_content action block. It extracts the innerText of the element matching the selector '.article-body' and stores it in the variable 'articleText'. If the selector matches no element, the result is null. After the block runs, {$articleText} contains the visible text.

```json
{
  "type": "get_content",
  "selector": ".article-body",
  "varName": "articleText"
}
```

--------------------------------

### GET /api/credentials/:id/proxy/baserow/databases

Source: https://figranium.dev/docs/rest-api

Lists all Baserow databases accessible by the credential, proxying the request through Figranium.

```json
[
  { "id": 1, "name": "Web Scraping" },
  { "id": 2, "name": "Product Data" }
]
```

--------------------------------

### GET /api/tasks/list Response

Source: https://figranium.dev/docs/rest-api

The response format for a lightweight list of tasks with summary metadata.

```json
{
  "tasks": [
    {
      "id": "task_1",
      "name": "Scraper",
      "description": "Extracts product prices daily",
      "mode": "agent",
      "schedule": { "enabled": true, "cron": "0 9 * * *" },
      "variables": {},
      "updatedAt": "2026-08-05T18:04:12.335Z",
      "createdAt": "2026-08-01T12:00:00.000Z"
    }
  ]
}
```

--------------------------------

### GET /api/settings/ai-models

Source: https://figranium.dev/docs/rest-api

Returns the currently configured default model for each AI provider. Requires authentication.

```json
{
  "gemini": "gemini-3-flash-preview",
  "openai": "gpt-5-nano",
  "claude": "claude-haiku-4-6",
  "ollama": "llama3.2"
}
```