HTTP tools

The HTTP tool enables AI agents to make HTTP requests to any API or web service with comprehensive control over request parameters.

Tool overview

import { createHttpRequestTool } from "@/core/agent/tools/http-tools";

const httpTool = createHttpRequestTool();
yield* registerTool(httpTool);

http_request

Send HTTP requests with full control over method, headers, query parameters, and body. Parameters:

method

required

HTTP method

url

string

required

Absolute URL with protocol (http or https)Example: "https://api.example.com/v1/users"

headers

object

Request headers as key-value pairsMaximum: 32 headersExample: { "Authorization": "Bearer token", "Content-Type": "application/json" }

query

object

Query parameters as key-value pairsValues can be string, number, or booleanExample: { "page": 1, "limit": 10 }

body

object

Request body. Must be one of:

Show JSON body

type

'json'

required

value

unknown

required

JSON-serializable value

Show Text body

type

'text'

required

value

string

required

Plain text content

Show Form body

type

'form'

required

value

object

required

URL-encoded form fields (key-value pairs)

timeoutMs

number

default:15000

Request timeout in milliseconds (cap: 120000 = 2 minutes)

followRedirects

boolean

default:true

Whether to follow HTTP redirects

maxResponseBytes

number

default:1048576

Maximum response size in bytes (cap: 5000000 = 5MB)

cacheTtlSeconds

number

Cache duration in seconds (adds Cache-Control: max-age header)Maximum: 3600 (1 hour)

Returns:

request

object

Request details:

Show properties

method

string

HTTP method used

url

string

Full URL (including query parameters)

headers

object

Request headers (sensitive headers redacted)

query

object

Query parameters

body

object

Request body (if provided)

timeoutMs

number

Timeout used

followRedirects

boolean

Whether redirects were followed

maxResponseBytes

number

Maximum response size

responseType

'json' | 'text' | 'bytes'

Response type inferred from Content-Type

response

object

Response details:

Show properties

status

number

HTTP status code

statusText

string

HTTP status text

headers

object

Response headers (sensitive headers redacted)

elapsedMs

number

Request duration in milliseconds

size

number

Response size in bytes

truncated

boolean

Whether response was truncated due to size limit

body

object

Response body (format depends on Content-Type):JSON response:

Show JSON body

type

'json'

data

unknown

Parsed JSON data

rawText

string

Raw text (if truncated)

parseError

string

Parse error message (if parsing failed)

Text response:

Show Text body

type

'text'

text

string

Response text

Binary response:

Show Bytes body

type

'bytes'

base64

string

Base64-encoded binary data

Example:

// GET request with query parameters
const result1 = yield* httpTool.handler(
  {
    method: "GET",
    url: "https://api.example.com/users",
    query: { page: 1, limit: 10 },
    headers: {
      Authorization: "Bearer token123",
    },
  },
  context
);

// POST request with JSON body
const result2 = yield* httpTool.handler(
  {
    method: "POST",
    url: "https://api.example.com/users",
    headers: {
      "Content-Type": "application/json",
    },
    body: {
      type: "json",
      value: {
        name: "John Doe",
        email: "john@example.com",
      },
    },
  },
  context
);

// Form submission
const result3 = yield* httpTool.handler(
  {
    method: "POST",
    url: "https://api.example.com/login",
    body: {
      type: "form",
      value: {
        username: "john",
        password: "secret",
      },
    },
  },
  context
);

Security features

Header validation

Headers are validated to ensure:

Maximum 32 headers
Valid header names (visible ASCII, no spaces)
Header values under 4KB
Automatic sanitization of sensitive headers in logs

Sensitive headers (redacted in logs):

Authorization
Cookie
*token*
*secret*
*api*key*
*credential*

Automatic headers

The tool adds default headers if not provided:

{
  "User-Agent": "Jazz/1.0 (https://github.com/lvndry/jazz)",
  "Accept": "application/json, text/markdown, text/plain, application/xml, text/xml, text/html, */*",
  "Accept-Charset": "utf-8"
}

Content-Type handling

Content-Type is set automatically based on body type:

JSON body: application/json
Text body: text/plain; charset=utf-8
Form body: application/x-www-form-urlencoded

Response size limits

Responses are truncated if they exceed maxResponseBytes:

{
  response: {
    truncated: true,
    size: 5242880, // Actual size
    body: {
      type: "text",
      text: "[truncated content]…"
    }
  }
}

Timeout enforcement

Requests are aborted if they exceed the timeout:

{
  success: false,
  error: "Request timed out after 15000ms."
}

Error handling

Invalid URL

{
  success: false,
  error: "Invalid URL: not-a-url"
}

Unsupported protocol

{
  success: false,
  error: "Only http and https protocols are supported."
}

Too many headers

{
  success: false,
  error: "Too many headers provided (maximum 32 allowed)."
}

Invalid header name

{
  success: false,
  error: "Invalid header name \"bad name\". Header names must use visible ASCII characters without spaces."
}

Network error

{
  success: false,
  error: "HTTP request failed: ECONNREFUSED"
}

Response type detection

The tool automatically detects response type from Content-Type header:

JSON response

// Content-Type: application/json
{
  response: {
    body: {
      type: "json",
      data: { id: 1, name: "John" }
    }
  }
}

Text response

// Content-Type: text/plain
{
  response: {
    body: {
      type: "text",
      text: "Plain text response"
    }
  }
}

Binary response

// Content-Type: image/png
{
  response: {
    body: {
      type: "bytes",
      base64: "iVBORw0KGgoAAAANSUhEUgAA..."
    }
  }
}

