Request

yaml

type: "io.kestra.plugin.core.http.Request"

Make an HTTP API request to a specified URL and store the response as output.

This task makes an API call to a specified URL of an HTTP server and stores the response as output. By default, the maximum length of the response is limited to 10MB, but it can be increased to at most 2GB by using the options.maxContentLength property. Note that the response is added as output to the task. If you need to process large API payloads, we recommend using the Download task instead.

Examples

Execute a Kestra flow via an HTTP POST request authenticated with basic auth. To pass a user input to the API call, we use the formData property. When using form data, make sure to set the contentType property to multipart/form-data.

yaml

id: api_call
namespace: company.team

tasks:
  - id: basic_auth_api
    type: io.kestra.plugin.core.http.Request
    uri: http://host.docker.internal:8080/api/v1/executions/dev/inputs_demo
    options:
      basicAuthUser: admin
      basicAuthPassword: admin
    method: POST
    contentType: multipart/form-data
    formData:
      user: John Doe

Execute a Kestra flow via an HTTP request authenticated with a Bearer auth token / JWT token.

yaml

id: jwt_auth_call
namespace: company.team

tasks:
  - id: auth_token_api
    type: io.kestra.plugin.core.http.Request
    uri: https://dummyjson.com/user/me
    method: GET
    headers:
      Authorization: 'Bearer <TOKEN>'

Execute a Kestra flow via an HTTP request authenticated with API key passed in the header.

yaml

id: api_key_auth_call
namespace: company.team

tasks:
  - id: api_key_auth
    type: io.kestra.plugin.core.http.Request
    uri: https://dummyjson.com/user/me
    method: GET
    headers:
      X-API-KEY: abcde12345

Execute a Kestra flow via an HTTP request authenticated with API key passed in the query parameters.

yaml

id: api_key_auth_call
namespace: company.team

tasks:
  - id: api_key_in_query_params
    type: io.kestra.plugin.core.http.Request
    uri: "https://dummyjson.com/user/me?api_key={{ secret('API_KEY') }}"
    method: GET

Make an HTTP GET request with a timeout. The timeout property specifies the maximum time allowed for the entire task to run, while the options.connectTimeout, options.readTimeout, options.connectionPoolIdleTimeout, and options.readIdleTimeout properties specify the time allowed for establishing a connection, reading data from the server, keeping an idle connection in the client's connection pool, and keeping a read connection idle before closing it, respectively.

yaml

id: timeout
namespace: company.team

tasks:
  - id: http
    type: io.kestra.plugin.core.http.Request
    uri: https://reqres.in/api/long-request
    timeout: PT10M # no default
    method: GET
    options:
      connectTimeout: PT1M # no default
      readTimeout: PT30S # 10 seconds by default
      connectionPoolIdleTimeout: PT10S # 0 seconds by default
      readIdleTimeout: PT10M # 300 seconds by default

Make a HTTP request and process its output. Given that we send a JSON payload in the request body, we need to use application/json as content type.

yaml

id: http_post_request_example
namespace: company.team

inputs:
  - id: payload
    type: JSON
    defaults: |
      {"title": "Kestra Pen"}

tasks:
  - id: send_data
    type: io.kestra.plugin.core.http.Request
    uri: https://dummyjson.com/products/add
    method: POST
    contentType: application/json
    body: "{{ inputs.payload }}"

  - id: print_status
    type: io.kestra.plugin.core.log.Log
    message: '{{ outputs.send_data.body }}'

Send an HTTP POST request to a webserver.

yaml

id: http_post_request_example
namespace: company.team

tasks:
  - id: send_data
    type: io.kestra.plugin.core.http.Request
    uri: "https://server.com/login"
    headers:
      user-agent: "kestra-io"
    method: "POST"
    formData:
      user: "user"
      password: "pass"

Send a multipart HTTP POST request to a webserver.

yaml

id: http_post_multipart_example
namespace: company.team

inputs:
  - id: file
    type: FILE

