Making Requests

Learn how to construct and send HTTP requests to the Pullbay API. This guide covers request formatting, headers, parameters, response structure, and practical examples in multiple languages.

Base URL

All Pullbay API requests use this base URL:

https://api.pullbay.com

Append the service path and endpoint to this base URL.

Request Format

GET /{service}/{endpoint}?{parameters}

Example:

GET /appstore/reviews?appId=389801252&country=us&page=1

All current Pullbay endpoints are GET requests. Parameters are passed in the query string.

Required Headers

Header	Required	Value	Example
Authorization	Yes	Bearer token with your API key	Authorization: Bearer YOUR_API_KEY
User-Agent	Optional	Your application identifier	User-Agent: MyApp/1.0

Authorization header format

Authorization: Bearer YOUR_API_KEY

Replace YOUR_API_KEY with your actual API key from the Pullbay dashboard. Your API key is secret — never share it or commit it to version control.

Common Parameters

Parameters vary by endpoint; each endpoint's reference page lists its own. The App Store reviews endpoint, for example, accepts:

Parameter	Type	Required	Description
appId	string	One of appId/bundleId	App Store app ID (numeric). Pattern ^\d{8,12}$.
bundleId	string	One of appId/bundleId	App bundle ID (e.g. com.burbn.instagram).
country	string	No	Two-letter storefront code (e.g. us, gb, jp).
sort	string	No	Sort order: recent or helpful.
page	integer	No	Page number (1–10). Mutually exclusive with maxItems.
maxItems	integer	No	One-shot bulk pull (1–500). Mutually exclusive with page.

Use page to fetch one page at a time, or maxItems for a single bulk call — not both.

Example:

GET /appstore/reviews?appId=389801252&country=us&sort=recent&page=1
GET /appstore/reviews?appId=389801252&country=us&maxItems=500

Request Examples

Basic GET request

curl -X GET "https://api.pullbay.com/appstore/reviews?appId=389801252&country=us" \
  -H "Authorization: Bearer YOUR_API_KEY"

Paginated request (page)

curl -X GET "https://api.pullbay.com/appstore/reviews?appId=389801252&page=2" \
  -H "Authorization: Bearer YOUR_API_KEY"

Bulk pull (maxItems)

curl -X GET "https://api.pullbay.com/appstore/reviews?appId=389801252&country=us&maxItems=500" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response Structure

All successful responses follow this consistent JSON structure:

{
  "requestId": "3b8dcb68-1f8c-4a7b-b9e7-63a7b9986f24",
  "status": 200,
  "message": "OK",
  "success": true,
  "data": [
    {
      "id": "13997548250",
      "date": "2026-04-25T19:57:33-07:00",
      "userName": "Catie0012",
      "userUrl": "https://itunes.apple.com/us/reviews/id1632846422",
      "version": "426.0.0",
      "score": 5,
      "title": "How I love your app",
      "text": "An unmatched experience.",
      "url": "https://itunes.apple.com/us/review?id=389801252",
      "country": "US"
    }
  ],
  "pagination": {
    "page": 1,
    "hasNextPage": null,
    "cursor": null,
    "offset": null
  },
  "pricing": {
    "creditsCharged": 2
  }
}

Response fields explained

Top level

• requestId (string): Unique identifier for this request. Save it for debugging and support.

• status (integer): HTTP status code.

• message (string): Human-readable status message.

• success (boolean): Whether the request succeeded.

data (array)

• Contains the actual results. Each object's structure depends on the endpoint.

• An empty array [] means no matching results (not an error).

pagination (object) — present on list/search endpoints

• page (integer): Current page number.

• hasNextPage (boolean): Whether more pages are available.

• cursor / offset (string): Used only by cursor- or offset-paginated services (e.g. Google Maps); null for App Store.

pricing (object)

• creditsCharged (number): Credits consumed by this request.

Error Response Format

When a request fails, the response keeps the same top-level envelope and adds an error object:

{
  "requestId": "3b8dcb68-1f8c-4a7b-b9e7-63a7b9986f24",
  "status": 400,
  "message": "Bad request",
  "success": false,
  "error": {
    "code": "BAD_REQUEST"
  }
}

• success is false on failure.

• status / message describe the failure (e.g. 402 Insufficient credits, 404 Not found).

• error.code is a machine-readable code for programmatic handling.

• Include requestId when contacting Pullbay support for faster debugging.

Complete Request/Response Example

Request

curl -X GET "https://api.pullbay.com/appstore/reviews?appId=389801252&country=us&maxItems=2" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "User-Agent: MyApp/1.0"

Response (200 OK)

