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

# n8n

> Production-ready document data extraction for n8n.

export const Grid2 = ({children}) => {
  return <div className="grid grid-cols-2 content-center gap-2">
    {children}
  </div>;
};

export const Image = ({style, ...rest}) => {
  let sizeStyle = {
    width: '75%'
  };
  return <Frame><img {...rest} style={{
    ...style,
    ...sizeStyle
  }} /></Frame>;
};

## Before you begin

* An n8n instance (Cloud or self‑hosted) with permission to create workflows
* A Cradl AI agent with at least one test document

## Quickstart

Follow these steps to set up the Cradl AI node in n8n.

<Steps>
  <Step title="Add the Cradl AI node to your workflow">
    Add a new node to your n8n workflow and search for "Cradl AI".

    <Image src="/images/n8n-workflow-simple.jpg" alt="n8n Webhook node overview" />
  </Step>

  <Step title="Set up your credentials">
    Open the Cradl AI node in n8n and click **Set up credential**.
    In your Cradl AI agent, add a new trigger and choose **n8n**. Copy the *Client ID* and *Client Secret* from the n8n trigger panel, then paste them into n8n.

    <Grid2>
      <Image src="/images/n8n-cradl-trigger-panel.png" alt="n8n Cradl AI trigger panel" />

      <Image src="/images/n8n-cradl-credentials.jpg" alt="Cradl AI credentials in n8n" />
    </Grid2>

    You can also add an n8n export to your Cradl AI agent at this stage. This is optional. If you skip it, the export is created automatically the first time you run the n8n workflow.
  </Step>

  <Step title="Configure the Cradl AI node">
    Once your credentials are set up, your Cradl AI agents should appear under **Agent Name or ID**. Select the agent you want to use.

    In the **Document Binary Data** field, specify the file you want Cradl AI to read. This is typically a binary PDF or image file. Enter the name of the binary variable in this field, as shown below:

    <Image src="/images/n8n-cradl-setup-node.png" alt="Cradl AI agent setup" />
  </Step>
</Steps>

## Triggering n8n workflows from Cradl AI

Use the Cradl AI trigger to start an n8n workflow when results are available in Cradl AI. This is also useful for asynchronous workflows, so you do not need to wait for results in the middle of a workflow.

<Image src="/images/n8n-cradl-trigger.png" alt="n8n Cradl AI trigger" />

Follow the same steps as in [Quickstart](#quickstart) to configure the trigger node.

## Response format

The n8n node returns extracted fields and context, such as `context.documentId`. See [Webhook → Payload format](./webhook) for a full example.

## Best practices

* Keep node names stable (e.g., `Webhook`, `HTTP Request`) if you use expressions that reference them
* Return a fast **2xx** response from the Webhook node; perform longer work asynchronously downstream
* Store secrets using n8n Credentials instead of hardcoding values

## Troubleshooting

* No requests arriving in n8n: verify that the workflow is active and that the node is configured correctly
* 401 from token or API calls: check `client_id`/`client_secret`, `grant_type=client_credentials`, and `audience=https://api.cradl.ai/v1`
* Expression resolves to `undefined`: confirm node names match your expressions and inspect the incoming JSON with the Expression Editor to validate the path (e.g., `body.context.documentId`)
* Cannot download file: include the `Authorization: Bearer <ACCESS_TOKEN>` header when requesting `fileUrl`