Skip to main content
Figranium exposes a local REST API for task management, execution, and data retrieval. Base URL: http://localhost:11345 (default)

​
Health

​
GET /api/health

Returns the server status and storage backend connectivity. Use this endpoint for uptime monitoring, load-balancer health checks, or verifying that Figranium is ready to accept work. Response (healthy): 
{
  "status": "ok",
  "uptime": 3600,
  "storage": "json"
}
Response (degraded — database unreachable): 
{
  "status": "degraded",
  "uptime": 3600,
  "storage": "postgres",
  "storage_error": "Database unreachable"
}
FieldDescription
status"ok" or "degraded"
uptimeServer uptime in seconds
storage"json" (file-based) or "postgres"
storage_errorPresent only when the database is unreachable
Returns HTTP 200 when healthy and 503 when degraded. This endpoint does not require authentication.

​
Authentication

If enabled, authentication must be provided via one of the following methods:
  • Header: x-api-key: your_key or key: your_key
  • Authorization Header: Authorization: Bearer your_key
  • Request Body: {"apiKey": "your_key"} or {"key": "your_key"}

​
Tasks

​
GET /api/tasks

Lists all saved tasks. Each task includes its full configuration except for the version history, which is fetched separately when you open a task in the editor. Response: 
[
  {
    "id": "task_1",
    "name": "Scraper",
    "description": "Extracts product prices daily",
    "url": "https://example.com",
    "mode": "agent"
  }
]
The description field is optional and only present if the task has one.

​
POST /api/tasks

Creates or updates a task. If a task with the same id already exists, it is overwritten. Include ?version=true in the query string to save a version snapshot before overwriting. Body: 
{
  "name": "New Task",
  "description": "Optional summary of what this task does",
  "url": "https://example.com",
  "mode": "agent",
  "actions": []
}
The description field is optional. When set, it appears on the canvas trigger card and in the GET /api/tasks/list response so external tools and AI agents have context about the task without fetching its full definition.

​
POST /api/tasks/:id/api

Triggers an execution of a specific task. Body: 
{
  "variables": {
    "query": "override value"
  },
  "webhookUrl": "https://your-server.com/callback"
}
FieldTypeRequiredDescription
variablesobjectNoOverride task-level variables for this run
webhookUrlstringNoURL to receive a POST callback with the execution result
statelessExecutionbooleanNoRun in a clean browser context with no saved cookies
Response: Returns the execution result (JSON).

​
Completion webhook

When you include a webhookUrl, Figranium sends a POST request to that URL after the task finishes. The webhook URL is validated against the same SSRF rules as all other outbound requests (see Security). If the URL points to a private network and ALLOW_PRIVATE_NETWORKS is false, the request returns 400 INVALID_WEBHOOK_URL. The callback payload looks like this: 
{
  "executionId": "exec_abc123",
  "taskId": "task_1",
  "status": "success",
  "durationMs": 4200,
  "result": { "data": [ ... ] }
}
The webhook request times out after 10 seconds. Delivery failures are logged on the server but do not affect the execution result returned to the original caller.

​
Executions

​
GET /api/executions

Lists execution history. Query Parameters:
  • limit: Number of results (default 50).
  • status: Filter by status code.

​
GET /api/executions/:id

Gets detailed logs and result for a specific execution.

​
Data

​
GET /api/data/captures

Lists all captured files (screenshots, recordings).

​
DELETE /api/data/captures/:name

Deletes a specific capture file.

​
Settings

​
GET /api/settings/proxies

Lists configured proxies.

​
POST /api/settings/proxies

Adds a new proxy. Body: 
{
  "server": "http://1.2.3.4:8080",
  "label": "US Proxy"
}

​
Credentials

​
GET /api/credentials

Lists all saved credentials. Tokens are redacted in the response. Response: 
[
  {
    "id": "cred_a1b2c3d4e5f6g7h8",
    "name": "My Baserow",
    "provider": "baserow",
    "config": {
      "baseUrl": "https://baserow.io",
      "token": "••••••••"
    }
  }
]

