> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tracecat.com/llms.txt
> Use this file to discover all available pages before exploring further.

# HTTP

## `core.http_request`

Perform a HTTP request to a given URL.

### Secrets

Optional secrets:

* `mtls`: required values `TLS_CERTIFICATE`, `TLS_PRIVATE_KEY`.
* `ca_cert`: required values `CA_CERTIFICATE`.

### Inputs

<ParamField path="method" type="string" required>
  HTTP request method

  Allowed values: `GET`, `POST`, `PUT`, `PATCH`, `DELETE`, `HEAD`, `OPTIONS`.
</ParamField>

<ParamField path="url" type="string" required>
  The destination of the HTTP request
</ParamField>

<ParamField path="auth" type="map[string, string] | null">
  Basic auth credentials with `username` and `password` keys

  Default: `null`.
</ParamField>

<ParamField path="base64_encode_data" type="boolean">
  Base64 encode the raw response body before returning. Use this for binary downloads to prevent corruption from text decoding.

  Default: `false`.
</ParamField>

<ParamField path="files" type="map[string, string | FileUploadData] | null">
  Files to upload using multipart/form-data. The dictionary key is the form field name. The value can be a simple base64 encoded string (filename defaults to form field name), or a dictionary with 'filename', 'content\_base64', and optional 'content\_type'.

  Default: `null`.
</ParamField>

<ParamField path="follow_redirects" type="boolean">
  Follow HTTP redirects

  Default: `false`.
</ParamField>

<ParamField path="form_data" type="object | null">
  Form encoded data in request body (POST, PUT, and PATCH)

  Default: `null`.
</ParamField>

<ParamField path="headers" type="map[string, string] | null">
  HTTP request headers

  Default: `null`.
</ParamField>

<ParamField path="ignore_status_codes" type="array[integer] | null">
  If specified, these status codes will not be treated as errors. Defaults to None.

  Default: `null`.
</ParamField>

<ParamField path="max_redirects" type="integer">
  Maximum number of redirects

  Default: `20`.
</ParamField>

<ParamField path="params" type="object | null">
  URL query parameters

  Default: `null`.
</ParamField>

<ParamField path="payload" type="object | array[any] | null">
  JSON serializable data in request body (POST, PUT, and PATCH)

  Default: `null`.
</ParamField>

<ParamField path="timeout" type="number">
  Timeout in seconds

  Default: `10.0`.
</ParamField>

<ParamField path="verify_ssl" type="boolean">
  Verify SSL certificates. Defaults to True, disable at own risk.

  Default: `true`.
</ParamField>

### Examples

**Basic request**

```yaml theme={null}
- ref: fetch_alert
  action: core.http_request
  args:
    url: https://api.example.com/alerts/${{ TRIGGER.alert_id }}
    method: GET
    headers:
      Authorization: Bearer ${{ SECRETS.alerts.API_TOKEN }}
```

## `core.http_poll`

Perform a HTTP request to a given URL with optional polling.

### Secrets

Optional secrets:

* `mtls`: required values `TLS_CERTIFICATE`, `TLS_PRIVATE_KEY`.
* `ca_cert`: required values `CA_CERTIFICATE`.

### Inputs

<ParamField path="method" type="string" required>
  HTTP request method

  Allowed values: `GET`, `POST`, `PUT`, `PATCH`, `DELETE`, `HEAD`, `OPTIONS`.
</ParamField>

<ParamField path="url" type="string" required>
  The destination of the HTTP request
</ParamField>

<ParamField path="auth" type="map[string, string] | null">
  Basic auth credentials with `username` and `password` keys

  Default: `null`.
</ParamField>

<ParamField path="follow_redirects" type="boolean">
  Follow HTTP redirects

  Default: `false`.
</ParamField>

<ParamField path="form_data" type="object | null">
  Form encoded data in request body (POST, PUT, and PATCH)

  Default: `null`.
</ParamField>

<ParamField path="headers" type="map[string, string] | null">
  HTTP request headers

  Default: `null`.
</ParamField>

<ParamField path="max_redirects" type="integer">
  Maximum number of redirects

  Default: `20`.
</ParamField>

<ParamField path="params" type="object | null">
  URL query parameters

  Default: `null`.
</ParamField>

<ParamField path="payload" type="object | array[any] | null">
  JSON serializable data in request body (POST, PUT, and PATCH)

  Default: `null`.
</ParamField>

