REST API Reference

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

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"}

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,
  "version": "0.19.0",
  "storage": "json",
  "protection": {
    "totalMb": 4096,
    "availableMb": 2900,
    "cpuCount": 2,
    "cpuLoad": 0.35,
    "reserveMb": 615,
    "maxConcurrent": 2,
    "pressure": "Normal",
    "maxQueue": 50,
    "queueTimeoutMs": 600000,
    "active": 1,
    "queued": 0
  },
  "captcha": {
    "healthy": true,
    "activeTier": "owlvit",
    "backend": "onnx",
    "device": "cpu",
    "error": null
  }
}

Response (degraded — database unreachable):

{
  "status": "degraded",
  "uptime": 3600,
  "storage": "postgres",
  "storage_error": "Database unreachable"
}

Field	Description
`status`	`"ok"` or `"degraded"`
`uptime`	Server uptime in seconds
`version`	Running Figranium version
`storage`	`"json"` (file-based) or `"postgres"`
`storage_error`	Present only when the database is unreachable
`protection`	Non-sensitive resource protection state: detected memory and CPU, `maxConcurrent`, `pressure` (`"Normal"` or `"Busy"`), and `active` and `queued` execution counts
`captcha`	Local CAPTCHA solver status (`healthy`, `activeTier`, `backend`, `device`, `error`). Capacity is detected once after boot. Values depend on your host.

Returns HTTP 200 when healthy and 503 when degraded. This endpoint does not require authentication.

`GET /api/capabilities`

Describes the features and action schemas supported by the running server. Use it to check what an instance supports before building tasks. This endpoint does not require authentication.

Capacity and timeout errors

Execution endpoints can return these errors when resource protection is active:

Status	Error code	Cause
`503`	`RESOURCE_CAPACITY_EXCEEDED`	The execution queue is full, or the run waited longer than `EXECUTION_QUEUE_TIMEOUT_MS`. The response includes `retryAfterMs` and a `Retry-After` header.
`504`	`EXECUTION_TIMEOUT`	A non-headful run exceeded `EXECUTION_TIMEOUT_MS` and was stopped.

Trigger a task

`POST /api/tasks/:id/api`

Triggers an execution of a specific task. This is the primary endpoint most integrations use: send a POST to a task’s URL to run it on demand, optionally overriding variables or receiving a webhook callback when it finishes.

