HttpRequest

Overview

The HttpRequest block makes HTTP requests and returns the response. It supports all HTTP methods, headers, query parameters, and automatic JSON serialization.

{
  "block": "HttpRequest",
  "input": {
    "url": "https://api.example.com/users",
    "method": "GET"
  },
  "output": "response"
}

Input Parameters

Required

Parameter	Type	Description
`url`	string	The URL to request
`method`	string	HTTP method (GET, POST, PUT, DELETE, PATCH, etc.)

Optional

Parameter	Type	Default	Description
`headers`	object	`{}`	HTTP headers to send
`body`	string/object	-	Request body (auto-serialized if object)
`query`	object	-	Query parameters to append to URL
`timeout`	number	`30000`	Request timeout in milliseconds

Output Fields

Field	Type	Description
`status`	number	HTTP status code (200, 404, etc.)
`headers`	object	Response headers
`body`	string	Response body as text
`duration`	number	Request duration in milliseconds
`url`	string	Final URL (with query params if any)

Examples

Simple GET Request

{
  "block": "HttpRequest",
  "input": {
    "url": "https://api.example.com/users/1",
    "method": "GET"
  },
  "output": "response"
}

Output:

{
  status: 200,
  headers: { "content-type": "application/json" },
  body: '{"id": 1, "name": "John"}',
  duration: 245,
  url: "https://api.example.com/users/1"
}

POST with JSON Body

{
  "block": "HttpRequest",
  "input": {
    "url": "https://api.example.com/users",
    "method": "POST",
    "headers": {
      "Authorization": "Bearer ${token}"
    },
    "body": {
      "name": "John Doe",
      "email": "john@example.com"
    }
  },
  "output": "createResponse"
}

Notes:

Object bodies are automatically JSON-serialized
Content-Type: application/json is automatically added

GET with Query Parameters

{
  "block": "HttpRequest",
  "input": {
    "url": "https://api.example.com/users",
    "method": "GET",
    "query": {
      "page": "2",
      "limit": "10",
      "sort": "name"
    }
  },
  "output": "response"
}

Final URL: https://api.example.com/users?page=2&limit=10&sort=name

PUT with String Body

{
  "block": "HttpRequest",
  "input": {
    "url": "https://api.example.com/data",
    "method": "PUT",
    "headers": {
      "Content-Type": "text/plain"
    },
    "body": "Raw text content"
  },
  "output": "response"
}

Custom Timeout

{
  "block": "HttpRequest",
  "input": {
    "url": "https://api.example.com/slow-endpoint",
    "method": "GET",
    "timeout": 60000
  },
  "output": "response"
}

Common Patterns

API Authentication

Bearer Token
API Key
Basic Auth

{
  "input": {
    "url": "${BASE_URL}/protected",
    "method": "GET",
    "headers": {
      "Authorization": "Bearer ${authToken}"
    }
  }
}

{
  "input": {
    "url": "${BASE_URL}/data",
    "method": "GET",
    "headers": {
      "X-API-Key": "${env.API_KEY}"
    }
  }
}

{
  "input": {
    "url": "${BASE_URL}/secure",
    "method": "GET",
    "headers": {
      "Authorization": "Basic ${base64Credentials}"
    }
  }
}

REST Operations

Create (POST)
Read (GET)
Update (PUT)
Delete (DELETE)

{
  "block": "HttpRequest",
  "input": {
    "url": "${BASE_URL}/users",
    "method": "POST",
    "body": {
      "name": "John",
      "email": "john@example.com"
    }
  },
  "output": "created"
}

{
  "block": "HttpRequest",
  "input": {
    "url": "${BASE_URL}/users/${userId}",
    "method": "GET"
  },
  "output": "user"
}

{
  "block": "HttpRequest",
  "input": {
    "url": "${BASE_URL}/users/${userId}",
    "method": "PUT",
    "body": {
      "name": "John Updated"
    }
  },
  "output": "updated"
}

{
  "block": "HttpRequest",
  "input": {
    "url": "${BASE_URL}/users/${userId}",
    "method": "DELETE"
  },
  "output": "deleted"
}

Error Handling

The block returns an error if the request fails:

{
  error: "Failed to fetch",
  status: 0,
  duration: 1234,
  url: "https://api.example.com/users"
}

Common errors:

Network errors (connection refused, DNS failure)
Timeout errors (request took longer than timeout ms)
Invalid URL errors

Note: HTTP error status codes (4xx, 5xx) are not treated as errors. Check the status field in assertions:

{
  "assertions": {
    "response.status": 200
  }
}

Full Example

{
  "name": "User API Test",
  "context": {
    "BASE_URL": "https://api.example.com",
    "API_KEY": "${env.API_KEY}"
  },
  "tests": [{
    "id": "create-user",
    "pipeline": [
      {
        "block": "HttpRequest",
        "input": {
          "url": "${BASE_URL}/users",
          "method": "POST",
          "headers": {
            "Authorization": "Bearer ${API_KEY}",
            "Content-Type": "application/json"
          },
          "body": {
            "name": "John Doe",
            "email": "john@example.com",
            "role": "admin"
          },
          "timeout": 5000
        },
        "output": "createResponse"
      },
      {
        "block": "JsonParser",
        "input": "${createResponse.body}",
        "output": {
          "parsed": "newUser"
        }
      }
    ],
    "assertions": {
      "createResponse.status": 201,
      "newUser.id": { "gt": 0 },
      "newUser.email": "john@example.com"
    }
  }]
}

Tips

Always Parse JSON Responses

HttpRequest returns body as text. Use JsonParser to parse it:

{
  "pipeline": [
    {
      "block": "HttpRequest",
      "output": "response"
    },
    {
      "block": "JsonParser",
      "input": "${response.body}",
      "output": { "parsed": "data" }
    }
  ]
}

Use Context for Base URLs

Store base URLs in context to avoid repetition:

{
  "context": {
    "BASE_URL": "${env.API_URL}",
    "API_KEY": "${env.API_KEY}"
  },
  "tests": [{
    "pipeline": [{
      "block": "HttpRequest",
      "input": {
        "url": "${BASE_URL}/endpoint"
      }
    }]
  }]
}

Check Status in Assertions

Don’t rely on errors for HTTP status codes:

{
  "assertions": {
    "response.status": { "lt": 400 }
  }
}

Increase Timeout for Slow Endpoints

Default timeout is 30 seconds. Increase if needed:

{
  "input": {
    "url": "${BASE_URL}/slow",
    "method": "GET",
    "timeout": 120000
  }
}

Get Started

Core Concepts

Blocks

Testing AI Systems

Advanced

Overview

Input Parameters

Required

Optional

Output Fields

Examples

Simple GET Request

POST with JSON Body

GET with Query Parameters

PUT with String Body

Custom Timeout

Common Patterns

API Authentication

REST Operations

Error Handling

Full Example

Tips

Next Steps

JsonParser

StreamParser

​Overview

​Input Parameters

​Required

​Optional

​Output Fields

​Examples

​Simple GET Request

​POST with JSON Body

​GET with Query Parameters

​PUT with String Body

​Custom Timeout

​Common Patterns

​API Authentication

​REST Operations

​Error Handling

​Full Example

​Tips

​Next Steps

JsonParser

StreamParser

Overview

Input Parameters

Required

Optional

Output Fields

Examples

Simple GET Request

POST with JSON Body

GET with Query Parameters

PUT with String Body

Custom Timeout

Common Patterns

API Authentication

REST Operations

Error Handling

Full Example

Tips

Next Steps