RapidSeedbox API Documentation

Authentication

All API requests require a Bearer token in the Authorization header. You can obtain your API key from the RapidSeedbox client area.

Header

Authorization: Bearer YOUR_API_KEY

Example curl request

curl -X GET https://api.rapidseedbox.com/api/v1/account/balance \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json"

Important: Keep your API key secret. Do not share it in public repositories or client-side code.

GET

Get Account Balance

Retrieve the credit balance for your account.

Endpoint

GET /api/v1/account/balance

Parameters

No parameters required.

Curl Example

curl -X GET https://api.rapidseedbox.com/api/v1/account/balance \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json"

Success Response 200

{
  "user_id": "12345",
  "currency": "USD",
  "balance": 42.50
}

Error Responses

401 Unauthorized

{
  "error": {
    "code": "MISSING_API_KEY",
    "message": "Authorization header is required."
  }
}

GET

List Products

List all active residential proxy products associated with your account.

Endpoint

GET /api/v1/products

Parameters

No parameters required.

Curl Example

curl -X GET https://api.rapidseedbox.com/api/v1/products \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json"

Success Response 200

{
  "products": [
    {
      "product_id": "98765",
      "type": "FLEXIBLE",
      "remaining_bw_gb": 5120,
      "status": "active"
    },
    {
      "product_id": "98766",
      "type": "FIXED_10GB",
      "remaining_bw_gb": 10,
      "status": "active"
    }
  ]
}

Response Fields

Field	Type	Description
product_id	string	Unique product identifier
type	string	FLEXIBLE, FIXED_10GB, FIXED_50GB, FIXED_100GB, or FIXED_500GB
remaining_bw_gb	integer	Remaining bandwidth in GB
status	string	Product status (e.g. active)

POST

Create a Product

Create a new residential proxy product order.

Endpoint

POST /api/v1/products

Request Body

Parameter	Type	Required	Description
type	string	Yes	Product type: `PAYG`, `SUBSCRIPTION_10GB`, `SUBSCRIPTION_50GB`, `SUBSCRIPTION_100GB`, `SUBSCRIPTION_500GB`
initial_bw_gb	integer	Required if PAYG	Initial bandwidth in GB (min: 1). Required for PAYG products only.

Curl Example

curl -X POST https://api.rapidseedbox.com/api/v1/products \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "type": "PAYG",
    "initial_bw_gb": 10
  }'

Success Response 201

{
  "result": "success",
  "message": "Product created and provisioned successfully.",
  "order_id": 1024,
  "product_id": 98765,
  "invoice_id": 5001,
  "type": "PAYG",
  "currency": "USD",
  "amount_charged": 15,
  "credit_before": 100,
  "credit_after": 85,
  "initial_bw_gb": 10,
  "service_status": "active"
}

Response Fields

Field	Type	Description
result	string	Operation result (`success` or `error`)
message	string	Human-readable status message
order_id	integer	Created order ID
product_id	integer	Created product/service ID
invoice_id	integer	Generated invoice ID
type	string	Product type (PAYG, SUBSCRIPTION_10GB, etc.)
currency	string	Currency code (e.g. EUR, USD)
amount_charged	number	Amount charged from account credit
credit_before	number	Account credit balance before the charge
credit_after	number	Account credit balance after the charge
initial_bw_gb	integer	Initial bandwidth in GB (PAYG only)
service_status	string	Service status (e.g. active)

Error Responses

400 Validation Error

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid product type. Allowed: PAYG, SUBSCRIPTION_10GB, SUBSCRIPTION_50GB, SUBSCRIPTION_100GB, SUBSCRIPTION_500GB."
  }
}

400 Validation Error

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Initial bandwidth (initial_bw_gb) is required for PAYG products."
  }
}

POST

Top-up PAYG Bandwidth

Add bandwidth to an existing Pay-As-You-Go proxy product.

Endpoint

POST /api/v1/products/topup

Request Body

