HTTP Request Execution

Execute HTTP requests through the cURL engine using either the simplified GET interface or the full-configuration POST interface. Subscribe to asynchronous job lifecycle events over WebSocket for real-time progress tracking.

Execute simple HTTP request

GET /api/v1/curl/request

Simplified interface for executing HTTP requests using URL query parameters. Best suited for simple GET requests and quick testing. For advanced features use the POST endpoint.

Parameters

Name	In	Type	Required	Description
url	query	string	Yes	Target URL
method	query	string	No	HTTP method (default: GET)
response	query	string	No	Response mode: transparent or json (default: json)
mode	query	string	No	Execution mode: sync or async (default: sync)
session_id	query	string	No	Session ID for cookie persistence
follow_redirects	query	boolean	No	Follow redirects (default: true)
timeout	query	integer	No	Timeout in seconds
user_agent	query	string	No	User-Agent header
referer	query	string	No	Referer header
bearer_token	query	string	No	Bearer token
save	query	boolean	No	Save to storage
save_path	query	string	No	Custom save path, relative to downloads/by-job/{job_id} (no absolute paths or ..)
insecure	query	boolean	No	Allow insecure SSL
compressed	query	boolean	No	Request compressed
job_name	query	string	No	Job name for async
data	query	string	No	Raw request body (curl --data); alias body; presence upgrades default method to POST
json	query	string	No	JSON request body, sent with Content-Type: application/json (curl --json); upgrades default method to POST
header	query	string	No	Custom header as Name: Value. Repeatable — supply once per header
data_base64	query	string	No	Base64 request body (binary-safe; standard or URL-safe); alias body_base64. Takes precedence over data/json; upgrades default method to POST

This endpoint accepts no body.

cURL

curl -X GET "https://api.example.com/api/v1/curl/request?url=https%3A%2F%2Fhttpbin.org%2Fget&method=GET&response=json&timeout=30"

SDK

const result = await client.curl.executeCurlRequestGet({
  url: "https://httpbin.org/get",
  method: "GET",
  response: "json",
  timeout: 30
});

200

{
  "success": true,
  "status_code": 200,
  "headers": {
    "content-type": "application/json",
    "date": "Mon, 14 Apr 2025 10:23:45 GMT"
  },
  "body": "{\n  \"args\": {}, \n  \"headers\": {\n    \"Accept\": \"*/*\", \n    \"User-Agent\": \"curl/8.5.0\"\n  }, \n  \"url\": \"https://httpbin.org/get\"\n}",
  "is_binary": false,
  "job_id": null,
  "metadata": {
    "effective_url": "https://httpbin.org/get",
    "redirect_count": 0,
    "size_download": 142,
    "size_upload": 0,
    "speed_download": 1280.5,
    "speed_upload": 0,
    "content_type": "application/json"
  },
  "timing": {
    "total": 0.342,
    "namelookup": 0.012,
    "connect": 0.085,
    "pretransfer": 0.142,
    "starttransfer": 0.298,
    "redirect": 0
  }
}

202

{
  "job_id": "01HMZ8X9K2QF3N5P7R8T6V4WYD",
  "status": "queued"
}

400

{
  "statusCode": 400,
  "error": "Bad Request",
  "message": "Missing required parameter: url"
}

Error Code	Title	Description	Resolution
INVALID_URL	Missing or invalid URL	URL parameter is required and must be valid	Provide url parameter with complete URL including protocol
INVALID_PARAMETER	Invalid query parameter	One or more query parameters have invalid values	Check parameter values match expected types (e.g., timeout as number)

500

{
  "statusCode": 500,
  "error": "Internal Server Error",
  "message": "Network connection failed"
}

Error Code	Title	Description	Resolution
NETWORK_ERROR	Network request failed	Failed to execute HTTP request via cURL	Verify target URL accessibility and network connectivity

Execute HTTP request with full cURL capabilities

POST /api/v1/curl/request

Execute an HTTP request using libcurl with comprehensive configuration options. Supports both synchronous (immediate response) and asynchronous (background job) execution modes. Includes advanced features like retry logic, cookie sessions, proxy configuration, and automatic response storage.

Execution Modes:

• sync (default): Blocks until completion, returns immediate response
• async: Returns job ID immediately, executes in background

Response Modes:

• transparent (default): Returns raw response with original headers
• json: Wraps response in JSON with timing metrics and metadata

Tip

Use this endpoint when you need advanced features such as retry logic, proxy configuration, form encoding, scheduled execution, or session cookies. The body schema is documented as the CurlRequest object.

This endpoint takes no path, query, or header parameters.

The request body conforms to the CurlRequest schema. The only required field is url; all other fields are optional.

cURL

