RequestRocket Documentation
API Reference

Proxy API

Synchronous API for real-time requests with immediate responses

Proxy API

The Proxy API allows you to make authenticated requests to target APIs through your configured proxies. Requests are processed synchronously with immediate responses.

Overview

Once a proxy has been configured, you can immediately start making API requests to endpoints defined by:

  • The region in which the proxy is deployed
  • The credential type being used
  • The ID of the proxy

Endpoint Format

https://{region_specific_baseURL}/api/{proxyId}/{your_target_path}

URL Components

  • region_specific_baseURL: The regional endpoint (e.g., us-east-1.requestrocket.com)
  • proxyId: Your proxy's unique identifier
  • your_target_path: The path on your target API

The exact Base URL for your proxy is provided in the proxy details after creation. Copy it from the dashboard (or Core API response) for use in your application.

Authentication

All proxy requests require authentication. The authentication method is determined by the proxy credential type configured for your proxy.

RequestRocket supports the following authentication methods:

API Key

Include your API key in the Authorization header (or Authorization query parameter).

curl -X GET "https://{Your_ProxyAPI_URL}/{target_path}" \
  -H "Content-Type: application/json" \
  -H "Authorization: {API_Key_Value}"

Bearer Token

Use a bearer token in the Authorization header (or Authorization query parameter).

curl -X GET "https://{Your_ProxyAPI_URL}/{target_path}" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer {Token}"

Basic Auth

Use username and password with Basic Auth in the header (or Authorization query parameter).

curl -X GET "https://{Your_ProxyAPI_URL}/{target_path}" \
  -H "Content-Type: application/json" \
  -H "Authorization: Basic {Base64_Encoded_Username:Password}"

JWT

Use a JWT token directly in the header (or Authorization query parameter).

curl -X GET "https://{Your_ProxyAPI_URL}/{target_path}" \
  -H "Content-Type: application/json" \
  -H "Authorization: {JWT_Token}"

OAuth 2.0

OAuth 2.0 and 2.1 endpoints are currently under development and not yet supported for proxy credentials.

HTTP Methods

The Proxy API supports all standard HTTP methods:

  • GET: Retrieve resources
  • POST: Create resources
  • PUT: Update/replace resources
  • PATCH: Partially update resources
  • DELETE: Remove resources
  • OPTIONS: Get available methods
  • HEAD: Get headers only

Request Examples

GET Request

const response = await fetch(
  'https://us-east-1.requestrocket.com/api/abc123/users/42',
  {
    method: 'GET',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': 'Bearer your-proxy-token'
    }
  }
);

const data = await response.json();
import requests

response = requests.get(
    'https://us-east-1.requestrocket.com/api/abc123/users/42',
    headers={
        'Content-Type': 'application/json',
        'Authorization': 'Bearer your-proxy-token'
    }
)

data = response.json()
package main

import (
    "encoding/json"
    "io"
    "net/http"
)

func main() {
    client := &http.Client{}
    req, _ := http.NewRequest("GET", "https://us-east-1.requestrocket.com/api/abc123/users/42", nil)
    req.Header.Set("Content-Type", "application/json")
    req.Header.Set("Authorization", "Bearer your-proxy-token")

    resp, _ := client.Do(req)
    defer resp.Body.Close()

    body, _ := io.ReadAll(resp.Body)
    var data map[string]interface{}
    json.Unmarshal(body, &data)
}
import java.net.http.*;
import java.net.URI;

public class GetRequest {
    public static void main(String[] args) throws Exception {
        HttpClient client = HttpClient.newHttpClient();
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://us-east-1.requestrocket.com/api/abc123/users/42"))
            .header("Content-Type", "application/json")
            .header("Authorization", "Bearer your-proxy-token")
            .GET()
            .build();

        HttpResponse<String> response = client.send(request, 
            HttpResponse.BodyHandlers.ofString());

        System.out.println(response.body());
    }
}
curl -X GET "https://us-east-1.requestrocket.com/api/abc123/users/42" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your-proxy-token"

POST Request

const response = await fetch(
  'https://us-east-1.requestrocket.com/api/abc123/users',
  {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': 'Bearer your-proxy-token'
    },
    body: JSON.stringify({
      name: 'John Doe',
      email: 'john@example.com'
    })
  }
);

const data = await response.json();
import requests

response = requests.post(
    'https://us-east-1.requestrocket.com/api/abc123/users',
    headers={
        'Content-Type': 'application/json',
        'Authorization': 'Bearer your-proxy-token'
    },
    json={
        'name': 'John Doe',
        'email': 'john@example.com'
    }
)

data = response.json()
package main

import (
    "bytes"
    "encoding/json"
    "io"
    "net/http"
)

