Docs »

Automations »

Commands »

http.request

The http.request: command sends data to an HTTP endpoint and returns the response.

A simple GET request:



start:
  http.request/get:
    output: http_response
    inputs:
      url: https://api.example/employee/123
    on_success:
      return:
        body@key: http_response:body


A more complex POST request:



start:
  http.request/post:
    output: http_response
    inputs:
      method: POST
      url: https://api.example/employee/add
      headers@text:
        Content-Type: application/json
      body@text:
        {
          "person": {
            "name": "Kina",
            "title": "Customer support manager"
          }
        }
    on_simulate:
      set:
        http_response:
          status_code@int: 200
          content_type: application/json
          body@text:
            { "status": true, "id": 123 }
  set:
    body@key,json: http_response:body
  return:
    employee_id@int: {{body.id}}


Syntax

inputs:

method:

The HTTP method to use for the request.

Method Body
DELETE  
GET  
HEAD  
OPTIONS  
PATCH
POST
PUT

method: POST

url:

The URL of the HTTP endpoint to use for the request.


url: https://api.example/employee/123

headers:

A set of HTTP headers to include with the request.

Headers should be described as a set of name: value pairs.


headers:
  Content-Type: application/json
  X-Requester: Cerb

The headers can optionally also be defined as a @text block.


headers@text:
  Content-Type: application/json
  X-Requester: Cerb

body:

The body of the HTTP request (if applicable).



body@text:
  This is the body content
  on multiple indented lines.


If the body is defined as a dictionary of key: value pairs, then it will automatically be encoded based on the Content-Type: header:

  • JSON (application/json)
  • YAML (application/x-yaml/text/yaml)
  • URL-encoded (application/x-www-form-urlencoded); or if the Content-Type: is omitted

This removes the need for extraneous set: commands to prepare the HTTP request.



headers:
  Content-Type: application/json
body:
  person:
    name: Kina Halpue
    title: Customer Service Manager


timeout:

The optional timeout in seconds. Decimal values are allowed (e.g. 0.5 for 500ms).



timeout: 0.5


authentication:

The optional URI of a connected account to use for authenticating this HTTP request.

For instance, an OAuth2 connected account will include a bearer token in the Authorization: header.


authentication: cerb:connected_account:my-oauth2-account

output:

Save the results in this placeholder.

on_simulate:

The commands to run during simulation instead of the HTTP request.

If omitted, the HTTP request is executed during simulation.

on_success:

The commands to run on success.

The output: placeholder receives a dictionary with these keys:

Key  
status_code The HTTP status code (e.g. 200)
url The URL of the HTTP endpoint.
content_type The content type of the HTTP response (e.g. application/json).
headers A dictionary of headers from the HTTP response. Keys are lowercase, with dashes as underscores (e.g. content_type).
body The body of the HTTP response.

on_error:

The commands to run on failure. If omitted, the automation exits in the error state.

The output: placeholder receives a dictionary with these keys:

Key  
status_code The HTTP status code (e.g. 500)
url The URL of the HTTP endpoint.
error The error message.