curl -X POST "https://api.example.com/api/v1/curl/request" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://httpbin.org/post",
    "method": "POST",
    "mode": "sync",
    "response": "json",
    "headers": {
      "Accept": "application/json",
      "X-Request-ID": "abc-123"
    },
    "json": "{\"name\":\"hoody\",\"version\":1}",
    "retry_count": 3,
    "retry_delay": 1000,
    "follow_redirects": true,
    "timeout": 30
  }'

SDK

const result = await client.curl.execute({
  url: "https://httpbin.org/post",
  method: "POST",
  mode: "sync",
  response: "json",
  headers: {
    "Accept": "application/json",
    "X-Request-ID": "abc-123"
  },
  json: JSON.stringify({ name: "hoody", version: 1 }),
  retry_count: 3,
  retry_delay: 1000,
  follow_redirects: true,
  timeout: 30
});

200

{
  "success": true,
  "status_code": 200,
  "headers": {
    "content-type": "application/json",
    "date": "Mon, 14 Apr 2025 10:23:45 GMT"
  },
  "body": "{\n  \"json\": {\n    \"name\": \"hoody\", \n    \"version\": 1\n  }, \n  \"url\": \"https://httpbin.org/post\"\n}",
  "is_binary": false,
  "job_id": null,
  "metadata": {
    "effective_url": "https://httpbin.org/post",
    "redirect_count": 0,
    "size_download": 88,
    "size_upload": 34,
    "speed_download": 980.2,
    "speed_upload": 340.0,
    "content_type": "application/json"
  },
  "timing": {
    "total": 0.412,
    "namelookup": 0.015,
    "connect": 0.091,
    "pretransfer": 0.156,
    "starttransfer": 0.378,
    "redirect": 0
  }
}

202

{
  "job_id": "01HMZ8X9K2QF3N5P7R8T6V4WYD",
  "status": "queued"
}

400

{
  "statusCode": 400,
  "error": "Bad Request",
  "message": "Invalid URL format"
}

Error Code	Title	Description	Resolution
INVALID_URL	Malformed URL	The provided URL is not in valid format	Provide a complete URL with protocol (e.g., https://example.com)
INVALID_PARAMETER	Invalid parameter value	One or more parameters contain invalid values	Check parameter types and allowed values in API documentation

500

{
  "statusCode": 500,
  "error": "Internal Server Error",
  "message": "Connection timeout after 30 seconds"
}

Error Code	Title	Description	Resolution
NETWORK_ERROR	Network request failed	cURL could not complete the HTTP request	Check target URL is accessible, verify network connectivity, check timeout settings

Subscribe to job events

GET /api/v1/curl/ws

Establish a WebSocket connection that receives job lifecycle events in JSON.

Message types:

• jobstarted — emitted with {job_id, name} when a new job begins execution
• jobprogress — emitted with {job_id, progress} where progress is a fraction from 0 to 1
• jobcompleted — emitted with {job_id, status} when a job finishes
• error — emitted with {message} when an error occurs

Filtering:

• Pass job_id as a query parameter to only receive events for a single job.

Tip

Use the job snapshot endpoint to fetch the current state of a job, and WebSocket for live updates.

Parameters

Name	In	Type	Required	Description
job_id	query	string	No	Optional job ID filter

This endpoint accepts no body.

WebSocket

// Connect to the events stream filtered by job_id
const ws = new WebSocket(
  "wss://api.example.com/api/v1/curl/ws?job_id=01HMZ8X9K2QF3N5P7R8T6V4WYD"
);

ws.onmessage = (event) => {
  const data = JSON.parse(event.data);
  console.log(data);
};

// Example incoming frames:
// { "type": "jobstarted",   "job_id": "01HMZ8X9K2QF3N5P7R8T6V4WYD", "name": "fetch-feed" }
// { "type": "jobprogress",  "job_id": "01HMZ8X9K2QF3N5P7R8T6V4WYD", "progress": 0.42 }
// { "type": "jobcompleted", "job_id": "01HMZ8X9K2QF3N5P7R8T6V4WYD", "status": "success" }
// { "type": "error",        "message": "Connection reset by peer" }

SDK

// Stream events for a specific job (positional jobId argument)
const stream = await client.curl.events.streamWs("01HMZ8X9K2QF3N5P7R8T6V4WYD");

for await (const event of stream) {
  switch (event.type) {
    case "jobstarted":
      console.log("started:", event.job_id, event.name);
      break;
    case "jobprogress":
      console.log("progress:", event.progress);
      break;
    case "jobcompleted":
      console.log("done:", event.status);
      break;
    case "error":
      console.error("error:", event.message);
      break;
  }
}

101

{
  "statusCode": 101,
  "description": "Switching Protocols — WebSocket connection established"
}

400

{
  "statusCode": 400,
  "error": "Bad Request",
  "message": "Invalid WebSocket upgrade request"
}

500

{
  "statusCode": 500,
  "error": "Internal Server Error",
  "message": "Failed to establish WebSocket connection"
}