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

# n8n

> Automate your Arca workflows using the official Arca node in n8n.

The Arca n8n integration lets you build automated workflows that read from and write to your Arca workspaces. You can create tasks when events happen in other tools, update task statuses based on external triggers, post comments automatically, and much more. The integration ships as two nodes: an action node for performing operations and a trigger node for listening to events. Arca is a verified node on n8n and is available directly in the node search, no manual installation required.

## Requirements

You need a self-hosted or cloud n8n instance and an Arca API key. Any workspace member can generate an API key regardless of their role.

***

## Get your API key

<Steps>
  <Step title="Open Settings">
    In Arca, click your avatar in the bottom-left sidebar and select
    **Settings**.
  </Step>

  <Step title="Go to API Keys">
    Select the **API Keys** section from the settings menu.
  </Step>

  <Step title="Generate a key">
    Click **Add new key**. Copy the key and store it somewhere safe. Arca only
    shows it once.
  </Step>
</Steps>

***

## Add the node

<Steps>
  <Step title="Search for Arca in n8n">
    In your n8n workflow, click **+** to add a node and search for **Arca**. The
    node is verified by n8n and appears directly in the search results, no
    manual installation needed.
  </Step>

  <Step title="Add credentials">
    When prompted for credentials, select the **Arca API** credential, paste
    your API key, and save. n8n verifies the key against your account before
    saving.
  </Step>
</Steps>

***

## Arca node (actions)

The **Arca** node lets you perform operations on your workspace from any workflow step. Select a **Resource** and then an **Operation** to configure what the node does.

### User

| Operation        | What it does                                             |
| ---------------- | -------------------------------------------------------- |
| Get Current User | Returns the profile of the account that owns the API key |

### Workspace

| Operation       | What it does                                     |
| --------------- | ------------------------------------------------ |
| List Workspaces | Returns all workspaces accessible to the API key |
| Get Workspace   | Returns the details of a specific workspace      |
| List Members    | Returns all members of a workspace               |

### Folder

| Operation     | What it does                                                |
| ------------- | ----------------------------------------------------------- |
| List Folders  | Returns all folders in a workspace                          |
| Create Folder | Creates a new folder with an optional icon and color        |
| Update Folder | Renames or changes the icon and color of an existing folder |
| Delete Folder | Permanently deletes a folder                                |

### List

| Operation   | What it does                                                |
| ----------- | ----------------------------------------------------------- |
| List Lists  | Returns all lists in a workspace                            |
| Create List | Creates a new list with an optional folder, icon, and color |
| Update List | Renames, moves, or reskins an existing list                 |
| Delete List | Permanently deletes a list                                  |

### Task

| Operation   | What it does                                                                                  |
| ----------- | --------------------------------------------------------------------------------------------- |
| List Tasks  | Returns tasks in a workspace, optionally filtered by list (paginated, 50 per page by default) |
| Get Task    | Returns a single task by its ID                                                               |
| Create Task | Creates a task with title, description, priority, status, due date, and start date            |
| Update Task | Edits any field on an existing task, including moving it to another list                      |
| Delete Task | Permanently deletes a task                                                                    |

**Priority values:** `urgent` `high` `medium` `low` `none`

### Status

| Operation     | What it does                                                               |
| ------------- | -------------------------------------------------------------------------- |
| List Statuses | Returns all custom statuses in a workspace                                 |
| Create Status | Creates a new status with a category, icon, and color                      |
| Update Status | Edits an existing status                                                   |
| Delete Status | Deletes a status, with an option to reassign tasks to another status first |

**Category values:** `pending` `in_progress` `completed` `cancelled`

### Label

| Operation    | What it does                               |
| ------------ | ------------------------------------------ |
| List Labels  | Returns all labels in a workspace          |
| Create Label | Creates a new label with an optional color |
| Update Label | Renames or recolors an existing label      |
| Delete Label | Permanently deletes a label                |

### Comment

| Operation      | What it does                   |
| -------------- | ------------------------------ |
| List Comments  | Returns all comments on a task |
| Create Comment | Posts a new comment on a task  |

***

## Arca Trigger node

The **Arca Trigger** node starts a workflow whenever Arca sends a webhook event. It outputs the full event payload so downstream nodes can act on it.

### Setup

<Steps>
  <Step title="Add the trigger node">
    Create a new workflow in n8n and add the **Arca Trigger** node as the
    starting node.
  </Step>

  <Step title="Copy the webhook URL">
    Click the node to open its settings. Copy the webhook URL shown in the panel
    (the production URL).
  </Step>

  <Step title="Register the webhook in Arca">
    In Arca, go to **Settings → Webhooks**, create a new webhook, and paste the
    n8n URL as the endpoint. Select the events you want to receive.
  </Step>

  <Step title="Activate the workflow">
    Back in n8n, publish the workflow. The trigger is now live and will start
    the workflow whenever a matching Arca event fires.
  </Step>
</Steps>

### Supported events

The trigger accepts any event belonging to these resource types:

| Prefix     | Covers                                                   |
| ---------- | -------------------------------------------------------- |
| `task.*`   | Task created, updated, deleted, status changed, and more |
| `folder.*` | Folder created, updated, deleted                         |
| `list.*`   | List created, updated, deleted                           |

The trigger passes all events through. To react to a specific event type, add an **IF** or **Switch** node after the trigger and check the `{{ $json.event }}` value (for example `task.created`).

### Output data

Each trigger execution outputs an object with the following fields:

| Field       | Description                                                   |
| ----------- | ------------------------------------------------------------- |
| `event`     | The event type string, for example `task.created`             |
| `timestamp` | ISO 8601 timestamp of when the event occurred                 |
| `workspace` | The workspace where the event happened                        |
| `user`      | The Arca user who triggered the event                         |
| `before`    | The resource state before the change (null for create events) |
| `after`     | The resource state after the change (null for delete events)  |

<Tip>
  For more information about the event structure and available fields, see the
  [Webhooks seciton](/administration/webhooks).
</Tip>

### Optional auth token

To verify that incoming webhook calls genuinely come from Arca, enable the **Auth Token** option in the Arca Trigger node settings and set a secret string. Then, in Arca's webhook configuration, enter the same string in the **Auth token** field. The trigger rejects any request that does not present the correct token.

***

## Use as an AI agent tool

The Arca node supports being used as a tool inside n8n AI agent workflows. Add it as a tool to any AI Agent node and the agent can query and update your Arca workspace using natural language instructions.

***

## Limitations

Task listing returns 50 results per page by default. To retrieve more tasks, increment the **Page** parameter and loop until the result count drops below the page size.

Comment operations are limited to listing and creating. Editing or deleting existing comments is not supported through n8n.

Workspace operations are read-only. Creating or deleting workspaces must be done directly in Arca.

There is no "get folder by ID" or "get list by ID" operation. Use the list operations and filter the results in your workflow.