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 600+ 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:
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.
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.
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.
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
body string
The full body as a string
contentType string
application/json
The request content type
encryptBody booleanstring
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 object
The form data to be send
headers object
The headers to pass to the request
method string
GET
The HTTP method to use
options Non-dynamicHttpConfiguration
{
"followRedirects": "true",
"allowFailed": "false",
"defaultCharset": "UTF-8"
}
The HTTP request options
Outputs
body object
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 integer
The status code of the response.
encryptedBody string
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 object
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 object
The headers of the response.
uri string
uri
The URL of the current request.
Definitions
io.kestra.core.http.client.configurations.TimeoutConfiguration
connectTimeout string
duration
The time allowed to establish a connection to the server before failing.
readIdleTimeout string
PT5M
duration
The time allowed for a read connection to remain idle before closing it.
io.kestra.core.http.client.configurations.BasicAuthConfiguration
type *Requiredobject
password string
The password for HTTP basic authentication.
username string
The username for HTTP basic authentication.
java.nio.charset.Charset
io.kestra.core.http.client.configurations.HttpConfiguration
allowFailed booleanstring
false
If true, allow a failed response code (response code >= 400)
allowedResponseCodes array
List of response code allowed for this request
auth BasicAuthConfigurationBearerAuthConfiguration
The authentification to use.
defaultCharset Charsetstring
UTF-8
The default charset for the request.
followRedirects booleanstring
true
Whether redirects should be followed automatically.
logs array
REQUEST_HEADERS
REQUEST_BODY
RESPONSE_HEADERS
RESPONSE_BODY
The enabled log.
proxy ProxyConfiguration
The proxy configuration.
ssl SslOptions
The SSL request options
timeout TimeoutConfiguration
The timeout configuration.
io.kestra.core.http.client.configurations.ProxyConfiguration
address string
The address of the proxy server.
password string
The password for proxy authentication.
port integerstring
The port of the proxy server.
type string
DIRECT
DIRECT
HTTP
SOCKS
The type of proxy to use.
username string
The username for proxy authentication.
io.kestra.core.http.client.configurations.SslOptions
insecureTrustAllCertificates booleanstring
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.
io.kestra.core.http.client.configurations.BearerAuthConfiguration
type *Requiredobject
token string
The token for bearer token authentication.