​
POST /api/credentials

Creates a new output provider credential. Body: 
{
  "provider": "baserow",
  "name": "My Baserow",
  "config": {
    "baseUrl": "https://baserow.io",
    "token": "your-api-token"
  }
}
The baseUrl is validated against SSRF rules. If the URL points to a private or internal network address (and ALLOW_PRIVATE_NETWORKS is false), the request returns: 
{ "error": "INVALID_BASE_URL", "details": "..." }

​
PUT /api/credentials/:id

Updates an existing credential. The same URL validation applies when updating the baseUrl.

​
DELETE /api/credentials/:id

Deletes a credential by ID. Response: 
{ "success": true }

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

Lists all Baserow databases accessible by the credential. This proxies the request through Figranium so your Baserow token is never exposed to the browser. Response: 
[
  { "id": 1, "name": "Web Scraping" },
  { "id": 2, "name": "Product Data" }
]

​
GET /api/credentials/:id/proxy/baserow/databases/:databaseId/tables

Lists all tables within a specific Baserow database. Response: 
[
  { "id": 45, "name": "Products" },
  { "id": 46, "name": "Pricing History" }
]
These proxy endpoints are used by the task editor’s Output tab to let you browse and select a destination table without leaving Figranium.

​
POST /api/settings/api-key

Generates or regenerates the system API key. If you include an apiKey field in the request body, that value is saved as the new key (max 512 characters). If omitted, a new key is generated automatically. Body (optional): 
{
  "apiKey": "your-custom-key"
}
Error responses:
StatusError codeCause
400API_KEY_TOO_LONGThe supplied key exceeds 512 characters

​
GET /api/settings/selector-finder

Returns the default selector finder preference. Response: 
{ "selectorFinder": "highlight" }
Possible values: "highlight" (standard point-and-click picker) or "ai" (AI Selector Finder).

​
POST /api/settings/selector-finder

Sets the default selector finder tool. Body: 
{ "selectorFinder": "ai" }

​
Headful

​
GET /api/headful/status

Returns the current state of the headful (VNC) browser session. Requires authentication. Response (VNC enabled, session active): 
{
  "useNovnc": true,
  "novncPort": 54311,
  "isRunning": true
}
Response (VNC disabled): 
{
  "useNovnc": false
}
FieldDescription
useNovncWhether VNC support is enabled on the server
novncPortThe port the noVNC viewer is running on (only present when enabled)
isRunningWhether a headful browser session is currently active
Use this endpoint to check if a headful session is running before starting a new one, or to display connection status in a custom integration.

​
Schedules

​
GET /api/schedules

Lists all tasks with an associated schedule. Response: 
{
  "schedules": [
    {
      "taskId": "c1f7a08b",
      "taskName": "Daily Price Check",
      "schedule": {
        "enabled": true,
        "frequency": "daily",
        "hour": 9,
        "minute": 0,
        "nextRun": 1690099200000
      }
    }
  ]
}

​
POST /api/schedules/:taskId

Creates or updates a schedule for a task. Body: 
{
  "enabled": true,
  "frequency": "daily",
  "hour": 9,
  "minute": 0
}
For advanced scheduling, use a cron expression: 
{
  "enabled": true,
  "cron": "0 9 * * 1-5"
}
Response: 
{
  "schedule": { ... },
  "description": "Every day at 9:00 AM",
  "nextRun": 1690099200000
}

​
DELETE /api/schedules/:taskId

Disables the schedule for a task. Response: 
{ "success": true }

​
GET /api/schedules/status/all

Returns runtime status of the scheduler and all active jobs. Response: 
{
  "running": true,
  "scheduledCount": 2,
  "tasks": [
    {
      "taskId": "c1f7a08b",
      "cron": "0 9 * * *",
      "nextRun": "2024-07-23T09:00:00.000Z"
    }
  ]
}