tasks:
  - id: send_data
    type: io.kestra.plugin.core.http.Request
    uri: "https://server.com/upload"
    headers:
      user-agent: "kestra-io"
    method: "POST"
    contentType: "multipart/form-data"
    formData:
      user: "{{ inputs.file }}"

Send a multipart HTTP POST request to a webserver and set a custom file name.

yaml

id: http_post_multipart_example
namespace: company.team

inputs:
  - id: file
    type: FILE

tasks:
  - id: send_data
    type: io.kestra.plugin.core.http.Request
    uri: "https://server.com/upload"
    headers:
      user-agent: "kestra-io"
    method: "POST"
    contentType: "multipart/form-data"
    formData:
      user:
        name: "my-file.txt"
        content: "{{ inputs.file }}"

Upload an image using HTTP POST request to a webserver.

yaml

id: http_upload_image
namespace: company.team

tasks:
  - id: s3_download
    type: io.kestra.plugin.aws.s3.Download
    accessKeyId: "{{ secret('AWS_ACCESS_KEY_ID')}}"
    secretKeyId: "{{ secret('AWS_SECRET_KEY_ID')}}"
    region: "eu-central-1"
    bucket: "my-bucket"
    key: "path/to/file/my_image.jpeg"

  - id: send_data
    type: io.kestra.plugin.core.http.Request
    uri: "https://server.com/upload"
    headers:
      user-agent: "kestra-io"
    method: "POST"
    contentType: "image/jpeg"
    formData:
      user:
        file: "my-image.jpeg"
        url: "{{ outputs.s3_download.uri }}"
        metadata:
          description: "my favorite image"

Upload a CSV file using HTTP POST request to a webserver.

yaml

id: http_csv_file_upload
namespace: company.team

tasks:
  - id: http_download
    type: io.kestra.plugin.core.http.Download
    uri: https://huggingface.co/datasets/kestra/datasets/raw/main/csv/orders.csv

  - id: upload
    type: io.kestra.plugin.core.http.Request
    uri: "https://server.com/upload"
    headers:
      user-agent: "kestra-io"
    method: "POST"
    contentType: "multipart/form-data"
    formData:
      url: "{{ outputs.http_download.uri }}"

Properties

`uri`

Type: string
Dynamic: ✔️
Required: ✔️

The fully-qualified URI that points to the HTTP destination

`allowFailed`

Type: boolean
Dynamic: ❓
Required: ❌
Default: false

If true, allow a failed response code (response code >= 400)

`body`

Type: string
Dynamic: ✔️
Required: ❌

The full body as a string

`contentType`

Type: string
Dynamic: ✔️
Required: ❌

The request content type

`encryptBody`

Type: boolean
Dynamic: ❓
Required: ❌
Default: false

If true, the HTTP response body will be automatically encrypted and decrypted in the outputs, provided that encryption is configured in your Kestra configuration.

If this property is set to true, this task will output the request body using the encryptedBody output property; otherwise, the request body will be stored in the body output property.

`formData`

Type: object
Dynamic: ✔️
Required: ❌

The form data to be send

`headers`

Type: object
SubType: string
Dynamic: ✔️
Required: ❌

The headers to pass to the request

`method`

Type: string
Dynamic: ❌
Required: ❌
Default: GET
Possible Values:
- OPTIONS
- GET
- HEAD
- POST
- PUT
- DELETE
- TRACE
- CONNECT
- PATCH
- CUSTOM

The HTTP method to use

`options`

Type: HttpInterface-RequestOptions
Dynamic: ❓
Required: ❌

The HTTP request options

`sslOptions`

Type: HttpInterface-SslOptions
Dynamic: ❓
Required: ❌

The SSL request options

Outputs

`body`

Type: object
Required: ❌

The body of the response.

Kestra will by default store the task output using this property. However, if the encryptBody property is set to true, kestra will instead encrypt the output and store it using the encryptedBody output property.

`code`

Type: integer
Required: ❌

The status code of the response.

`encryptedBody`

Type: EncryptedString
Required: ❌

The encrypted body of the response.