{
  "requestId": "3b8dcb68-1f8c-4a7b-b9e7-63a7b9986f24",
  "status": 200,
  "message": "OK",
  "success": true,
  "data": [
    {
      "id": "13997548250",
      "date": "2026-04-25T19:57:33-07:00",
      "userName": "Catie0012",
      "version": "426.0.0",
      "score": 5,
      "title": "Perfect productivity tool",
      "text": "This app streamlines my entire workflow. Highly recommended!",
      "country": "US"
    },
    {
      "id": "13997548251",
      "date": "2026-04-24T09:45:00-07:00",
      "userName": "MikeK",
      "version": "426.0.0",
      "score": 4,
      "title": "Good but needs one feature",
      "text": "Overall excellent. Would love to see offline support.",
      "country": "US"
    }
  ],
  "pagination": { "page": 1, "hasNextPage": null, "cursor": null, "offset": null },
  "pricing": { "creditsCharged": 3 }
}

Language-Specific Examples

Python

import requests

API_KEY = "YOUR_API_KEY"
BASE_URL = "https://api.pullbay.com"

headers = {
    "Authorization": f"Bearer {API_KEY}",
    "User-Agent": "MyApp/1.0",
}

response = requests.get(
    f"{BASE_URL}/appstore/reviews",
    params={"appId": "389801252", "country": "us", "page": 1},
    headers=headers,
)

if response.ok:
    data = response.json()
    reviews = data["data"]
    print(f"Fetched {len(reviews)} reviews (Request ID: {data['requestId']})")
    print(f"Has next page: {data['pagination']['hasNextPage']}")
    print(f"Credits charged: {data['pricing']['creditsCharged']}")
else:
    body = response.json()
    print(f"Error {body['error']['code']}: {body['message']} (Request ID: {body['requestId']})")

Node.js

const API_KEY = "YOUR_API_KEY";
const BASE_URL = "https://api.pullbay.com";

async function fetchReviews() {
  const params = new URLSearchParams({ appId: "389801252", country: "us", page: "1" });
  const response = await fetch(`${BASE_URL}/appstore/reviews?${params}`, {
    headers: {
      Authorization: `Bearer ${API_KEY}`,
      "User-Agent": "MyApp/1.0",
    },
  });

  const body = await response.json();
  if (response.ok) {
    console.log(`Fetched ${body.data.length} reviews (Request ID: ${body.requestId})`);
    console.log(`Has next page: ${body.pagination.hasNextPage}`);
  } else {
    console.error(`Error ${body.error.code}: ${body.message} (Request ID: ${body.requestId})`);
  }
}

fetchReviews();

PHP

<?php
$apiKey = "YOUR_API_KEY";
$baseUrl = "https://api.pullbay.com";

$params = http_build_query(["appId" => "389801252", "country" => "us", "page" => 1]);

$ch = curl_init();
curl_setopt_array($ch, [
    CURLOPT_URL => "{$baseUrl}/appstore/reviews?{$params}",
    CURLOPT_HTTPHEADER => ["Authorization: Bearer {$apiKey}", "User-Agent: MyApp/1.0"],
    CURLOPT_RETURNTRANSFER => true,
]);
$response = curl_exec($ch);
$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

$body = json_decode($response, true);
if ($httpCode === 200) {
    echo "Fetched " . count($body["data"]) . " reviews\n";
    echo "Request ID: " . $body["requestId"] . "\n";
} else {
    echo "Error " . $body["error"]["code"] . ": " . $body["message"] . "\n";
}
?>

Ruby

require 'net/http'
require 'json'
require 'uri'

API_KEY = "YOUR_API_KEY"
BASE_URL = "https://api.pullbay.com"

uri = URI("#{BASE_URL}/appstore/reviews")
uri.query = URI.encode_www_form(appId: "389801252", country: "us", page: 1)

request = Net::HTTP::Get.new(uri)
request["Authorization"] = "Bearer #{API_KEY}"
request["User-Agent"] = "MyApp/1.0"

http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true
response = http.request(request)

body = JSON.parse(response.body)
if response.code == "200"
  puts "Fetched #{body['data'].length} reviews"
  puts "Request ID: #{body['requestId']}"
else
  puts "Error #{body['error']['code']}: #{body['message']}"
end

Frequently Asked Questions

What's the difference between `page` and `maxItems`?

They're mutually exclusive modes on list/search endpoints. Use page to fetch one page at a time (max 10 pages for App Store reviews) with fine control over credits. Use maxItems (max 500 for App Store reviews) to pull a full set in a single call — simpler for batch jobs. Don't send both.

How do I know if there are more results?

Check pagination.hasNextPage. When it's true, request the next page by incrementing page.

How do I pass multiple parameters?

Use the query string: GET /appstore/reviews?appId=389801252&country=us&sort=recent&page=1.

Should I include the User-Agent header?

It's optional but recommended for better diagnostics. Identify your application, e.g. User-Agent: MyApp/1.0.

What should I do with the `requestId`?

Save it from responses, especially errors. Include it when contacting Pullbay support so they can locate your request in the logs.

Can I cache API responses?

Yes — caching reduces calls and credit consumption. Cache app metadata longer than dynamic data like reviews, and validate freshness with timestamps.

What encoding should I use for special characters in parameters?

URL-encode query parameters with your language's standard library: Python urllib.parse.urlencode(), JavaScript URLSearchParams, PHP http_build_query(), Ruby URI.encode_www_form().