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

# n8n | Workflow Automation with Orq.ai

> Use the Orq.ai community nodes in n8n to run agents, invoke deployments, and search knowledge bases inside your automation workflows.

## Installation

Install the `@orq-ai/n8n-nodes-orq` package through the n8n Community Nodes manager:

1. Open n8n and go to **Settings**
2. Select **Community Nodes**
3. Click **Install a community node**
4. Enter `@orq-ai/n8n-nodes-orq` and click **Install**

You may need to refresh your browser or restart n8n Desktop after installation.

## Credentials

1. In n8n, go to **Credentials** and click **New**
2. Search for **Orq API**
3. Paste your API key from [Workspace Settings](https://my.orq.ai/settings/api-keys)
4. Name the credential and save

## Quick Start

1. Add a **Manual Trigger** node
2. Add an **Orq Deployment** node and connect it
3. Select a deployment, add a message with role `user` and your prompt text
4. Click **Execute Workflow**

<img src="https://mintcdn.com/orqai/5Ze5hYDNyQzA0f2f/images/docs/091ca29b74f1ba215cd6ebeaec44439ca16f8aa4232d02dce7adee3cac2874e4-Screenshot_2025-07-29_at_17.47.02.png?fit=max&auto=format&n=5Ze5hYDNyQzA0f2f&q=85&s=36b7d4e9381d840859ce1872077e3517" alt="n8n workflow with Manual Trigger connected to Orq Deployment node" width="2812" height="1498" data-path="images/docs/091ca29b74f1ba215cd6ebeaec44439ca16f8aa4232d02dce7adee3cac2874e4-Screenshot_2025-07-29_at_17.47.02.png" />

## Nodes Reference

Three nodes are available:

* **Orq Agent**: Run an [Agent](/docs/agents/build) for multi-step tasks with tools and autonomous reasoning.
* **Orq Deployment**: Invoke a [Deployment](/docs/deployments/overview) for direct, single LLM calls with prompt templates.
* **Orq Knowledge Base Search**: Search an **Orq.ai** [Knowledge Base](/docs/knowledge/overview) for RAG and context retrieval.

***

### Orq Agent

Run an **Orq.ai** [Agent](/docs/agents/build) for complex, multi-step tasks. The node sends a message to the agent, waits for it to complete (including any tool calls), and returns the final response.

| Parameter             | Type     | Description                                                                             |
| --------------------- | -------- | --------------------------------------------------------------------------------------- |
| **Agent**             | Dropdown | Select from available agents in your workspace                                          |
| **Message**           | Text     | The message to send to the agent                                                        |
| **Timeout (seconds)** | Number   | HTTP timeout in seconds. Defaults to 600 (10 min) to match server-side execution limits |

#### Additional Fields

| Field                    | Description                                                                                                                                             |
| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Previous Response ID** | Continue from a prior response. Mutually exclusive with Conversation ID                                                                                 |
| **Conversation ID**      | Thread this call into an existing long-lived conversation (`conv_...`). Mutually exclusive with Previous Response ID                                    |
| **Memory Entity ID**     | Attach a persistent memory entity so the agent can recall facts across calls                                                                            |
| **Store Response**       | Whether Orq persists this response server-side (default on). When off, the response cannot be referenced as a Previous Response ID by a downstream node |
| **Variables**            | Template variables passed to the agent's prompt. Each row has Name, Value, and a Secret toggle to redact the value from logs                            |
| **Metadata**             | Key-value tags attached to this call, queryable in the **Orq.ai** dashboard. Max 16 pairs                                                               |

#### Output

<Expandable title="fields">
  <ResponseField name="responseId" type="string">
    Unique identifier for this response. Pass as **Previous Response ID** in a downstream node to continue the conversation.
  </ResponseField>

  <ResponseField name="agentKey" type="string">
    The agent that was invoked.
  </ResponseField>

  <ResponseField name="status" type="string">
    Final status: `completed` or `incomplete`.
  </ResponseField>

  <ResponseField name="success" type="boolean">
    `true` when the response completed successfully.
  </ResponseField>

  <ResponseField name="response" type="string">
    The agent's response text. Use `{{ $json.response }}` in downstream nodes.
  </ResponseField>

  <ResponseField name="raw" type="object">
    Full response body.
  </ResponseField>

  <ResponseField name="usage" type="object">
    Token counts, when present.
  </ResponseField>

  <ResponseField name="incomplete" type="boolean">
    `true` when status is `incomplete`.
  </ResponseField>

  <ResponseField name="incompleteReason" type="string">
    Reason for an incomplete status, when present.
  </ResponseField>
</Expandable>

<Note>
  The node branches on the agent's final status: `completed` routes to the success branch, `incomplete` returns a partial response with `incomplete: true`, and `failed` throws with the server error message.
</Note>

***

### Orq Deployment

Invoke an **Orq.ai** [Deployment](/docs/deployments/overview) with messages, routing context, and variable inputs.

| Parameter          | Type            | Description                                                                                                           |
| ------------------ | --------------- | --------------------------------------------------------------------------------------------------------------------- |
| **Deployment Key** | Dropdown        | Select from available deployments in your workspace                                                                   |
| **Context**        | Key-value pairs | Routing context for the deployment (e.g. `environment: production`). [Learn more](/docs/deployments/creating#routing) |
| **Inputs**         | Key-value pairs | Values for `{{variable}}` placeholders defined in the deployment prompt. Add one entry per variable                   |
| **Messages**       | Collection      | Conversation messages to pass to the deployment                                                                       |

#### Messages

Each message has a **Role** (User, System, or Assistant). System and Assistant messages take plain text. User messages support two content types:

| Content Type | Fields                                                                 |
| ------------ | ---------------------------------------------------------------------- |
| **Text**     | Message text                                                           |
| **Image**    | Image Source (URL or Base64 Data URI) and an optional text description |

<Note>
  Some models require text alongside images. Check your model's documentation if image-only messages return errors.
</Note>

#### Output

<Expandable title="fields">
  <ResponseField name="id" type="string">
    Deployment invocation ID.
  </ResponseField>

  <ResponseField name="model" type="string">
    Model used for the response.
  </ResponseField>

  <ResponseField name="provider" type="string">
    Provider that served the request.
  </ResponseField>

  <ResponseField name="choices" type="array">
    Response choices. Use `{{ $json.choices[0].message.content }}` in downstream nodes to get the text response.
  </ResponseField>

  <ResponseField name="providerResponse" type="object">
    Raw response from the upstream provider.
  </ResponseField>

  <ResponseField name="finalized" type="boolean">
    Whether the response is complete.
  </ResponseField>
</Expandable>

***

### Orq Knowledge Base Search

Run semantic, keyword, or hybrid search over an **Orq.ai** [Knowledge Base](/docs/proxy/knowledge-bases).

| Parameter                | Type     | Description                                                                                                              |
| ------------------------ | -------- | ------------------------------------------------------------------------------------------------------------------------ |
| **Knowledge Base**       | Dropdown | Select from available knowledge bases in your workspace                                                                  |
| **Query**                | Text     | The search query                                                                                                         |
| **Metadata Filter Type** | Options  | `None`, `AND` (all conditions must match), `OR` (any condition must match), or `Custom JSON` (advanced recursive filter) |

When **AND** or **OR** is selected, add one or more conditions. Each condition takes:

| Field        | Description                                                                  |
| ------------ | ---------------------------------------------------------------------------- |
| **Field**    | The metadata field to filter on                                              |
| **Operator** | `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`                            |
| **Value**    | The value to compare against. For `in` and `nin`, use comma-separated values |

When **Custom JSON** is selected, provide a recursive filter structure directly:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "$and": [
    { "field1": { "eq": "value1" } },
    { "$or": [
      { "field2": { "gt": 100 } },
      { "field3": { "in": ["a", "b"] } }
    ]}
  ]
}
```

#### Additional Options

| Option          | Description                                                                   |
| --------------- | ----------------------------------------------------------------------------- |
| **Chunk Limit** | Number of results to return (1 to 20). Defaults to the knowledge base setting |
| **Threshold**   | Minimum similarity score (0 to 1). Defaults to the knowledge base setting     |
| **Search Type** | `Vector Search`, `Keyword Search`, or `Hybrid Search` (default)               |

#### Output

<ResponseField name="matches" type="array">
  Array of matching chunks. Use `{{ $json.matches[0].text }}` in downstream nodes to get the top result.

  <Expandable title="matches[]">
    <ResponseField name="id" type="string">
      Chunk ID.
    </ResponseField>

    <ResponseField name="text" type="string">
      The matched chunk text.
    </ResponseField>

    <ResponseField name="metadata" type="object">
      Any metadata attached to the chunk.
    </ResponseField>

    <ResponseField name="scores" type="object">
      <Expandable title="properties">
        <ResponseField name="searchScore" type="number">
          Similarity score for the match.
        </ResponseField>

        <ResponseField name="rerankScore" type="number">
          Rerank score, if reranking is enabled.
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>