> ## Documentation Index
> Fetch the complete documentation index at: https://figranium.dev/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# TasksResource: Manage and Run Figranium Tasks

> Reference for the TasksResource class in the Figranium JavaScript SDK. Create, update, version, and execute tasks with typed requests and responses.

The `TasksResource` class is the primary way to manage Figranium tasks through the JavaScript SDK. Use it to list, create, update, version, and run tasks, as well as to generate selectors and scripts with AI assistance. Every method is typed against the Figranium API and accepts an optional [`RequestOptions`](/docs/sdk/js/request-options) object as its final argument.

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

const figranium = new Figranium({ apiKey: process.env.FIGRANIUM_API_KEY! });
```

<Note>
  The client-level convenience `figranium.runTask(id, input?)` proxies directly to `figranium.tasks.run(id, input?)`.
</Note>

## Methods

<AccordionGroup>
  <Accordion title="list">
    Retrieve every task in the workspace.

    * **HTTP endpoint:** `GET /api/tasks`
    * **Signature:** `list(options?: RequestOptions): Promise<Task[]>`

    ```ts list-tasks.ts theme={null}
    const tasks = await figranium.tasks.list();
    console.log(tasks.length);
    ```

    Returns an array of [`Task`](/docs/sdk/js/resources/tasks#task-type) objects.
  </Accordion>

  <Accordion title="listSummaries">
    Fetch a lightweight summary of all tasks.

    * **HTTP endpoint:** `GET /api/tasks/list`
    * **Signature:** `listSummaries(options?: RequestOptions): Promise<{ tasks: TaskSummary[] }>`

    ```ts list-summaries.ts theme={null}
    const { tasks } = await figranium.tasks.listSummaries();
    for (const t of tasks) {
      console.log(t.id, t.name);
    }
    ```

    Each `TaskSummary` contains `id`, `name`, and an optional `description`.
  </Accordion>

  <Accordion title="save">
    Create or update a task. Pass `createVersion: true` to snapshot the current version before saving.

    * **HTTP endpoint:** `POST /api/tasks` (with `?version=true` when `createVersion` is set)
    * **Signature:** `save(task: Task, options?: RequestOptions & { createVersion?: boolean }): Promise<Task>`

    ```ts save-task.ts theme={null}
    import { actions, variable, type Task } from "@figranium/sdk";

    const task: Task = {
      name: "Search and extract",
      url: "https://example.com",
      mode: "agent",
      variables: {
        query: { type: "string", value: "figranium" },
      },
      actions: [
        actions.waitFor("#search"),
        actions.type("#search", variable("query")),
        actions.press("Enter", "#search"),
        actions.getContent(".results", "resultText"),
      ],
    };

    const saved = await figranium.tasks.save(task, { createVersion: true });
    console.log(saved.id);
    ```

    Returns the saved [`Task`](/docs/sdk/js/resources/tasks#task-type), including any server-generated `id`.
  </Accordion>

  <Accordion title="touch">
    Refresh a task's `last_opened` timestamp without changing its definition.

    * **HTTP endpoint:** `POST /api/tasks/:id/touch`
    * **Signature:** `touch(id: string, options?: RequestOptions): Promise<Task>`

    ```ts touch-task.ts theme={null}
    const updated = await figranium.tasks.touch("task_123");
    ```
  </Accordion>

  <Accordion title="update">
    Apply a partial patch to an existing task.

    * **HTTP endpoint:** `PATCH /api/tasks/:id`
    * **Signature:** `update(id: string, patch: Partial<Task>, options?: RequestOptions): Promise<{ id: string; updatedAt: number; status: string; task: Task }>`

    ```ts update-task.ts theme={null}
    const result = await figranium.tasks.update("task_123", {
      name: "Renamed task",
      wait: 2000,
    });
    console.log(result.updatedAt);
    ```
  </Accordion>

  <Accordion title="delete">
    Remove a task by ID.

    * **HTTP endpoint:** `DELETE /api/tasks/:id`
    * **Signature:** `delete(id: string, options?: RequestOptions): Promise<{ id: string; deleted: boolean; message?: string }>`

    ```ts delete-task.ts theme={null}
    const result = await figranium.tasks.delete("task_123");
    console.log(result.deleted, result.message);
    ```
  </Accordion>

  <Accordion title="versions">
    List all saved versions for a task.

    * **HTTP endpoint:** `GET /api/tasks/:id/versions`
    * **Signature:** `versions(id: string, options?: RequestOptions): Promise<{ versions: TaskVersion[] }>`

    ```ts list-versions.ts theme={null}
    const { versions } = await figranium.tasks.versions("task_123");
    for (const v of versions) {
      console.log(v.id, v.timestamp, v.name);
    }
    ```
  </Accordion>

  <Accordion title="version">
    Retrieve a specific version snapshot.

    * **HTTP endpoint:** `GET /api/tasks/:id/versions/:versionId`
    * **Signature:** `version(id: string, versionId: string, options?: RequestOptions): Promise<{ snapshot: Task; metadata: { id: string; timestamp: number } }>`

    ```ts get-version.ts theme={null}
    const { snapshot, metadata } = await figranium.tasks.version("task_123", "v_456");
    console.log(metadata.timestamp, snapshot.name);
    ```
  </Accordion>

  <Accordion title="clearVersions">
    Delete all stored versions for a task.

    * **HTTP endpoint:** `POST /api/tasks/:id/versions/clear`
    * **Signature:** `clearVersions(id: string, options?: RequestOptions): Promise<{ success: boolean }>`

    ```ts clear-versions.ts theme={null}
    const result = await figranium.tasks.clearVersions("task_123");
    ```
  </Accordion>

  <Accordion title="rollback">
    Restore a task to a previous version snapshot.

    * **HTTP endpoint:** `POST /api/tasks/:id/rollback`
    * **Signature:** `rollback(id: string, versionId: string, options?: RequestOptions): Promise<Task>`

    ```ts rollback-task.ts theme={null}
    const restored = await figranium.tasks.rollback("task_123", "v_456");
    console.log(restored.id);
    ```
  </Accordion>

  <Accordion title="generateSelector">
    Use AI to generate a CSS selector for a specific action inside a task.

    * **HTTP endpoint:** `POST /api/tasks/generate-selector`
    * **Signature:** `generateSelector(input: { task: Task; actionIndex: number; prompt: string }, options?: RequestOptions): Promise<{ selector: string }>`

    ```ts generate-selector.ts theme={null}
    const { selector } = await figranium.tasks.generateSelector({
      task: savedTask,
      actionIndex: 2,
      prompt: "Target the primary search button",
    });
    console.log(selector);
    ```
  </Accordion>

  <Accordion title="generateScript">
    Generate a JavaScript extraction script from a natural language description.

    * **HTTP endpoint:** `POST /api/tasks/generate-script`
    * **Signature:** `generateScript(description: string, options?: RequestOptions): Promise<{ script: string }>`

    ```ts generate-script.ts theme={null}
    const { script } = await figranium.tasks.generateScript(
      "Extract all product names and prices from the page"
    );
    console.log(script);
    ```
  </Accordion>

  <Accordion title="run">
    Execute a task and return its result. This is the public execution endpoint, reachable at `/tasks/:id/api`.

    * **HTTP endpoint:** `POST /tasks/:id/api`
    * **Signature:** `run<T = unknown>(id: string, input?: ExecuteTaskOptions, options?: RequestOptions): Promise<ExecutionResult<T>>`

    ```ts run-task.ts theme={null}
    const result = await figranium.tasks.run<{ items: string[] }>("task_123", {
      variables: { query: "browser automation" },
    });
    console.log(result.data?.items);
    ```

    The generic `T` parameter types `result.data`. The `input` object accepts `variables`, `taskVariables`, `webhookUrl`, and `runId`. For more about execution results and streaming, see [`ExecutionsResource`](/docs/sdk/js/resources/executions). To learn about task variables and runtime substitution, see [`Variables`](/docs/sdk/js/variables) and [`Actions`](/docs/sdk/js/actions).
  </Accordion>
</AccordionGroup>