Parameter	Type	Required	Description
product_id	string	Yes	The product to top up
amount_gb	integer	Yes	Bandwidth to add in GB (min: 1)

Curl Example

curl -X POST https://api.rapidseedbox.com/api/v1/products/topup \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "product_id": "98765",
    "amount_gb": 5
  }'

Success Response 200

{
  "product_id": "98765",
  "added_bw_gb": 5,
  "status": "success"
}

Error Responses

400 Validation Error

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "The product_id field is required."
  }
}

500 Service Error

{
  "result": "error",
  "message": "Service not found, not active, or not Residential Proxy Flexible for the given user.",
  "remaining_credit": null,
  "total_charged": null
}

POST

Cancel a Product

Cancel an active proxy product.

Cancellation Rules

PAYG (Flexible): Immediately terminated. Any remaining bandwidth balance will be lost and cannot be recovered.
Subscription (Fixed): Service remains active until the end of the current billing period. No further renewals will be charged.

Endpoint

POST /api/v1/products/{productId}/cancel

URL Parameters

Parameter	Type	Required	Description
productId	integer	Yes	The product ID to cancel

Curl Example

curl -X POST https://api.rapidseedbox.com/api/v1/products/98765/cancel \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json"

Success Response 200

{
  "product_id": "98765",
  "status": "cancelled"
}

Error Responses

404 Not Found

{
  "error": {
    "code": "PRODUCT_NOT_FOUND",
    "message": "The specified product was not found."
  }
}

GET

Get Proxy Credentials

Retrieve the proxy connection credentials for a specific product.

Endpoint

GET /api/v1/products/{productId}/proxy

URL Parameters

Parameter	Type	Required	Description
productId	integer	Yes	The product ID

Curl Example

curl -X GET https://api.rapidseedbox.com/api/v1/products/98765/proxy \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json"

Success Response 200

{
  "product_id": "98765",
  "proxy_host": "proxy.rapidseedbox.com",
  "username": "user_abc123",
  "password": "p4ssw0rd",
  "http_port": 8080,
  "socks_port": 1080,
  "remaining_bw_gb": 50,
  "status": "active"
}

Error Responses

404 Not Found

{
  "error": {
    "code": "PRODUCT_NOT_FOUND",
    "message": "The specified product was not found."
  }
}

GET

Get GEO Locations

Retrieve available GEO targeting locations for proxy configuration. Results are cached for 24 hours.

Endpoint

GET /api/v1/geos

Parameters

No parameters required.

Curl Example

curl -X GET https://api.rapidseedbox.com/api/v1/geos \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json"

Success Response 200

{
  "countries": ["US", "GB", "DE", "FR", "JP"],
  "cities": ["New York", "London", "Berlin", "Paris", "Tokyo"],
  "regions": ["North America", "Europe", "Asia"],
  "isp": ["ISP_A", "ISP_B", "ISP_C"],
  "continents": ["NA", "EU", "AS"]
}

Error Codes

All errors follow a consistent format:

{
  "error": {
    "code": "ERROR_CODE",
    "message": "A human-readable description of the error."
  }
}

HTTP Status	Error Code	Description
400	VALIDATION_ERROR	Request body failed validation. Check the message for details.
401	MISSING_API_KEY	No Authorization header was provided in the request.
401	INVALID_API_KEY	The provided API key is invalid or has been revoked.
404	PRODUCT_NOT_FOUND	The specified product was not found or does not belong to your account.
500	INTERNAL_ERROR	An unexpected server error occurred. Please try again later.

Rate Limiting

API requests are rate-limited to ensure fair usage and system stability.

60 requests per minute

If you exceed this limit, you will receive a 429 Too Many Requests response. Wait for the rate limit window to reset before retrying.

Header	Description
X-RateLimit-Limit	Maximum requests allowed per window (60)
X-RateLimit-Remaining	Requests remaining in the current window
Retry-After	Seconds until the rate limit resets (only on 429 responses)