# HTTP File Trigger (Upload and Download)

The **HTTP File Trigger** can be used to:

* **Upload:** Send large files (over 5 MB) to a pipeline via HTTP.
* **Download:** Download large files using the `GET` method.

Below, you’ll learn how to configure the trigger for both purposes.

## Parameters

Configure the trigger using the parameters below. Fields that support[ Double Braces expressions](https://docs.digibee.com/documentation/connectors-and-triggers/double-braces/overview) are marked in the **Supports DB** column.

<table data-full-width="true"><thead><tr><th>Parameter</th><th>Description</th><th>Type</th><th>Supports DB</th><th>Default</th></tr></thead><tbody><tr><td><strong>Methods</strong></td><td>Defines the methods accepted by the pipeline.</td><td>String</td><td>❌</td><td><code>POST</code>, <code>PUT</code>, <code>GET</code>, <code>PATCH</code> and <code>DELETE</code></td></tr><tr><td><strong>Response Headers</strong></td><td>Headers to be returned by the endpoint when the pipeline processing is complete. Special characters should not be used in keys, due to possible failures in proxies and gateways.</td><td>Key-value pairs</td><td>✅</td><td>N/A</td></tr><tr><td><strong>Add Cross-Origin Resource Sharing (CORS)</strong></td><td>If enabled, allows you to add CORS headers to be returned by the endpoint after the pipeline processing is complete. <br><br>Use a comma (<code>,</code>) to separate multiple values in a header, without adding spaces before or after the comma. Avoid using special characters in header keys, as they can cause failures in proxies or gateways.</td><td>Boolean</td><td>❌</td><td>False</td></tr><tr><td><strong>CORS Headers</strong></td><td><p>Defines CORS specifically for the pipeline and its constraints.</p><p>To configure it globally, instead of individually in each pipeline, see the <a href="https://app.gitbook.com/s/jvO5S91EQURCEhbZOuuZ/platform-administration/governance/policies/transformation/cors-http-header">CORS HTTP Header policy</a>.</p></td><td>Key-value pairs</td><td>❌</td><td>N/A</td></tr><tr><td><strong>Form Data Uploads</strong></td><td>Enables or disables the receipt of form data uploads (multipart form data).</td><td>Boolean</td><td>❌</td><td>True</td></tr><tr><td><strong>Body Uploads</strong></td><td>Enables or disables the receipt of body uploads.</td><td>Boolean</td><td>❌</td><td>True</td></tr><tr><td><strong>Body Upload Content Types</strong></td><td>Defines the content types allowed by the pipeline for body uploads.</td><td>String</td><td>❌</td><td><code>application/pdf</code>, <code>application/jpeg</code></td></tr><tr><td><strong>Response Content Types</strong></td><td>Defines the response content types allowed by the pipeline. For example, this setting determines the response format.</td><td>String</td><td>✅</td><td><code>text/xml</code>, <code>application/xml</code></td></tr><tr><td><strong>Maximum Timeout</strong></td><td><p>Maximum time (in milliseconds) that the pipeline takes to process information before returning a response. Limit: <code>900000</code>.</p><p>If processing exceeds this limit, the request is finished and returns a <code>500</code> status code without a response body.</p></td><td>Integer</td><td>❌</td><td><code>30000</code></td></tr><tr><td><strong>Maximum Request Size</strong></td><td>Defines the maximum size of the file in the upload request (in MB). Maximum: 100 MB.</td><td>Integer</td><td>❌</td><td><code>100</code></td></tr><tr><td><strong>External API</strong></td><td>If enabled, publishes the API to an external gateway.</td><td>Boolean</td><td>❌</td><td>True</td></tr><tr><td><strong>Internal API</strong></td><td>If enabled, publishes the API to an internal gateway.</td><td>Boolean</td><td>❌</td><td>False</td></tr><tr><td><strong>mTLS enabled API</strong></td><td><p>If enabled, the API is published to a dedicated mTLS gateway, with a different access host.</p><p>The pipeline can have both <strong>External API</strong> and <strong>Internal API</strong> options enabled. However, it’s recommended to keep them disabled.</p><p>This parameter doesn’t support <strong>API Key</strong>, <strong>JWT</strong>, or <strong>Basic Auth</strong>. To enable them in your realm, <a href="https://app.gitbook.com/s/boT4qPJIk6PZotrxlJWL/help-and-faq/support">contact Support</a>.</p></td><td>Boolean</td><td>❌</td><td>False</td></tr><tr><td><strong>API Key</strong></td><td>If enabled, the endpoint can only be accessed if an API key has been previously configured in the Digibee Integration Platform.</td><td>Boolean</td><td>❌</td><td>False</td></tr><tr><td><strong>Token JWT</strong></td><td>If enabled, the token for API consumption will be requested.</td><td>Boolean</td><td>❌</td><td>False</td></tr><tr><td><strong>Basic Auth</strong></td><td><p>If enabled, the endpoint can only be consumed if a Basic Auth setting is present in the request.</p><p>This setting can be registered beforehand through the <a href="https://app.gitbook.com/s/jvO5S91EQURCEhbZOuuZ/platform-administration/settings/api-keys-consumers">Consumers</a> page in the Digibee Integration Platform.</p></td><td>Boolean</td><td>❌</td><td>False</td></tr><tr><td><strong>Additional API Routes</strong></td><td>If enabled, allows you to add new routes.</td><td>Boolean</td><td>❌</td><td>False</td></tr><tr><td><strong>Remove Digibee Prefix from Route</strong></td><td><p>Removes the default Digibee route prefix <code>/pipeline/{realm}/v{n}</code>from the pipeline route. </p><p>Available only when <strong>External API</strong> and <strong>Internal API</strong> parameters are disabled, and <strong>mTLS enabled API</strong> and <strong>Additional API Routes</strong> parameters are enabled.</p></td><td>Boolean</td><td>❌</td><td>False</td></tr><tr><td><strong>Routes</strong></td><td>Defines custom routes.</td><td>String</td><td>❌</td><td>N/A</td></tr><tr><td><strong>Rate Limit</strong></td><td><p>If enabled, a rate-limiting will be applied to the API gateway.</p><p>Available if <strong>API Key</strong> or <strong>Basic Auth</strong> is enabled.</p></td><td>Boolean</td><td>❌</td><td>False</td></tr><tr><td><strong>Limit by</strong></td><td>Defines the entity to which the limits will be applied.</td><td>String</td><td>❌</td><td>API</td></tr><tr><td><strong>Aggregate by</strong></td><td>Defines the entity for aggregating the limits. Options: <a href="https://app.gitbook.com/s/jvO5S91EQURCEhbZOuuZ/platform-administration/settings/api-keys-consumers">Consumers and Credential</a> (<strong>API Key</strong>, <strong>Basic Auth</strong>).</td><td>String</td><td>❌</td><td>Consumer</td></tr><tr><td><strong>Options</strong></td><td>Defines the limit of requests allowed within a time interval.</td><td>Options for limit and interval</td><td>❌</td><td>N/A</td></tr><tr><td><strong>Interval</strong></td><td>Defines the time interval for the request limit. Options: <strong>second</strong>, <strong>minute</strong>, <strong>hour</strong>, <strong>day</strong>, and <strong>month</strong>.</td><td>String</td><td>❌</td><td>second</td></tr><tr><td><strong>Limit</strong></td><td>Defines the maximum number of requests users can make within the specified time interval.</td><td>Integer</td><td>❌</td><td>N/A</td></tr><tr><td><strong>Allow Redelivery Of Messages</strong></td><td>If enabled, allows messages to be redelivered in case of a Pipeline Engine failure.</td><td>Boolean</td><td>❌</td><td>False</td></tr></tbody></table>

## HTTP File Trigger in action

### Upload

#### Scenario 1: `POST` with `multipart/form-data` content type of file

Suppose you want to send a file larger than 5 MB. You can call a pipeline endpoint configured with an **HTTP File Trigger** using a `POST` request with the `multipart/form-data` content type. This allows the pipeline to process the file. Follow these steps:

1. Enable the **Form Data Uploads** option in the **HTTP File Trigger**.
2. Deploy the pipeline.
3. Create a [Consumer](https://app.gitbook.com/s/jvO5S91EQURCEhbZOuuZ/platform-administration/settings/api-keys-consumers) and configure it to have access to the pipeline.
4. Call the pipeline using the following cURL command:&#x20;

```sh
curl -d “@file_name” https://godigibee.io/pipeline/realm_name/v1/http-file-upload -v -H 'Content-Type: application/pdf' -H 'apikey: generated_token'
```

* **`file_name`:** Refers to a local file.
* **`realm_name`:** Refers to the realm where the pipeline is located.
* **`generated_token`**: Refers to the API Key generated by the recently created consumer.

The pipeline will receive an array `files[]` containing:

* `fileName`
* `param`
* `contentType`

This allows the file to be referenced and accessed from the pipeline:

```json
{
  "body": null,
  "form": {},
  "headers": {
  ...
  },
  "queryAndPath": {},
  "method": "POST",
  "contentType": "application/pdf",
  "path": "/pipeline/realm_name/v1/http-file-upload",
  "files": [
    {      
      "fileName": "55acdc09-c0fc-4f6a-b3ee-f4199076b0c4",
      "param": "body",
      "contentType": "application/pdf"    
    }  
  ]
}

```

#### Scenario 2: `POST` with `multipart/form-data` content type of multiple files

Suppose you have multiple files larger than 5 MB. You can call a pipeline endpoint configured with an **HTTP File Trigger** using a `POST` request with the `multipart/form-data` content type, allowing the pipeline to process these files. Follow these steps:

1. Enable the **Form Data Uploads** option in the **HTTP File Trigger**.
2. Deploy the pipeline.
3. Create a [Consumer](https://app.gitbook.com/s/jvO5S91EQURCEhbZOuuZ/platform-administration/settings/api-keys-consumers) and configure it to have access to the pipeline.
4. Call the pipeline using the following cURL command:

```sh
curl -F dgbfile1=@file_name1 -F dgbfile2=@file_name2 https://godigibee.io/pipeline/realm_name/v1/http-file-upload -v -H 'apikey: generated_token'
```

* **`file_name1`:** Refers to a local file.
* **`file_name2`:** Refers to a local file.
* **`realm_name`:** Refers to the realm where the pipeline is located.
* **`generated_token`**: Refers to the API Key generated by the recently created consumer.

The pipeline will receive an array `files[]` containing:

* `fileName`
* `originalFileName`
* `param`
* `charset`
* `contentLength`
* `contentType`

This allows the files to be referenced and accessed from the pipeline:

```json
{
  "body": "",
  "form": {},
  "headers": {
    ...
  },
  "queryAndPath": {},
  "method": "POST",
  "contentType": "multipart/form-data; boundary=------------------------b3c985803b952f2c",
  "path": "/pipeline/realm_name/v1/http-file-upload",
  "files": [
    {
      "fileName": "96f3ecb2-1c72-4980-9f01-6f44cafc719f",
      "originalFileName": "file1",
      "param": "dgbfile1",
      "contentType": "application/octet-stream",
      "charset": "UTF-8",
      "contentLength": 5242880
    },
    {
      "fileName": "58fb844f-a1d1-4788-b9b4-30df4b69165e",
      "originalFileName": "file2",
      "param": "dgbfile2",
      "contentType": "application/octet-stream",
      "charset": "UTF-8",
      "contentLength": 5242880
    }
  ]
}

```

#### Scenario 3: `POST` with any content type and body with more than 5MB

Suppose you have multiple files larger than 5 MB. You can call a pipeline endpoint configured with an **HTTP Trigger** using a **`POST`** request with any content type, allowing the pipeline to process these files. Follow these steps:

1. Enable the **Body Uploads** option in the **HTTP File Trigger**.
2. Deploy the pipeline.
3. Create a [Consumer](https://app.gitbook.com/s/jvO5S91EQURCEhbZOuuZ/platform-administration/settings/api-keys-consumers) and configure it to have access to the pipeline.
4. Call the pipeline using the following cURL command:

```sh
curl -d '@file_name1' https://godigibee.io/pipeline/realm_name/v1/http-file-upload -v -H 'apikey: generated_token'
```

The pipeline will receive an array `files[]` containing:

* `fileName`
* `param`
* `charset`
* `contentType`

This allows the files to be referenced and accessed from the pipeline:

```json
{
  "body": null,
  "form": {},
  "headers": {
    ...
  },
  "queryAndPath": {},
  "method": "POST",
  "contentType": "application/pdf",
  "path": "/pipeline/realm_name/v1/http-file-upload",
  "files": [
    {
      "fileName": "55acdc09-c0fc-4f6a-b3ee-f4199076b0c4",
      "param": "body",
      "contentType": "application/pdf"
    }
  ]
}

```

### Download

#### Scenario: `GET` with any content type

Suppose you have a file larger than 5 MB. You can call a pipeline endpoint configured with an **HTTP Trigger** using a `GET` request with any content type. The pipeline receives and processes the file, returning it according to the output content type and its original content. Follow these steps:

1. Include the `GET` method and specify the **Response Content Types** in the **HTTP File Trigger**.
2. Add a [File Reader](https://docs.digibee.com/documentation/connectors-and-triggers/connectors/files/file-reader) connector to the pipeline to search the file to be processed. For example, you can configure a [WGet](https://docs.digibee.com/documentation/connectors-and-triggers/connectors/web-protocols/wget) connector to retrieve a file of a URL sent to the endpoint during a call.
3. Insert a [JSON Generator](https://docs.digibee.com/documentation/connectors-and-triggers/connectors/tools/json-generator) as the last step in your pipeline to produce a JSON in the following format:

```
{ 
    "file": "file-download.pdf",
    "Content-Type": "application/pdf"
}
```

4. Deploy the pipeline.
5. Create a [Consumer](https://app.gitbook.com/s/jvO5S91EQURCEhbZOuuZ/platform-administration/settings/api-keys-consumers) and configure it to have access to the pipeline.
6. Call the pipeline using the following cURL command:

```json
curl https://godigibee.io/pipeline/realm_name/v1/pipeline_name -v -H 'Content-Type: application/pdf' -H 'apikey: generated_token' -H 'urlDownload: http://url/path'
```

* **`realm_name`:** Refers to the realm where the pipeline is located.
* **`generated_token`:** Refers to the API Key generated by the recently created consumer.
* **`urlDownload`:** Parameter sent to the **WGet** connector to populate the URL field. The attribute is optional but allows a more flexible approach using [Double Braces](https://docs.digibee.com/documentation/connectors-and-triggers/double-braces/overview). It works seamlessly if you define the **path** directly within the **WGet** connector.

## HTTP File Trigger response

### Upload response

To define the pipeline response format, add a transformer connector, such as the [**Transformer (JOLT)**](https://docs.digibee.com/documentation/connectors-and-triggers/connectors/tools/jolt-v2), as the final step in the pipeline and configure the desired response.

```json
{  
    "body": "<xml>Output 1</xml>",  
    "code": 200,  
    "Content-Type": "application/xml"
}
```

#### Response limitations for payloads above 5 MB

For payloads larger than 5 MB, it’s recommended that the pipeline returns a **file** instead of a payload. Use the [**File Writer**](https://docs.digibee.com/documentation/connectors-and-triggers/connectors/files/file-writer) connector to generate the file, and reference it in the pipeline response using the `file` property rather than `body`:

```json
{
"file": {{ message.fileName }},
"code": 200,
"Content-Type": "application/json"
}
```

### Download response

To define the pipeline response format, add a transformer connector, such as the [**Transformer (JOLT)**](https://docs.digibee.com/documentation/connectors-and-triggers/connectors/tools/jolt-v2), as the final step in the pipeline and configure the desired response:

```json
{  
    "file": "file-download.pdf",  
    "code": 200,  
    "Content-Type": "application/pdf"
}
```

The HTTP File Trigger can also respond with non-file bodies, similar to the [HTTP Trigger.](https://docs.digibee.com/documentation/connectors-and-triggers/triggers/web-protocols/http) To do so, the last step of the pipeline must have this structure:

```json
{ 
    "body": "information that will be written in the endpoint output", 
    "Content-Type": "body content type", 
    "code": <a HTTP return code>
}
```

### Response properties

The same response structure applies to both **upload** and **download** scenarios.

* **`code`:** HTTP status code to be returned by the endpoint after a request is finished.
* **`body`:** Response message body. This field must be a **string**. If you need to send JSON data, use the [TOSTRING function](https://docs.digibee.com/documentation/connectors-and-triggers/double-braces/double-braces-functions#string).
* **`content-type`:** Content type of the response body. All content types are supported, but they must be declared in the **Response Content Types** field.

## Best practices

### Global configuration for authentication

A global configuration parameter enforces authentication for all pipelines using the **HTTP File Trigger**. When enabled, pipelines can only be published if at least one authentication method (**API Key** or **Basic Auth**) is configured.

### Remove Digibee Prefix from Route

When removing the default prefix and defining the route through the **Additional API Routes** parameter, make sure not to use a route already assigned to another pipeline. If multiple major versions of the same pipeline exist, remember that route versioning must be managed manually, as there is no automatic versioning path (for example: `/pipeline/realm/v1/`).

### Rate Limit

Enable the **Rate Limit** parameter to restrict the number of API requests within a specific time interval. Use the following configuration:

* **Limit by:** API
* **Aggregate by:** Credential (API Key, Basic Auth)
* **Options:**
  * Interval: second → Limit: 100
  * Interval: minute → Limit: 1000
  * Interval: hour → Limit: 5000

If the API includes additional paths, the limit applies to all of them collectively. To activate Rate Limit, the API must use an **API key** or **Basic Auth**, allowing aggregation by either groups of credentials (**Consumer** option) or individual credentials (**Credential** option).

{% hint style="info" %}
If multiple interval parameters have the same value, only one is considered. The **Limit** parameter must always be greater than zero. Incorrect or incomplete rate limiting settings are ignored, and a warning log is generated. You can view this log on the [Pipeline Logs](https://app.gitbook.com/s/jvO5S91EQURCEhbZOuuZ/development-cycle/dashboards/pipeline-logs) page.
{% endhint %}