You don’t need to assemble this URL by hand. The Trigger via API panel in the task editor’s Task Settings API tab shows the complete endpoint URL for your instance (for example, https://your-figranium.example.com/api/tasks/task_1/api) with a POST badge, and its copy button copies the full URL.

Body:

{
  "variables": {
    "query": "override value"
  },
  "webhookUrl": "https://your-server.com/callback"
}

Field	Type	Required	Description
`variables`	object	No	Override task-level variables for this run
`webhookUrl`	string	No	URL to receive a POST callback with the execution result
`statelessExecution`	boolean	No	Run in a clean browser context with no saved cookies
`sessionId`	string	No	Named session snapshot to load before the run and save after. Persists cookies and local storage to `data/sessions/<sessionId>.json`. Sanitized to `[a-zA-Z0-9_-]`. See Named Session Snapshots

Response: Returns the execution result (JSON).

The request body is optional. If you send the request without a body or without a Content-Type: application/json header, Figranium treats the body as {} and runs the task with its default variables. This lets tools that can’t set request headers (for example, Clay’s HTTP action) trigger a task with a bare POST to the endpoint URL.To pass variables, webhookUrl, statelessExecution, or sessionId, you must send Content-Type: application/json and a JSON body.

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.

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/list

Returns a lightweight list of all saved tasks with summary metadata (ID, name, description, mode, schedule, variables, createdAt, updatedAt) without version history or full action lists. Useful for lightweight listings and dashboard overviews. Requires API-key authentication.Response:

{
  "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/tasks

Lists all saved tasks with full configuration (except version history). Prefer GET /api/tasks/list for lightweight listings.Response:

[
  {
    "id": "task_1",
    "name": "Scraper",
    "description": "Extracts product prices daily",
    "url": "https://example.com",
    "mode": "agent"
  }
]

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 tasks[] entries returned by GET /api/tasks/list so external tools and AI agents have context about the task without fetching its full definition.

PATCH /api/tasks/:id

Applies a partial update to an existing task. Only the fields you include in the body are changed. The id and versions fields are ignored if supplied. Figranium takes a version snapshot of the task before applying the update, so you can restore the previous state from the version history.Use this endpoint when you want to change a single attribute (for example, a schedule, a variable, or one action) without re-sending the full task definition.Body: Any subset of the task’s top-level fields.

{
  "name": "Renamed scraper",
  "description": "Runs every morning",
  "url": "https://example.com/products"
}

Response:

{
  "id": "task_1",
  "updatedAt": "2026-08-05T18:04:12.335Z",
  "status": "success",
  "task": { "id": "task_1", "name": "Renamed scraper", "...": "..." }
}

Error responses:

Status	Error code	Cause
`400`	`INVALID_PAYLOAD`	The request body is not a JSON object
`404`	`TASK_NOT_FOUND`	No task exists with the given `id`

DELETE /api/tasks/:id

Deletes a task by ID. Any in-process schedule registered for the task is also removed, so a scheduled run will not fire after deletion.Response:

{
  "id": "task_1",
  "deleted": true,
  "message": "Task successfully removed."
}

Error responses:

Status	Error code	Cause
`404`	`TASK_NOT_FOUND`	No task exists with the given `id`

POST /api/tasks/:id/api

Triggers an execution of a specific task. See Trigger a task above for the full reference.

Executions

GET /api/executions/list

Returns a lightweight list of execution records with summary metadata (ID, task ID, status, phase, outcome, timestamps, duration) without full logs or result payloads. Use this for dashboard views and history listings when you don’t need the per-execution detail returned by GET /api/executions/:id. Requires API-key authentication.Response:

{
  "executions": [
    {
      "id": "exec_abc123",
      "taskId": "task_1",
      "status": 200,
      "phase": "finished",
      "outcome": "success",
      "startedAt": 1785953052335,
      "finishedAt": 1785953056535,
      "durationMs": 4200
    }
  ]
}

Field	Description
`phase`	`queued`, `running`, or `finished`. Queued and running runs appear in the list before they complete.
`outcome`	The final outcome of the run. Present only when `phase` is `finished`.
`startedAt`	When the run left the queue and started, in milliseconds since the Unix epoch.
`finishedAt`	When the run finished, in milliseconds since the Unix epoch.
`durationMs`	Run duration in milliseconds.

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. Accepts an API key or a signed-in session.If the stored record exceeded MAX_PERSISTED_EXECUTION_BYTES (default 256 KB), the result in the history record is trimmed and marked with "truncated": true and "hasFullResult": true. Use GET /api/executions/:id/result to load the complete result.

GET /api/executions/:id/result

Returns the complete stored result for an execution whose history record was trimmed. Accepts an API key or a signed-in session. Full results are deleted together with execution history when the retention period expires.Response:

{
  "result": {
    "data": [],
    "logs": []
  }
}

Error responses:

Status	Error code	Cause
`404`	`EXECUTION_NOT_FOUND`	No execution exists with the given `id`
`404`	`FULL_RESULT_NOT_AVAILABLE`	The execution was not trimmed, or its full result is no longer stored

POST /api/executions/stop

Stops a running execution, or cancels a run that is still waiting in the execution queue. Requires a signed-in session.Body:

{ "runId": "run_abc123" }

Response:

{ "success": true }

When you cancel a queued run, it never starts, and the original run request responds with 200:

{ "outcome": "stopped", "logs": ["Execution stopped while queued."] }

If the client that started a queued run disconnects before the run starts, Figranium cancels the queued run.Returns 400 MISSING_RUN_ID if runId is missing.

DELETE /api/executions/:id

Deletes a single execution record by ID.Response:

{ "success": true }

Data

GET /api/data/captures

Lists all captured files (screenshots, recordings). Accepts an API key or a signed-in session.

DELETE /api/data/captures/:name

Deletes a specific capture file.

Templates

Use these endpoints to list and fetch community templates from the official Templates Hub. Both endpoints require a signed-in workspace session (the session cookie set when you sign in). API keys are not accepted. Requests are rate limited. Figranium caches the Hub catalog for 5 minutes and waits up to 12 seconds for the Hub to respond.

GET /api/templates

Lists, searches, and sorts community templates.

Without query parameters: returns the full catalog as an array of templates, including configuration, readme, and expected_output.
With any query parameter: returns a page of template summaries as { "items": [...], "total": n }. Summaries omit configuration, readme, and expected_output, and add action_count.

Query parameters:

Parameter	Type	Default	Description
`limit`	integer	`12`	Number of summaries to return, from `1` to `24`.
`offset`	integer	`0`	Number of matching templates to skip.
`sort`	string	`popular`	`popular`, `newest`, or `name`.
`category`	string	`all`	Exact category to filter by, up to 60 characters. Use `all` for every category.
`search`	string		Case-insensitive search across title, description, author name, category, and target URL, up to 100 characters.

Request:

curl "http://localhost:11345/api/templates?search=price&sort=popular&limit=12" \
  -H "Cookie: connect.sid=YOUR_SESSION_COOKIE"

Response:

{
  "items": [
    {
      "id": "3f1c2b9e-6a4d-4c1e-9b7a-2d5e8f0a1b2c",
      "title": "Price tracker",
      "description": "Monitors a product page for price changes",
      "author_name": "Jane Doe",
      "category": "Monitoring",
      "target_url": "https://example.com/product",
      "downloads": 128,
      "action_count": 6
    }
  ],
  "total": 1
}

Error responses:

Status	Error code	Cause
`400`	`INVALID_TEMPLATE_QUERY`	A query parameter is out of range or not allowed
`502`	`TEMPLATE_CATALOG_UNAVAILABLE`	The Templates Hub returned an error
`502`	`TEMPLATE_CATALOG_TIMEOUT`	The Templates Hub did not respond in time
`502`	`TEMPLATE_CATALOG_INVALID`	The Templates Hub returned invalid data

GET /api/templates/:id

Returns a single template, including its workflow configuration, readme, and expected_output. The id must be a UUID.Request:

curl "http://localhost:11345/api/templates/3f1c2b9e-6a4d-4c1e-9b7a-2d5e8f0a1b2c" \
  -H "Cookie: connect.sid=YOUR_SESSION_COOKIE"

Response:

{
  "id": "3f1c2b9e-6a4d-4c1e-9b7a-2d5e8f0a1b2c",
  "title": "Price tracker",
  "description": "Monitors a product page for price changes",
  "author_name": "Jane Doe",
  "category": "Monitoring",
  "target_url": "https://example.com/product",
  "downloads": 128,
  "configuration": { "actions": [] },
  "readme": "# Price tracker\n\nTracks the price of a product page.",
  "expected_output": "{ \"price\": \"$19.99\" }"
}

Error responses:

Status	Error code	Cause
`400`	`INVALID_TEMPLATE_ID`	The `id` is not a UUID
`404`	`TEMPLATE_NOT_FOUND`	No template exists with the given `id`
`502`	`TEMPLATE_CATALOG_UNAVAILABLE`, `TEMPLATE_CATALOG_TIMEOUT`, or `TEMPLATE_CATALOG_INVALID`	The Templates Hub could not be reached or returned invalid data

Paginated list responses and single-template responses include Cache-Control: private, max-age=60.

System settings

GET /api/settings/system

Returns the retention setting along with resource protection, CAPTCHA capacity, and last cleanup status.Response:

{
  "retentionDays": 7,
  "protection": { "maxConcurrent": 2, "pressure": "Normal", "active": 0, "queued": 0 },
  "captcha": { "healthy": true, "activeTier": "owlvit" },
  "cleanup": { "lastRunAt": 1790000000000, "deletedCaptures": 12, "deletedExecutions": 40, "error": null }
}

POST /api/settings/system

Saves the shared retention period for captures and execution history. If the new period is shorter than the old one, cleanup runs immediately and the response includes the result.Body:

{ "retentionDays": 14 }

Field	Type	Required	Description
`retentionDays`	integer or null	Yes	Days to keep data, from `1` to `365`. Use `null` to keep data forever.

Returns 400 INVALID_SYSTEM_SETTINGS for values outside the range.

POST /api/settings/export

Downloads a ZIP archive with the selected workspace data. See Exporting data for the archive contents.Body:

{ "include": ["tasks", "executions", "captures"] }

Field	Type	Required	Description
`include`	string[]	Yes	Categories to export: `tasks`, `executions`, `captures`, `apiKeys`, `cookies`. Unknown values are ignored.

The response is application/zip with Content-Disposition: attachment; filename="figranium-export-YYYY-MM-DD.zip" and Cache-Control: no-store.Error responses:

Status	Error code	Cause
`400`	`EXPORT_SELECTION_REQUIRED`	`include` has no valid categories
`500`	`DATA_EXPORT_FAILED`	The archive could not be generated

Proxies

GET /api/settings/proxies

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

{
  "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"
}

POST /api/settings/proxies

Adds a new proxy.Body:

{
  "server": "http://1.2.3.4:8080",
  "username": "user",
  "password": "pass",
  "label": "US Proxy",
  "isRotatingPool": false,
  "estimatedPoolSize": 500
}

Field	Type	Required	Description
`server`	string	Yes	Proxy address (e.g., `http://1.2.3.4:8080`, `socks5://10.0.0.5:1080`)
`username`	string	No	Authentication username
`password`	string	No	Authentication password
`label`	string	No	Friendly display name
`isRotatingPool`	boolean	No	Mark this proxy as a rotating pool gateway
`estimatedPoolSize`	number	No	Approximate number of IPs behind the gateway (informational)

The server address is validated against the SSRF blocklist. If it points to a private or internal network address, the request returns 400 with INVALID_URL.

POST /api/settings/proxies/import

Bulk imports proxies. Existing proxies with matching server addresses are updated; new addresses are added.Body:

{
  "proxies": [
    { "server": "http://1.2.3.4:8080", "label": "US" },
    { "server": "socks5://5.6.7.8:1080", "username": "user", "password": "pass" }
  ]
}

Each entry supports the same fields as POST /api/settings/proxies. Every entry is validated individually against the SSRF blocklist — if any entry fails, the entire import is rejected.

PUT /api/settings/proxies/:id

Updates an existing proxy by ID.Body: Same fields as POST /api/settings/proxies. The server field is required and re-validated against the SSRF blocklist.

DELETE /api/settings/proxies/:id

Deletes a single proxy by ID.

Browser

Programmatic control of the managed headful browser session. Use these endpoints when an external tool or agent needs to open a browser, drive it, and inspect the page without going through the Figranium UI.

POST /api/browser/open

Launches a headful browser session, or reattaches to the one already running. Returns a sessionId you can pass to other endpoints and a WebSocket endpoint suitable for connecting a Playwright or Chrome DevTools client.Accepts either a signed-in dashboard session or an API key. Session-authenticated callers (the Figranium UI) can launch the browser without adding a header. External callers such as MCP servers or scripts authenticate with x-api-key, Authorization: Bearer, or an apiKey body field, as described under Authentication.Body:

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

Field	Type	Required	Description
`url`	string	No	URL to navigate to after the session starts
`mode`	string	No	Currently only `"headful"` is supported (default)
`devTools`	boolean	No	Reserved for future use
`headless`	boolean	No	Launch Chromium in headless mode. Defaults to `false`. Set to `true` when the host has no display server (for example, a Mac dev machine running Figranium directly on the host, or a headless CI runner). The `HEADLESS` environment variable is honored as a fallback.

Response (200):

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

Automatic headless fallback: if the initial headful launch fails because no display is available, Figranium retries once in headless mode automatically and returns the running session. You only need to pass headless: true explicitly if you want to skip the failed first attempt.Error responses:

Status	Error code	Cause
`409`	`HEADFUL_DISPLAY_UNAVAILABLE`	No X server is available on the host and the headless fallback also failed. Figranium detects this from any of: `missing X server`, `$DISPLAY`, `platform failed to initialize`, `no display server`, `X11 connection failed`, `cannot open display`, or `target closed` during launch.
`409`	`BROWSER_LAUNCH_FAILED`	The session was created but did not reach a running state
`500`	`BROWSER_LAUNCH_FAILED`	The launch threw an unexpected error; see `details` for the underlying message

Example:

curl -X POST http://localhost:11345/api/browser/open \
  -H "x-api-key: $FIGRANIUM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com"}'

Example (explicit headless):

curl -X POST http://localhost:11345/api/browser/open \
  -H "x-api-key: $FIGRANIUM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com", "headless": true}'