func main() {
    requestBody, _ := json.Marshal(map[string]string{
        "name":  "John Doe",
        "email": "john@example.com",
    })

    client := &http.Client{}
    req, _ := http.NewRequest("POST", "https://us-east-1.requestrocket.com/api/abc123/users", 
        bytes.NewBuffer(requestBody))
    req.Header.Set("Content-Type", "application/json")
    req.Header.Set("Authorization", "Bearer your-proxy-token")

    resp, _ := client.Do(req)
    defer resp.Body.Close()

    body, _ := io.ReadAll(resp.Body)
    var data map[string]interface{}
    json.Unmarshal(body, &data)
}
import java.net.http.*;
import java.net.URI;

public class PostRequest {
    public static void main(String[] args) throws Exception {
        String json = "{\"name\": \"John Doe\", \"email\": \"john@example.com\"}";
        
        HttpClient client = HttpClient.newHttpClient();
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://us-east-1.requestrocket.com/api/abc123/users"))
            .header("Content-Type", "application/json")
            .header("Authorization", "Bearer your-proxy-token")
            .POST(HttpRequest.BodyPublishers.ofString(json))
            .build();

        HttpResponse<String> response = client.send(request, 
            HttpResponse.BodyHandlers.ofString());

        System.out.println(response.body());
    }
}
curl -X POST "https://us-east-1.requestrocket.com/api/abc123/users" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your-proxy-token" \
  -d '{
    "name": "John Doe",
    "email": "john@example.com"
  }'

Response Headers

RequestRocket appends two custom headers to all proxy responses:

requestrocket-proxy-code

Indicates the proxy authentication status:

  • proxy-access-granted: Proxy authentication successful
  • proxy-access-denied: Proxy authentication failed

requestrocket-proxy-message

Provides a human-readable description of the proxy code.

Understanding Responses

Successful Proxy Authentication

If a request successfully passes proxy credential validation (accepted by the gateway), you'll see proxy-access-granted in the response headers - even if the target system returns an error.

This confirms:

  • ✅ You're using the correct proxy credential
  • ✅ RequestRocket has successfully processed your request
  • ✅ The request was forwarded to the target API

Failed Proxy Authentication

If you see proxy-access-denied, it means:

  • ❌ Your proxy credential is invalid
  • ❌ You're using the wrong proxyId in the URL

Error Response with proxy-access-granted

If you see proxy-access-granted but receive an error response, the issue is not the proxy credential. Check:

  1. Target URL: The target API endpoint might be incorrect
  2. Request Format: Your request might be malformed for the target API
  3. Target Credential: The credential used to authenticate with the target might be invalid

If you're receiving errors and RequestRocket headers are attached, you're seeing the actual response from the target system.

Internal Server Errors

There's one notable exception: a 500 error generated from RequestRocket when something has gone very wrong.

If you receive a 500 error without RequestRocket headers, contact our support team as soon as convenient.

Request Flow

Response Headers & Error Codes

RequestRocket adds custom headers to all responses to help you understand the request flow and troubleshoot issues:

  • requestrocket-proxy-code: Status of proxy authentication (proxy-access-granted, proxy-access-denied, etc.)
  • requestrocket-proxy-message: Human-readable description of the proxy code
  • requestrocket-proxy-warning: Warning messages about account or request status

The requestrocket-proxy-code header is key to understanding where an issue occurred. If you see proxy-access-granted with an error response, the issue is with the target API, not the proxy authentication.

Quick Reference:

Proxy CodeStatusIssue Location
proxy-access-denied403Invalid proxy credential or proxyId
proxy-access-granted200-299✅ Success
proxy-access-granted400-499Target API or authorization rules
proxy-access-granted500-599Target API error
billing-suspended402Account payment required
response-too-large413Response exceeds 6MB limit

View complete response headers documentation →

Query Parameters

Query parameters are passed through to the target API:

curl -X GET "https://us-east-1.requestrocket.com/api/abc123/users?page=1&limit=20" \
  -H "Authorization: Bearer your-proxy-token"

The target API will receive:

GET /users?page=1&limit=20

Request Headers

Most headers are passed through to the target API. However:

Modified Headers

  • Host: Set to the target API host
  • Authorization: Replaced with target credential

Preserved Headers

  • Content-Type
  • Content-Length
  • Accept
  • User-Agent
  • Custom headers (X-*, etc.)

Added Headers

  • requestrocket-proxy-code
  • requestrocket-proxy-message
  • X-Forwarded-For (your IP)

Rate Limiting

Rate limits are applied per proxy credential:

PlanRate Limit
Basic100 requests/minute
Team1,000 requests/minute
BusinessCustom

When exceeded, you'll receive a 429 Too Many Requests response.

Timeouts

  • Default Timeout: 30 seconds
  • Maximum Timeout: 60 seconds

If the target API doesn't respond within the timeout period, you'll receive a 504 Gateway Timeout error.

Next Steps

On this page