request
Make an HTTP API request to a specified URL and store the response as an output.
Make an HTTP API request to a specified URL and store the response as an output.
Make an HTTP API request to a specified URL and store the response as an output.
This task makes an API call to a specified URL of an HTTP server and stores the response as an output.
Kestra offers hundreds of plugins. Before using the generic HTTP task, check if a dedicated plugin fits your use case — it's recommended to use plugins first and only fall back to HTTP when needed.
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 an output of the task. If you need to process large API payloads, we recommend using the Download task instead.
type: "io.kestra.plugin.core.http.request"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.
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:
auth:
type: BASIC
username: "{{ secret('API_USERNAME') }}"
password: "{{ secret('API_PASSWORD') }}"
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.
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 an API key passed in the header.
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 an API key passed in the query parameters.
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.
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.
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.
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.
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.
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.
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.
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 }}"
Send a multiline JSON message using HTTP POST request and inputs with a pebble expression. We recommend this method to avoid JSON string interpolation
id: http_multiline_json
namespace: company.team
inputs:
- id: title
type: STRING
defaults: This is the title of the request
- id: message
type: STRING
defaults: |-
This is my long
multiline message.
- id: priority
type: INT
defaults: 5
tasks:
- id: send
type: io.kestra.plugin.core.http.Request
uri: "https://reqres.in/api/test-request"
method: "POST"
body: |
{{ {
"title": inputs.title,
"message": inputs.message,
"priority": inputs.priority
} }}
Properties
uri*Requiredstring
The fully-qualified URI that points to the HTTP destination
bodystring
The full body as a string
contentTypestring
application/jsonThe request content type
encryptBodybooleanstring
falseIf 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.
formDataobject
The form data to be send
headersobject
The headers to pass to the request
methodstring
GETThe HTTP method to use
optionsNon-dynamic
{
"followRedirects": "true",
"allowFailed": "false",
"defaultCharset": "UTF-8"
}The HTTP request options
io.kestra.core.http.client.configurations.HttpConfiguration
falseIf true, allow a failed response code (response code >= 400)
List of response code allowed for this request
The authentification to use.
io.kestra.core.http.client.configurations.BasicAuthConfiguration
The password for HTTP basic authentication.
The username for HTTP basic authentication.
io.kestra.core.http.client.configurations.BearerAuthConfiguration
The token for bearer token authentication.
The password for HTTP basic authentication. Deprecated, use auth property with a BasicAuthConfiguration instance instead.
The username for HTTP basic authentication. Deprecated, use auth property with a BasicAuthConfiguration instance instead.
durationdurationThe time an idle connection can remain in the client's connection pool before being closed.
UTF-8The default charset for the request.
java.nio.charset.Charset
trueWhether redirects should be followed automatically.
ALLTRACEDEBUGINFOWARNERROROFFNOT_SPECIFIEDThe log level for the HTTP client.
REQUEST_HEADERSREQUEST_BODYRESPONSE_HEADERSRESPONSE_BODYThe enabled log.
The maximum content length of the response.
The proxy configuration.
io.kestra.core.http.client.configurations.ProxyConfiguration
DIRECTDIRECTHTTPSOCKSThe address of the proxy server.
The password for proxy authentication.
The port of the proxy server.
DIRECTHTTPSOCKSThe type of proxy to use.
The username for proxy authentication.
durationdurationThe maximum time allowed for reading data from the server before failing.
The SSL request options
io.kestra.core.http.client.configurations.SslOptions
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.
The timeout configuration.
io.kestra.core.http.client.configurations.TimeoutConfiguration
durationThe time allowed to establish a connection to the server before failing.
PT5MdurationThe time allowed for a read connection to remain idle before closing it.
paramsobject
The query string parameter to use
Adds parameter to URI query. The parameter name and value are expected to be unescaped and may contain non ASCII characters.
The value can be a string or a list of strings.
This method will not override parameters already existing on uri and will add them as array.
Outputs
bodyobject
The body of the response
Kestra, by default, stores 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.
codeinteger
The status code of the response
encryptedBodystring
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.
formDataobject
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).
headersobject
The headers of the response
uristring
uriThe URL of the current request