Inspector

POST /api/inspector/highlight

Activates the inspect overlay on the active browser session and, given a targetHint, returns up to five candidate elements with CSS selectors, XPath, and a confidence score. Optionally returns a base64-encoded JPEG snapshot of the current viewport with the top match visually outlined.Accepts either a signed-in dashboard session or an API key. This lets the Figranium UI drive the inspector directly while external clients (for example, an MCP server resolving a plain-language target into a selector) authenticate with an API key. See Authentication for accepted formats.Use this endpoint from an external agent or CLI to resolve a plain-language target (for example, "Sign in" or input[name="q"]) into a selector you can feed back into a task action. Match strategy, in order:

Treat targetHint as a CSS selector and run querySelectorAll.
Match common attributes (name, placeholder, aria-label, title, alt, value, data-testid, data-test-id).
Match visible text on button, a, label, span, div, h1–h4, li, and p.

If no browser session is running and you supply url, Figranium launches one first.Body:

{
  "sessionId": "sess_a1b2c3",
  "url": "https://example.com",
  "targetHint": "Sign in"
}

Field	Type	Required	Description
`sessionId`	string	No	If provided, must match the active session or the request returns `409`
`url`	string	No	Navigate to this URL before searching. Also used to launch a session if none is active
`targetHint`	string	No	CSS selector, attribute value, or visible text to locate. Omit to only enable inspect mode and return a snapshot

