---
title: "Perform an outbound HTTP request"
method: POST
path: "/v1/http/request"
tags: ["Web"]
---

# Perform an outbound HTTP request

`POST /v1/http/request`

## Request

- Base URL: `http://localhost:9998`
- URL: `http://localhost:9998/v1/http/request`
- Auth: HTTP bearer

Generic HTTP client with shorthand bodies (`json` / `form` / `body`),
helpers for `bearer` / `basic` / `api_key` auth, redirect control, and
an `allow_local` switch (off by default — blocks loopback / link-local
/ private addresses to mitigate SSRF). Returns status, headers, decoded
body, and a parsed `json` field when the response Content-Type is JSON.

## Request body

- HttpRequestPayload
  - `url` string, required
  - `method` string: HTTP verb. Default `GET`.
  - `headers` object
  - `json` unknown
  - `form` object: Request body — serialized as `application/x-www-form-urlencoded`.
  - `body` string: Raw request body (UTF-8).
  - `auth` object: Auth helper. Explicit `Authorization` header wins.
    - `type` 'bearer' | 'basic' | 'api_key'
    - `token` string
    - `username` string
    - `password` string
    - `key` string
    - `header` string: Header name for `type=api_key`. Default `X-API-Key`.
  - `timeout_ms` integer: Request timeout in ms. Capped by service.
  - `follow_redirects` boolean: Follow HTTP redirects. Default true.
  - `allow_local` boolean: Allow loopback / link-local / private addresses. Default false (SSRF guard).
  - `parse_json` boolean: When the response Content-Type looks like JSON, also include a parsed `json` field. Default true.

## Response `200`

Upstream response (status, headers, body, optional parsed JSON)

- HttpRequestResponse
  - `status` integer, required
  - `statusText` string, required
  - `headers` object, required
  - `contentType` string, required
  - `elapsedMs` integer, required
  - `sizeBytes` integer, required
  - `finalUrl` string, required
  - `truncated` boolean, required
  - `body` string, required: Response body — UTF-8 string when decodable, otherwise base64.
  - `bodyEncoding` 'utf8' | 'base64', required
  - `json` unknown

## Other responses

- `400`: Invalid request
- `502`: Outbound request failed (transport error, blocked, etc.)
- `503`: HTTP request service not initialized

---

[API](https://skmtc.dev/modelpiper/apis/toolpiper-api.md) · [All operations](https://skmtc.dev/modelpiper/apis/toolpiper-api/llms.txt) · [OpenAPI document](https://skmtc.dev/modelpiper/apis/toolpiper-api/revisions/6722bf56385c?raw)