Best practices

Handle HTTP status codes

const result = yield* httpTool.handler(
  {
    method: "GET",
    url: "https://api.example.com/users/123",
  },
  context
);

if (result.success) {
  const { status, body } = result.result.response;
  
  if (status === 200) {
    // Success
    console.log("User:", body.data);
  } else if (status === 404) {
    // Not found
    console.log("User not found");
  } else if (status >= 500) {
    // Server error
    console.error("Server error:", status);
  }
}

Use appropriate timeouts

// Quick API call
{
  url: "https://api.example.com/ping",
  timeoutMs: 5000 // 5 seconds
}

// Long-running request
{
  url: "https://api.example.com/batch-process",
  timeoutMs: 60000 // 1 minute
}

Set proper Content-Type

// JSON request
{
  method: "POST",
  url: "https://api.example.com/data",
  headers: { "Content-Type": "application/json" },
  body: { type: "json", value: { key: "value" } }
}

// XML request
{
  method: "POST",
  url: "https://api.example.com/data",
  headers: { "Content-Type": "application/xml" },
  body: { type: "text", value: "<root><key>value</key></root>" }
}

Handle authentication

// Bearer token
{
  headers: {
    Authorization: "Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
  }
}

// Basic auth
{
  headers: {
    Authorization: `Basic ${btoa("username:password")}`
  }
}

// API key
{
  headers: {
    "X-API-Key": "your-api-key"
  }
}

Limit response size

// Small response expected
{
  url: "https://api.example.com/config",
  maxResponseBytes: 10240 // 10KB
}

// Large file download
{
  url: "https://example.com/large-file.zip",
  maxResponseBytes: 5000000 // 5MB (max)
}

Use query parameters correctly

// Good: Use query parameter object
{
  url: "https://api.example.com/search",
  query: {
    q: "typescript",
    page: 1,
    limit: 10
  }
}
// Actual URL: https://api.example.com/search?q=typescript&page=1&limit=10

// Bad: Manually construct query string
{
  url: "https://api.example.com/search?q=typescript&page=1&limit=10"
}

Common use cases

REST API calls

// List resources
const list = yield* httpTool.handler(
  {
    method: "GET",
    url: "https://api.example.com/v1/posts",
    query: { status: "published", limit: 20 },
  },
  context
);

// Create resource
const create = yield* httpTool.handler(
  {
    method: "POST",
    url: "https://api.example.com/v1/posts",
    body: {
      type: "json",
      value: { title: "New Post", content: "..." },
    },
  },
  context
);

// Update resource
const update = yield* httpTool.handler(
  {
    method: "PUT",
    url: "https://api.example.com/v1/posts/123",
    body: {
      type: "json",
      value: { title: "Updated Title" },
    },
  },
  context
);

// Delete resource
const remove = yield* httpTool.handler(
  {
    method: "DELETE",
    url: "https://api.example.com/v1/posts/123",
  },
  context
);

Webhook calls

const result = yield* httpTool.handler(
  {
    method: "POST",
    url: "https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXXXXXX",
    body: {
      type: "json",
      value: {
        text: "Deployment completed successfully",
      },
    },
  },
  context
);

GraphQL queries

const result = yield* httpTool.handler(
  {
    method: "POST",
    url: "https://api.example.com/graphql",
    headers: {
      "Content-Type": "application/json",
    },
    body: {
      type: "json",
      value: {
        query: `
          query GetUser($id: ID!) {
            user(id: $id) {
              id
              name
              email
            }
          }
        `,
        variables: { id: "123" },
      },
    },
  },
  context
);

File uploads

const result = yield* httpTool.handler(
  {
    method: "POST",
    url: "https://api.example.com/upload",
    headers: {
      "Content-Type": "multipart/form-data",
    },
    body: {
      type: "form",
      value: {
        file: "base64-encoded-data",
        filename: "document.pdf",
      },
    },
  },
  context
);

Tools

Skills

Workflows

Tool overview

http_request

Security features

Header validation

Automatic headers

Content-Type handling

Response size limits

Timeout enforcement

Error handling

Invalid URL

Unsupported protocol

Too many headers

Invalid header name

Network error

Response type detection

JSON response

Text response

Binary response

Best practices

Handle HTTP status codes

Use appropriate timeouts

Set proper Content-Type

Handle authentication

Limit response size

Use query parameters correctly

Common use cases

REST API calls

Webhook calls

GraphQL queries

File uploads

Tools

Skills

Workflows

Documentation Index

​Tool overview

​http_request

​Security features

​Header validation

​Automatic headers

​Content-Type handling

​Response size limits

​Timeout enforcement

​Error handling

​Invalid URL

​Unsupported protocol

​Too many headers

​Invalid header name

​Network error

​Response type detection

​JSON response

​Text response

​Binary response

​Best practices

​Handle HTTP status codes

​Use appropriate timeouts

​Set proper Content-Type

​Handle authentication

​Limit response size

​Use query parameters correctly

​Common use cases

​REST API calls

​Webhook calls

​GraphQL queries

​File uploads

Tool overview

http_request

Security features

Header validation

Automatic headers

Content-Type handling

Response size limits

Timeout enforcement

Error handling

Invalid URL

Unsupported protocol

Too many headers

Invalid header name

Network error

Response type detection

JSON response

Text response

Binary response

Best practices

Handle HTTP status codes

Use appropriate timeouts

Set proper Content-Type

Handle authentication

Limit response size

Use query parameters correctly

Common use cases

REST API calls

Webhook calls

GraphQL queries

File uploads