Response (200):

{
  "success": true,
  "selectors": [
    { "css": "button#login", "xpath": "//*[@id=\"login\"]", "confidence": 0.98 },
    { "css": "button.primary", "xpath": "/html/body/div[2]/button[1]", "confidence": 0.93 }
  ],
  "snapshot": "<base64 JPEG or null>"
}

Error responses:

Status	Error code	Cause
`404`	`NO_ACTIVE_SESSION`	No browser session is running and no `url` was supplied to launch one
`409`	`SESSION_ID_MISMATCH`	The supplied `sessionId` does not match the active session; the active ID is returned as `activeSessionId`
`500`	`INSPECTOR_FAILED`	The inspector threw an unexpected error; see `details`

Example:

curl -X POST http://localhost:11345/api/inspector/highlight \
  -H "x-api-key: $FIGRANIUM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com", "targetHint": "Sign in"}'

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

Removes the schedule from a task. The task itself is kept.Response:

{ "success": true, "schedule": null }

GET /api/schedules/:taskId/status

Returns the schedule configuration and current status for a specific task, including the computed cron expression, human-readable description, and validation status.Response:

{
  "schedule": {
    "enabled": true,
    "frequency": "daily",
    "hour": 9,
    "minute": 0
  },
  "cron": "0 9 * * *",
  "description": "Every day at 9:00 AM",
  "isValid": true
}

​Health

​GET /api/health

​GET /api/capabilities

​Capacity and timeout errors

​Trigger a task

​POST /api/tasks/:id/api

​Completion webhook

​Authentication

​Tasks

​Executions

​Data

​Templates

​System settings

​Proxies

​Browser

​Inspector

​Schedules

Health

`GET /api/health`

`GET /api/capabilities`

Capacity and timeout errors

Trigger a task

`POST /api/tasks/:id/api`

Completion webhook

Authentication

Tasks

Executions

Data

Templates

System settings

Proxies

Browser

Inspector

Schedules