<ParamField path="poll_condition" type="string | null">
  Python lambda function when evaluated to True, stops polling. The function receives a dict with `headers`, `data`, and `status_code` fields.

  Default: `null`.
</ParamField>

<ParamField path="poll_interval" type="number | null">
  Interval in seconds between polling attempts. If not specified, defaults to polling with exponential wait.

  Default: `null`.
</ParamField>

<ParamField path="poll_max_attempts" type="integer">
  Maximum number of polling attempts. If set to 0, the action will poll indefinitely (until timeout).

  Default: `10`.
</ParamField>

<ParamField path="poll_retry_codes" type="integer | array[integer] | null">
  Status codes on which the action will retry. Ignored if `poll_condition` is provided. If neither are specified, an error will be raised.

  Default: `null`.
</ParamField>

<ParamField path="timeout" type="number">
  Timeout in seconds

  Default: `10.0`.
</ParamField>

<ParamField path="verify_ssl" type="boolean">
  Verify SSL certificates. Defaults to True, disable at own risk.

  Default: `true`.
</ParamField>

### Examples

**Poll until complete**

```yaml theme={null}
- ref: wait_for_export
  action: core.http_poll
  args:
    url: https://api.example.com/exports/${{ TRIGGER.export_id }}
    method: GET
    headers:
      Authorization: Bearer ${{ SECRETS.exports.API_TOKEN }}
    poll_interval: 5
    poll_max_attempts: 24
    poll_condition: "lambda response: response['data'].get('status') == 'completed'"
```

## `core.http_paginate`

Paginate through a HTTP response.

### Inputs

<ParamField path="method" type="string" required>
  HTTP request method

  Allowed values: `GET`, `POST`, `PUT`, `PATCH`, `DELETE`, `HEAD`, `OPTIONS`.
</ParamField>

<ParamField path="next_request" type="string" required>
  Python lambda function that returns the next request as a JSON of `url`, `method`, `headers`, `params`, `payload`, `form_data` to paginate to. The function receives a dict with `headers`, `data`, and `status_code` fields.
</ParamField>

<ParamField path="stop_condition" type="string" required>
  Python lambda function that determines when pagination should STOP. The function receives a dict with `headers`, `data`, and `status_code` fields.
</ParamField>

<ParamField path="url" type="string" required>
  The destination of the HTTP request
</ParamField>

<ParamField path="auth" type="map[string, string] | null">
  Basic auth credentials with `username` and `password` keys

  Default: `null`.
</ParamField>

<ParamField path="follow_redirects" type="boolean">
  Follow HTTP redirects

  Default: `false`.
</ParamField>

<ParamField path="form_data" type="object | null">
  Form encoded data in request body (POST, PUT, and PATCH)

  Default: `null`.
</ParamField>

<ParamField path="headers" type="map[string, string] | null">
  HTTP request headers

  Default: `null`.
</ParamField>

<ParamField path="items_jsonpath" type="string | null">
  JSONPath expression that evaluates to the items to paginate through.

  Default: `null`.
</ParamField>

<ParamField path="limit" type="integer">
  Maximum number of items to paginate through. Defaults to 1000.

  Default: `1000`.
</ParamField>

<ParamField path="max_redirects" type="integer">
  Maximum number of redirects

  Default: `20`.
</ParamField>

<ParamField path="params" type="object | null">
  URL query parameters

  Default: `null`.
</ParamField>

<ParamField path="payload" type="object | array[any] | null">
  JSON serializable data in request body (POST, PUT, and PATCH)

  Default: `null`.
</ParamField>

<ParamField path="timeout" type="number">
  Timeout in seconds

  Default: `10.0`.
</ParamField>

<ParamField path="verify_ssl" type="boolean">
  Verify SSL certificates. Defaults to True, disable at own risk.

  Default: `true`.
</ParamField>

### Examples

**Follow next page links**

```yaml theme={null}
- ref: list_findings
  action: core.http_paginate
  args:
    url: https://api.example.com/findings
    method: GET
    headers:
      Authorization: Bearer ${{ SECRETS.findings.API_TOKEN }}
    params:
      limit: 100
    items_jsonpath: $.items[*]
    stop_condition: "lambda response: response['data'].get('next_cursor') is None"
    next_request: "lambda response: {'url': 'https://api.example.com/findings', 'method': 'GET', 'headers': {'Authorization': 'Bearer ${{ SECRETS.findings.API_TOKEN }}'}, 'params': {'limit': 100, 'cursor': response['data']['next_cursor']}}"
```