If the encryptBody property is set to true, kestra will automatically encrypt the output before storing it, and decrypt it when the output is retrieved in a downstream task.

`formData`

Type: object
Required: ❌

The form data to be sent in the request body

When sending a file, you can pass a list of maps (i.e. a list of key-value pairs) with a key 'name' and value of the filename, as well as 'content' key with the file's content as value (e.g. passed from flow inputs or outputs from another task).

`headers`

Type: object
SubType: array
Required: ❌

The headers of the response.

`uri`

Type: string
Required: ❌
Format: uri

The URL of the current request.

`basicAuthPassword`

Type: string
Dynamic: ✔️
Required: ❌

The password for HTTP basic authentication.

`basicAuthUser`

Type: string
Dynamic: ✔️
Required: ❌

The username for HTTP basic authentication.

`connectTimeout`

Type: string
Dynamic: ❌
Required: ❌
Format: duration

The time allowed to establish a connection to the server before failing.

`connectionPoolIdleTimeout`

Type: string
Dynamic: ❌
Required: ❌
Default: 0.0
Format: duration

The time an idle connection can remain in the client's connection pool before being closed.

`defaultCharset`

Type: Charset
Dynamic: ❌
Required: ❌
Default: UTF-8

The default charset for the request.

`followRedirects`

Type: boolean
Dynamic: ❌
Required: ❌
Default: true

Whether redirects should be followed automatically.

`logLevel`

Type: string
Dynamic: ❌
Required: ❌
Possible Values:
- ALL
- TRACE
- DEBUG
- INFO
- WARN
- ERROR
- OFF
- NOT_SPECIFIED

The log level for the HTTP client.

`maxContentLength`

Type: integer
Dynamic: ❌
Required: ❌
Default: 10485760

The maximum content length of the response.

`proxyAddress`

Type: string
Dynamic: ✔️
Required: ❌

The address of the proxy server.

`proxyPassword`

Type: string
Dynamic: ✔️
Required: ❌

The password for proxy authentication.

`proxyPort`

Type: integer
Dynamic: ❌
Required: ❌

The port of the proxy server.

`proxyType`

Type: string
Dynamic: ❌
Required: ❌
Default: DIRECT
Possible Values:
- DIRECT
- HTTP
- SOCKS

The type of proxy to use.

`proxyUsername`

Type: string
Dynamic: ✔️
Required: ❌

The username for proxy authentication.

`readIdleTimeout`

Type: string
Dynamic: ❌
Required: ❌
Default: 300.000000000
Format: duration

The time allowed for a read connection to remain idle before closing it.

`readTimeout`

Type: string
Dynamic: ❌
Required: ❌
Default: 10.000000000
Format: duration

The maximum time allowed for reading data from the server before failing.

`io.kestra.core.models.tasks.common.EncryptedString`

Properties

`type`

Type: string
Dynamic: ❓
Required: ❓

`value`

Type: string
Dynamic: ❓
Required: ❓

`io.kestra.plugin.core.http.HttpInterface-SslOptions`

Properties

`insecureTrustAllCertificates`

Type: boolean
Dynamic: ❌
Required: ❌

Whether to disable checking of the remote SSL certificate.

Only applies if no trust store is configured. Note: This makes the SSL connection insecure and should only be used for testing. If you are using a self-signed certificate, set up a trust store instead.

Was this page helpful?

​Request

Request

basicAuthPassword

basicAuthUser

connectTimeout

connectionPoolIdleTimeout

defaultCharset

followRedirects

logLevel

maxContentLength

proxyAddress

proxyPassword

proxyPort

proxyType

proxyUsername

readIdleTimeout

readTimeout

type

value

insecureTrustAllCertificates

Request

`basicAuthPassword`

`basicAuthUser`

`connectTimeout`

`connectionPoolIdleTimeout`

`defaultCharset`

`followRedirects`

`logLevel`

`maxContentLength`

`proxyAddress`

`proxyPassword`

`proxyPort`

`proxyType`

`proxyUsername`

`readIdleTimeout`

`readTimeout`

`type`

`value`

`insecureTrustAllCertificates`