LoginToolsPricing
Skip to content
BirdProxies
BirdProxies
Login
  • Home
  • Quickstart
  • Products
  • Integrations
    • Integration guides
    • REST API
  • Account
  • Common issues
  • Reference
  • Dashboard
  • Discord support
  1. Documentation
  2. REST API

REST API

Read your plans and credentials, generate proxy lists, manage sub-users, swap IPs and control servers from your own code.

Overview

The API is for automating what you would otherwise click through in the dashboard: pulling fresh proxy lists into your tools, watching data balances, handing out sub-users, swapping blocked IPs or rebooting a server from a script. It does not place orders, those stay in the checkout.

Every endpoint lives under one base URL and speaks JSON over HTTPS:

Base URL
https://birdproxies.com/api/v1
  • •Create and manage keys in the dashboard under Account, AI & API. The same page shows your usage, live rate limits and a 30 day log of changes and errors.
  • •The machine readable description is at /openapi.json (OpenAPI 3.1). Import it into Postman or Insomnia, or generate a client from it.
  • •Timestamps are ISO 8601 in UTC, ids are hex strings, money is a decimal EUR number with a currency field, data amounts are GB.

Quick start

Create a key in the dashboard, then keep it in an environment variable so it never ends up in your shell history or your code:

Shell
export BP_API_KEY="bp_live_..."

1. List your ISP plans

Returns every plan without credentials. Take the id of the plan you want.

Request
curl -s "https://birdproxies.com/api/v1/isp/plans" \
  -H "Authorization: Bearer $BP_API_KEY"

2. Get its proxies as a text list

One ip:port:user:pass per line, ready to paste into a bot or an antidetect browser. Leave out format=txt for JSON.

Request
curl -s "https://birdproxies.com/api/v1/isp/plans/PLAN_ID/proxies?format=txt" \
  -H "Authorization: Bearer $BP_API_KEY"
Response 200, text/plain
203.0.113.10:8000:user123:pass456
203.0.113.11:8000:user123:pass456

3. Generate residential proxies

Ten rotating US lines. Up to 10000 per call.

Request
curl -s -X POST "https://birdproxies.com/api/v1/residential/proxies" \
  -H "Authorization: Bearer $BP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"proxyType":"http","routingType":"rotating","generateAmount":10,"countries":[{"country":"US"}]}'

Authentication

Send your key as a Bearer token on every request:

Header
Authorization: Bearer bp_live_...
  • •Keys start with bp_live_. The full key is shown once, when you create it. We only store a hash, so nobody can show it to you again; if it is lost, create a new one.
  • •Up to 10 active keys per account. Give each tool its own key, so you can revoke one without breaking the others.
  • •Keys in the URL (query string) are never accepted. Only the Authorization header counts.
  • •Optional IP allowlist per key: single IPv4 or IPv6 addresses and IPv4 ranges in CIDR notation (for example 203.0.113.0/24). Requests from anywhere else get ip_not_allowed.
  • •Resetting your account password revokes every key at once. Create new ones afterwards.
  • •We send a security email every time a new key is created on your account. If you did not create it, revoke it in the dashboard and change your password.

Scopes

Each key carries one or both scopes. A script that only reads proxy lists does not need to be able to delete sub-users, so give it the read scope only.

ScopeAllows
readView the account, plans, usage, invoices and credentials, and generate proxy lists.
manageEverything that changes something: sub-users, password resets, IP swaps, server power and auto-renew.

Every endpoint below shows the scope it needs. Calling one without it answers insufficient_scope (403) with the required and granted scopes in details. Keys created before scopes existed keep full access.


Responses and errors

Every JSON response uses the same envelope. On success the payload sits in data:

Success
{
  "success": true,
  "data": { ... }
}

An error has a readable error message, a stable machine code to branch on, the requestId and, for some codes, details:

Error
{
  "success": false,
  "error": "This endpoint needs the \"manage\" scope.",
  "code": "insufficient_scope",
  "requestId": "req_3f9a1c2b7d4e6f80",
  "details": { "required": "manage", "granted": ["read"] }
}

Every response carries an X-Request-Id header, errors also repeat it as requestId. Quote it to support and we can find the exact call.

Proxy lists in text format and invoice PDFs are not wrapped in the envelope. Their errors are JSON as usual.

Error codes

Branch on code, not on the message text. The message may change, the code does not.

CodeHTTPMeaning
missing_api_key401No API key sent. Use Authorization: Bearer bp_live_....Can happen on every endpoint.
invalid_api_key401The API key is unknown or was revoked.Can happen on every endpoint.
api_key_expired401The API key has expired.Can happen on every endpoint.
ip_not_allowed403This key is not allowed from your IP address.Can happen on every endpoint.
insufficient_scope403This key does not have the scope this endpoint needs.Can happen on every endpoint.
validation_error400The request is invalid. See details.fields.
not_found404Not found.
conflict409The resource is busy or already in the requested state.
cooldown_active429This action is on cooldown.
rate_limited429Rate limit reached. Retry after the time in Retry-After.Can happen on every endpoint.
payment_required402This action needs a purchase first (for example an IP Refresh Pass).
internal_error500Something went wrong on our side. Quote the request id to support.Can happen on every endpoint.
upstream_error502The proxy network did not answer. Nothing was changed, try again.

Validation errors

A validation_error (400) lists every problem in details.fields, one entry per field with its name and what is wrong. Unknown body fields are rejected too, so a typo fails loudly instead of being ignored.

Response 400
{
  "success": false,
  "error": "Unknown field \"nickame\".",
  "code": "validation_error",
  "requestId": "req_8b21d0c4e9a7f312",
  "details": {
    "fields": [
      { "field": "nickame", "message": "Unknown field \"nickame\"." }
    ]
  }
}

Rate limits

Limits count per account, not per key. All your keys, the dashboard and the AI assistant (MCP) share the same buckets, so a second key does not double your budget.

BucketLimitCounts
Reads (apiRead)120 per 1 hourGET requests
Changes (apiWrite)30 per 1 hourPOST, PUT, PATCH and DELETE requests that change something
Proxy generation (proxyGenerate)20 per 1 hourPOST /residential/proxies and POST /mobile/proxies

Every response tells you where you stand:

HeaderMeaning
X-Request-IdUnique id of this request (req_...). Sent on every response, also on errors. Quote it to support.
X-RateLimit-LimitRequests allowed in the current window of the bucket.
X-RateLimit-RemainingRequests left in the current window.
X-RateLimit-ResetUnix time (seconds) when the window resets.
X-RateLimit-BucketWhich bucket the request counted against: apiRead, apiWrite or proxyGenerate.
Retry-AfterSeconds to wait, sent with 429 responses.

When you get a 429

  • •rate_limited: wait the number of seconds in Retry-After, then retry. Do not retry in a loop, every attempt counts.
  • •cooldown_active is also a 429 but belongs to one action (an IP swap), not to your budget. Retrying will not help before details.nextSwapAt.
  • •Cache what rarely changes. Plans and credentials stay the same until you swap, reset or renew, so there is no need to fetch them on every run.

Endpoint reference

Paths are relative to https://birdproxies.com/api/v1. Every example uses the key from $BP_API_KEY and made up ids and addresses.

Account
  • GET/account
  • GET/account/transactions
  • GET/account/invoices
  • GET/account/invoices/{id}
  • GET/proxies
Products
  • GET/products
ISP
  • GET/isp
  • GET/isp/plans
  • GET/isp/plans/{planId}
  • GET/isp/plans/{planId}/proxies
  • POST/isp/plans/{planId}/swap
  • POST/isp/plans/{planId}/reset-password
  • PUT/isp/plans/{planId}/auto-renew
  • GET/isp/plans/{planId}/renewal
Residential
  • GET/residential/locations
  • GET/residential/usage
  • POST/residential/proxies
  • GET/residential/sub-users
  • POST/residential/sub-users
  • GET/residential/sub-users/{id}
  • PATCH/residential/sub-users/{id}
  • DELETE/residential/sub-users/{id}
  • GET/residential/sub-users/{id}/usage
Mobile
  • GET/mobile
  • POST/mobile/proxies
  • POST/mobile/reset-password
Servers
  • GET/servers
  • GET/servers/{planId}
  • POST/servers/{planId}/power

Account

Who the key belongs to, payments, invoices, and everything provisioned in one call.

GET/account

Account summary

Scope: readLimit: Reads, 120 per hour

Who the key belongs to, what is provisioned, and which key made the call.

Request
curl -s "https://birdproxies.com/api/v1/account" \
  -H "Authorization: Bearer $BP_API_KEY"
Response 200
{
  "success": true,
  "data": {
    "email": "you@example.com",
    "name": "Alex",
    "referralCode": "ALEX10",
    "createdAt": "2026-01-15T10:00:00.000Z",
    "ispPlans": 2,
    "residentialAccounts": 1,
    "hasMobile": false,
    "hasIpRefreshPass": true,
    "key": {
      "prefix": "bp_live_AbCd...",
      "name": "Production",
      "scopes": [
        "read",
        "manage"
      ]
    }
  }
}
GET/account/transactions

Payments, newest first

Scope: readLimit: Reads, 120 per hour

Parameters

pageinteger, queryoptional
Page number, starting at 1.Default 1.
limitinteger, queryoptional
Items per page, 1 to 100.Default 20.
statusstring, queryoptional
Only payments with this status.One of all, completed, pending, failed.Default all.
  • •Amounts are decimal EUR numbers.

Errors: validation_error, plus the common ones.

Request
curl -s "https://birdproxies.com/api/v1/account/transactions" \
  -H "Authorization: Bearer $BP_API_KEY"
Response 200
{
  "success": true,
  "data": {
    "items": [
      {
        "id": "6650a1b2c3d4e5f6a7b8c9f2",
        "date": "2026-11-01T12:00:00.000Z",
        "productTitle": "Social Media Proxies",
        "productType": "isp",
        "productRegion": "us",
        "amount": 18,
        "originalAmount": 18,
        "discountAmount": 0,
        "discountPercentage": 0,
        "currency": "EUR",
        "status": "completed",
        "method": "card",
        "duration": 30,
        "invoiceAvailable": true
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 20,
      "total": 1,
      "totalPages": 1
    }
  }
}
GET/account/invoices

Paid orders that have an invoice

Scope: readLimit: Reads, 120 per hour

Parameters

pageinteger, queryoptional
Page number, starting at 1.Default 1.
limitinteger, queryoptional
Items per page, 1 to 100.Default 20.
  • •number is null until the invoice has been issued for the first time (the first PDF download issues it).

Errors: validation_error, plus the common ones.

Request
curl -s "https://birdproxies.com/api/v1/account/invoices" \
  -H "Authorization: Bearer $BP_API_KEY"
Response 200
{
  "success": true,
  "data": {
    "items": [
      {
        "id": "6650a1b2c3d4e5f6a7b8c9f2",
        "number": "INV-2026-11-0042",
        "date": "2026-11-01T12:00:00.000Z",
        "amount": 18,
        "currency": "EUR",
        "productTitle": "Social Media Proxies",
        "pdfUrl": "https://birdproxies.com/api/v1/account/invoices/6650a1b2c3d4e5f6a7b8c9f2"
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 20,
      "total": 1,
      "totalPages": 1
    }
  }
}
GET/account/invoices/{id}

Invoice PDF of one order

Scope: readLimit: Reads, 120 per hour

Parameters

idstring, pathrequired
Order id from GET /account/invoices.
  • •Answers with the PDF itself (Content-Type: application/pdf), not with the JSON envelope. Errors are JSON as usual.

Errors: not_found, conflict, upstream_error, plus the common ones.

Request
curl -s "https://birdproxies.com/api/v1/account/invoices/6650a1b2c3d4e5f6a7b8c9f2" \
  -H "Authorization: Bearer $BP_API_KEY" \
  -o invoice.pdf
Response 200, application/pdf
%PDF-1.7 ... (binary, Content-Type: application/pdf)
GET/proxies

Everything provisioned, in one call

Scope: readLimit: Reads, 120 per hour

ISP plans with credentials, residential accounts (cached usage) and the mobile account.

Request
curl -s "https://birdproxies.com/api/v1/proxies" \
  -H "Authorization: Bearer $BP_API_KEY"
Response 200
{
  "success": true,
  "data": {
    "isp": [
      {
        "id": "6650a1b2c3d4e5f6a7b8c9d0",
        "title": "Social Media Proxies",
        "region": "US",
        "quantity": 10,
        "expiresAt": "2026-12-01T12:00:00.000Z",
        "status": "active",
        "proxies": [
          {
            "ip": "203.0.113.10",
            "port": 8000,
            "username": "user123",
            "password": "pass456"
          }
        ],
        "credentialsStale": false,
        "proxyCount": 1
      }
    ],
    "residential": [
      {
        "id": "abc123",
        "name": "Residential",
        "kind": "main",
        "planType": null,
        "planTitle": null,
        "isMainAccount": true,
        "dataLimit": 10,
        "dataUsed": 2,
        "dataLeft": 8,
        "cached": true,
        "status": "active"
      }
    ],
    "mobile": null
  }
}

Products

The catalog with the prices the shop shows. Ordering stays in the dashboard checkout.

GET/products

Product catalog with prices and availability

Scope: readLimit: Reads, 120 per hour

The products of the shop with the prices it shows. Ordering stays in the dashboard checkout.

Parameters

typestring, queryoptional
Only products of this type.One of isp, residential, mobile, server, static-mobile.
  • •unit: ip_month = per IP per month, gb = per GB, month = per month.

Errors: validation_error, plus the common ones.

Request
curl -s "https://birdproxies.com/api/v1/products" \
  -H "Authorization: Bearer $BP_API_KEY"
Response 200
{
  "success": true,
  "data": {
    "products": [
      {
        "id": "693f1853011993b3c29200d2",
        "name": "Social Media Proxies",
        "type": "isp",
        "description": "Run multiple accounts without getting banned.",
        "pricing": {
          "currency": "EUR",
          "unit": "ip_month",
          "pricePerUnit": 1.8,
          "volumePricing": null
        },
        "regions": [
          {
            "code": "us",
            "name": "United States",
            "available": true
          },
          {
            "code": "it",
            "name": "Italy",
            "available": false
          }
        ],
        "stock": {
          "available": 275,
          "inStock": true
        }
      }
    ]
  }
}

ISP

Static ISP plans: credentials, proxy lists, IP swaps, password resets and auto-renew.

GET/isp

ISP plans with all credentials (classic)

Scope: readLimit: Reads, 120 per hour

Every active ISP plan including its proxy credentials. For large accounts prefer GET /isp/plans and fetch credentials per plan.

  • •credentialsStale: true means the live credentials could not be loaded and the last stored ones are shown.
Request
curl -s "https://birdproxies.com/api/v1/isp" \
  -H "Authorization: Bearer $BP_API_KEY"
Response 200
{
  "success": true,
  "data": {
    "plans": [
      {
        "id": "6650a1b2c3d4e5f6a7b8c9d0",
        "title": "Social Media Proxies",
        "region": "US",
        "quantity": 10,
        "expiresAt": "2026-12-01T12:00:00.000Z",
        "status": "active",
        "proxies": [
          {
            "ip": "203.0.113.10",
            "port": 8000,
            "username": "user123",
            "password": "pass456"
          }
        ],
        "credentialsStale": false,
        "authType": "user",
        "proxyCount": 1
      }
    ],
    "totalProxies": 1
  }
}
GET/isp/plans

ISP plans, without credentials

Scope: readLimit: Reads, 120 per hour
  • •autoRenew is null for plans that are not a subscription.
  • •pool: standard, pkc, mm, ipqs or earnapp (the special clean pools).
Request
curl -s "https://birdproxies.com/api/v1/isp/plans" \
  -H "Authorization: Bearer $BP_API_KEY"
Response 200
{
  "success": true,
  "data": {
    "plans": [
      {
        "id": "6650a1b2c3d4e5f6a7b8c9d0",
        "title": "Social Media Proxies",
        "region": "US",
        "quantity": 10,
        "status": "active",
        "createdAt": "2026-10-01T12:00:00.000Z",
        "expiresAt": "2026-12-01T12:00:00.000Z",
        "autoRenew": true,
        "subscription": true,
        "pool": "standard",
        "ipAuth": false
      }
    ],
    "total": 1
  }
}
GET/isp/plans/{planId}

One ISP plan with live credentials

Scope: readLimit: Reads, 120 per hour

Parameters

planIdstring, pathrequired
Plan id (24 hex characters) from GET /isp/plans.
  • •With IP authentication (ipAuth: true) username and password are empty strings.

Errors: not_found, plus the common ones.

Request
curl -s "https://birdproxies.com/api/v1/isp/plans/6650a1b2c3d4e5f6a7b8c9d0" \
  -H "Authorization: Bearer $BP_API_KEY"
Response 200
{
  "success": true,
  "data": {
    "id": "6650a1b2c3d4e5f6a7b8c9d0",
    "title": "Social Media Proxies",
    "region": "US",
    "quantity": 10,
    "status": "active",
    "createdAt": "2026-10-01T12:00:00.000Z",
    "expiresAt": "2026-12-01T12:00:00.000Z",
    "autoRenew": true,
    "subscription": true,
    "pool": "standard",
    "ipAuth": false,
    "authType": "user",
    "allowedIps": [],
    "credentialsStale": false,
    "proxyCount": 1,
    "proxies": [
      {
        "ip": "203.0.113.10",
        "port": 8000,
        "username": "user123",
        "password": "pass456"
      }
    ]
  }
}
GET/isp/plans/{planId}/proxies

Proxy list of one ISP plan (JSON or text)

Scope: readLimit: Reads, 120 per hour

Parameters

planIdstring, pathrequired
Plan id (24 hex characters) from GET /isp/plans.
formatstring, queryoptional
json (default) or txt (one ip:port:user:pass per line).One of json, txt.Default json.
  • •format=txt answers text/plain with one line per proxy, ip:port only for IP authentication.

Errors: not_found, validation_error, plus the common ones.

Request
curl -s "https://birdproxies.com/api/v1/isp/plans/6650a1b2c3d4e5f6a7b8c9d0/proxies" \
  -H "Authorization: Bearer $BP_API_KEY"
Response 200
{
  "success": true,
  "data": {
    "proxies": [
      {
        "ip": "203.0.113.10",
        "port": 8000,
        "username": "user123",
        "password": "pass456"
      }
    ],
    "count": 1
  }
}
POST/isp/plans/{planId}/swap

Swap all IPs of a plan

Scope: manageLimit: Changes, 30 per hour

Replaces every IP of the plan with fresh ones. Needs an active IP Refresh Pass; one swap per plan per pass period.

Parameters

planIdstring, pathrequired
Plan id (24 hex characters) from GET /isp/plans.
  • •The old IPs stop working as soon as this returns.
  • •payment_required: no active IP Refresh Pass. cooldown_active: already swapped this period, details.nextSwapAt says when the next swap is possible.
  • •conflict with details.reason: not_supported, multi_subnet, no_stock or swap_limit. Your pass is not used in those cases.

Errors: not_found, payment_required, cooldown_active, conflict, upstream_error, plus the common ones.

Request
curl -s -X POST "https://birdproxies.com/api/v1/isp/plans/6650a1b2c3d4e5f6a7b8c9d0/swap" \
  -H "Authorization: Bearer $BP_API_KEY"
Response 200
{
  "success": true,
  "data": {
    "proxies": [
      {
        "ip": "203.0.113.10",
        "port": 8000,
        "username": "user123",
        "password": "pass456"
      }
    ],
    "count": 1,
    "nextSwapAt": "2026-12-01T12:00:00.000Z"
  }
}
POST/isp/plans/{planId}/reset-password

New password for every IP of a plan

Scope: manageLimit: Changes, 30 per hour

Parameters

planIdstring, pathrequired
Plan id (24 hex characters) from GET /isp/plans.
  • •Not possible while the plan uses IP authentication (conflict, details.reason: ip_auth).

Errors: not_found, conflict, upstream_error, plus the common ones.

Request
curl -s -X POST "https://birdproxies.com/api/v1/isp/plans/6650a1b2c3d4e5f6a7b8c9d0/reset-password" \
  -H "Authorization: Bearer $BP_API_KEY"
Response 200
{
  "success": true,
  "data": {
    "proxies": [
      {
        "ip": "203.0.113.10",
        "port": 8000,
        "username": "user123",
        "password": "pass456"
      }
    ],
    "count": 1
  }
}
PUT/isp/plans/{planId}/auto-renew

Turn auto-renew on or off

Scope: manageLimit: Changes, 30 per hour

Off: the subscription ends at the end of the paid period. On: a pending cancellation is withdrawn.

Parameters

planIdstring, pathrequired
Plan id (24 hex characters) from GET /isp/plans.

Body (JSON)

enabledbooleanrequired
true = renew automatically, false = end at period end.
  • •Idempotent: setting the current state again answers changed: false.
  • •conflict for plans that are not a subscription, or when the subscription has already ended.

Errors: not_found, validation_error, conflict, upstream_error, plus the common ones.

Request
curl -s -X PUT "https://birdproxies.com/api/v1/isp/plans/6650a1b2c3d4e5f6a7b8c9d0/auto-renew" \
  -H "Authorization: Bearer $BP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"enabled":false}'
Response 200
{
  "success": true,
  "data": {
    "autoRenew": false,
    "changed": true,
    "nextRenewalAt": null,
    "endsAt": "2026-12-01T12:00:00.000Z"
  }
}
GET/isp/plans/{planId}/renewal

Renewal state of a plan

Scope: readLimit: Reads, 120 per hour

Parameters

planIdstring, pathrequired
Plan id (24 hex characters) from GET /isp/plans.
  • •amount is the next invoice including tax and discounts, null when it cannot be determined.

Errors: not_found, plus the common ones.

Request
curl -s "https://birdproxies.com/api/v1/isp/plans/6650a1b2c3d4e5f6a7b8c9d0/renewal" \
  -H "Authorization: Bearer $BP_API_KEY"
Response 200
{
  "success": true,
  "data": {
    "subscription": true,
    "autoRenew": true,
    "status": "active",
    "nextRenewalAt": "2026-12-01T12:00:00.000Z",
    "amount": 18,
    "currency": "EUR"
  }
}

Residential

Locations, data usage, proxy generation and sub-users.

GET/residential/locations

Available countries, optionally with cities

Scope: readLimit: Reads, 120 per hour

Parameters

citiesstring, queryoptional
true = include the city list for each country.One of true.
countrystring, queryoptional
Restrict the answer to one ISO country code.

Errors: upstream_error, plus the common ones.

Request
curl -s "https://birdproxies.com/api/v1/residential/locations?country=US" \
  -H "Authorization: Bearer $BP_API_KEY"
Response 200
{
  "success": true,
  "data": {
    "includeCities": false,
    "totalCountries": 1,
    "countries": [
      {
        "code": "US",
        "name": "United States"
      }
    ]
  }
}
GET/residential/usage

Data limit, used and remaining (GB)

Scope: readLimit: Reads, 120 per hour

Parameters

subUserIdstring, queryoptional
Report on a sub-user instead of the main account.
planTypestring, queryoptional
Which residential plan to report on when several exist.One of residential, residential-lite, residential-premium.
  • •hasAccount: false, needsSetup: true means nothing is provisioned yet.

Errors: not_found, upstream_error, plus the common ones.

Request
curl -s "https://birdproxies.com/api/v1/residential/usage" \
  -H "Authorization: Bearer $BP_API_KEY"
Response 200
{
  "success": true,
  "data": {
    "hasAccount": true,
    "dataLimit": 10,
    "dataUsed": 2.5,
    "dataLeft": 7.5,
    "provider": "birdproxies",
    "planType": "residential",
    "planTitle": "Residential"
  }
}
POST/residential/proxies

Generate residential proxy lines

Scope: readLimit: Proxy generation, 20 per hour

Generates up to 10000 lines per call. Split larger jobs into several calls.

Body (JSON)

proxyTypestringrequired
Protocol.One of http, socks5.
routingTypestringrequired
Rotating or sticky sessions.One of rotating, sticky.
generateAmountintegerrequired
How many lines, 1 to 10000.
countriesarray of objectrequired
Targets: [{ country, cities?, asns? }]. country is an ISO code or any.
subUserIdstringoptional
Generate for a sub-user.
planTypestringoptional
Which residential plan.One of residential, residential-lite, residential-premium.
ttlintegeroptional
Sticky session lifetime in seconds (300 to 86400, the standard pool caps at 3600).
customPoolstringoptional
Custom pool name.
regionstringoptional
Region (premium plans only).
asnstringoptional
One AS number for every country, for example "7922".
gatewaystringoptional
Entry gateway: eu, us or sg. Omit it to pick per country and caller location.One of eu, us, sg.
  • •Needs only the read scope: generating lines changes nothing on the account.
  • •partial: true with a warning when fewer lines than requested could be generated.

Errors: validation_error, not_found, conflict, upstream_error, plus the common ones.

Request
curl -s -X POST "https://birdproxies.com/api/v1/residential/proxies" \
  -H "Authorization: Bearer $BP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"proxyType":"http","routingType":"rotating","generateAmount":100,"countries":[{"country":"US"}]}'
Response 200
{
  "success": true,
  "data": {
    "proxies": [
      "residential.birdproxies.com:7777:pool-p1-cc-us:secret"
    ],
    "count": 1,
    "provider": "birdproxies",
    "format": "host:port:username:password"
  }
}
GET/residential/sub-users

Sub-users with live data balance

Scope: readLimit: Reads, 120 per hour
  • •Data amounts are GB. mainAccount is null without a residential account.

Errors: upstream_error, plus the common ones.

Request
curl -s "https://birdproxies.com/api/v1/residential/sub-users" \
  -H "Authorization: Bearer $BP_API_KEY"
Response 200
{
  "success": true,
  "data": {
    "subUsers": [
      {
        "id": "a1b2c3d4e5",
        "nickname": "scraper-1",
        "dataLimit": 5,
        "dataUsed": 1.25,
        "dataLeft": 3.75,
        "status": "active",
        "createdAt": "2026-11-01T09:30:00.000Z"
      }
    ],
    "mainAccount": {
      "dataLimit": 20,
      "dataUsed": 4,
      "dataLeft": 16
    },
    "total": 1
  }
}
POST/residential/sub-users

Create a sub-user from your data balance

Scope: manageLimit: Changes, 30 per hour

Body (JSON)

nicknamestringrequired
1 to 50 characters.
dataGbnumberrequired
GB moved from the main account to the sub-user (at least 0.01).
  • •The password is only returned here. conflict with details.availableGb when the balance is too small.

Errors: validation_error, conflict, upstream_error, plus the common ones.

Request
curl -s -X POST "https://birdproxies.com/api/v1/residential/sub-users" \
  -H "Authorization: Bearer $BP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"nickname":"scraper-1","dataGb":5}'
Response 201
{
  "success": true,
  "data": {
    "id": "a1b2c3d4e5",
    "nickname": "scraper-1",
    "dataLimit": 5,
    "dataUsed": 0,
    "dataLeft": 5,
    "status": "active",
    "createdAt": "2026-11-01T09:30:00.000Z",
    "password": "subpass789"
  }
}
GET/residential/sub-users/{id}

One sub-user with live data balance

Scope: readLimit: Reads, 120 per hour

Parameters

idstring, pathrequired
Sub-user id from GET /residential/sub-users.

Errors: not_found, upstream_error, plus the common ones.

Request
curl -s "https://birdproxies.com/api/v1/residential/sub-users/a1b2c3d4e5" \
  -H "Authorization: Bearer $BP_API_KEY"
Response 200
{
  "success": true,
  "data": {
    "id": "a1b2c3d4e5",
    "nickname": "scraper-1",
    "dataLimit": 5,
    "dataUsed": 1.25,
    "dataLeft": 3.75,
    "status": "active",
    "createdAt": "2026-11-01T09:30:00.000Z"
  }
}
PATCH/residential/sub-users/{id}

Rename a sub-user or change its data limit

Scope: manageLimit: Changes, 30 per hour

Parameters

idstring, pathrequired
Sub-user id from GET /residential/sub-users.

Body (JSON)

nicknamestringoptional
New name, 1 to 50 characters.
dataGbnumberoptional
New total data limit in GB. More takes the difference from the main account, less gives it back.
  • •Send at least one field. changed: false when nothing had to change.

Errors: not_found, validation_error, conflict, upstream_error, plus the common ones.

Request
curl -s -X PATCH "https://birdproxies.com/api/v1/residential/sub-users/a1b2c3d4e5" \
  -H "Authorization: Bearer $BP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"dataGb":8}'
Response 200
{
  "success": true,
  "data": {
    "id": "a1b2c3d4e5",
    "nickname": "scraper-1",
    "dataLimit": 8,
    "dataUsed": 1.25,
    "dataLeft": 6.75,
    "status": "active",
    "createdAt": "2026-11-01T09:30:00.000Z",
    "changed": true
  }
}
DELETE/residential/sub-users/{id}

Delete a sub-user and get its data back

Scope: manageLimit: Changes, 30 per hour

Parameters

idstring, pathrequired
Sub-user id from GET /residential/sub-users.
  • •The remaining data goes back to the main account (dataReturned, GB).

Errors: not_found, conflict, upstream_error, plus the common ones.

Request
curl -s -X DELETE "https://birdproxies.com/api/v1/residential/sub-users/a1b2c3d4e5" \
  -H "Authorization: Bearer $BP_API_KEY"
Response 200
{
  "success": true,
  "data": {
    "deleted": true,
    "dataReturned": 3.75
  }
}
GET/residential/sub-users/{id}/usage

Usage history of a sub-user

Scope: readLimit: Reads, 120 per hour

Parameters

idstring, pathrequired
Sub-user id from GET /residential/sub-users.
periodstring, queryoptional
Time range.One of 24h, 7d, 30d, all.Default 30d.

Errors: not_found, validation_error, upstream_error, plus the common ones.

Request
curl -s "https://birdproxies.com/api/v1/residential/sub-users/a1b2c3d4e5/usage" \
  -H "Authorization: Bearer $BP_API_KEY"
Response 200
{
  "success": true,
  "data": {
    "id": "a1b2c3d4e5",
    "period": "30d",
    "dataLimit": 5,
    "dataUsed": 1.25,
    "dataLeft": 3.75,
    "totalGb": 1.25,
    "series": [
      {
        "date": "2026-11-17",
        "gb": 0.4
      }
    ]
  }
}

Mobile

The mobile account, proxy generation and its password.

GET/mobile

Mobile account and its data balance

Scope: readLimit: Reads, 120 per hour
  • •credentialsStale: true on the account means the live numbers could not be loaded.
Request
curl -s "https://birdproxies.com/api/v1/mobile" \
  -H "Authorization: Bearer $BP_API_KEY"
Response 200
{
  "success": true,
  "data": {
    "hasAccount": true,
    "account": {
      "id": "mob123",
      "password": "secret",
      "dataLimit": 5,
      "dataUsed": 1,
      "dataLeft": 4,
      "status": "active",
      "createdAt": "2026-10-01T12:00:00.000Z"
    }
  }
}
POST/mobile/proxies

Generate mobile proxy lines

Scope: readLimit: Proxy generation, 20 per hour

One country per call. Supported: DE, GB, US, JP, AU.

Body (JSON)

proxyTypestringrequired
Protocol.One of http, socks5.
routingTypestringrequired
Rotating or sticky sessions.One of rotating, sticky.
generateAmountintegerrequired
How many lines, 1 to 10000.
countriesarray of objectrequired
Exactly one: [{ country }].
ttlintegeroptional
Sticky session lifetime in seconds (300 to 3600).
  • •Needs only the read scope.

Errors: validation_error, not_found, conflict, upstream_error, plus the common ones.

Request
curl -s -X POST "https://birdproxies.com/api/v1/mobile/proxies" \
  -H "Authorization: Bearer $BP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"proxyType":"http","routingType":"sticky","generateAmount":10,"countries":[{"country":"DE"}]}'
Response 200
{
  "success": true,
  "data": {
    "proxies": [
      "mobile.birdproxies.com:7777:user-cc-de:secret"
    ],
    "count": 1,
    "format": "host:port:username:password"
  }
}
POST/mobile/reset-password

New password for the mobile account

Scope: manageLimit: Changes, 30 per hour
  • •Every mobile line generated before stops working when this returns.

Errors: not_found, upstream_error, plus the common ones.

Request
curl -s -X POST "https://birdproxies.com/api/v1/mobile/reset-password" \
  -H "Authorization: Bearer $BP_API_KEY"
Response 200
{
  "success": true,
  "data": {
    "username": "mob123",
    "password": "newsecret"
  }
}

Servers

Dedicated servers and their power state. Passwords are never returned.

GET/servers

Dedicated servers

Scope: readLimit: Reads, 120 per hour
  • •status is the last known state. GET /servers/{planId} reads the live power state. Passwords are never returned.
Request
curl -s "https://birdproxies.com/api/v1/servers" \
  -H "Authorization: Bearer $BP_API_KEY"
Response 200
{
  "success": true,
  "data": {
    "servers": [
      {
        "id": "6650a1b2c3d4e5f6a7b8c9e1",
        "title": "AMD EPYC 8x16",
        "status": "running",
        "location": "Frankfurt",
        "os": "Windows Server 2022",
        "hostname": "srv-example",
        "primaryIp": "198.51.100.20",
        "ipv4Addresses": [
          "198.51.100.20"
        ],
        "ipv6Addresses": [],
        "username": "Administrator",
        "specs": {
          "vcpu": 8,
          "ramGb": 16,
          "diskGb": 160
        },
        "createdAt": "2026-10-05T08:00:00.000Z",
        "expiresAt": "2026-12-05T08:00:00.000Z",
        "subscription": true,
        "autoRenew": true
      }
    ],
    "total": 1
  }
}
GET/servers/{planId}

One server with live power state

Scope: readLimit: Reads, 120 per hour

Parameters

planIdstring, pathrequired
Server id (24 hex characters) from GET /servers.
  • •live: false means the live state could not be read and the stored state is shown.

Errors: not_found, plus the common ones.

Request
curl -s "https://birdproxies.com/api/v1/servers/6650a1b2c3d4e5f6a7b8c9e1" \
  -H "Authorization: Bearer $BP_API_KEY"
Response 200
{
  "success": true,
  "data": {
    "id": "6650a1b2c3d4e5f6a7b8c9e1",
    "title": "AMD EPYC 8x16",
    "status": "running",
    "location": "Frankfurt",
    "os": "Windows Server 2022",
    "hostname": "srv-example",
    "primaryIp": "198.51.100.20",
    "ipv4Addresses": [
      "198.51.100.20"
    ],
    "ipv6Addresses": [],
    "username": "Administrator",
    "specs": {
      "vcpu": 8,
      "ramGb": 16,
      "diskGb": 160
    },
    "createdAt": "2026-10-05T08:00:00.000Z",
    "expiresAt": "2026-12-05T08:00:00.000Z",
    "subscription": true,
    "autoRenew": true,
    "live": true
  }
}
POST/servers/{planId}/power

Start, stop or reboot a server

Scope: manageLimit: Changes, 30 per hour

Parameters

planIdstring, pathrequired
Server id (24 hex characters) from GET /servers.

Body (JSON)

actionstringrequired
What to do.One of start, stop, reboot.
  • •The action runs asynchronously; poll GET /servers/{planId} for the new state.

Errors: not_found, validation_error, upstream_error, plus the common ones.

Request
curl -s -X POST "https://birdproxies.com/api/v1/servers/6650a1b2c3d4e5f6a7b8c9e1/power" \
  -H "Authorization: Bearer $BP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"action":"reboot"}'
Response 200
{
  "success": true,
  "data": {
    "id": "6650a1b2c3d4e5f6a7b8c9e1",
    "action": "reboot",
    "accepted": true,
    "message": "Server is rebooting"
  }
}

AI assistant (MCP)

Prefer to ask in plain language? Claude, ChatGPT, Cursor and other AI tools can reach your account through our MCP server. You choose read only or read and change access when you connect, and it shares the rate limits of this API. Setup and the list of tools are on the AI agent integration page.

Missing an endpoint? Tell us on Discord
Create an API key

On this page

  • Overview
  • Quick start
  • Authentication
  • Scopes
  • Responses and errors
  • Rate limits
  • Endpoint reference
  • Account
  • Products
  • ISP
  • Residential
  • Mobile
  • Servers
  • AI assistant (MCP)
BirdProxies
BirdProxies

Fast, secure, reliable proxies. ISP, Residential, and Mobile, ready when you are.

Products

  • ISP Proxies
  • Residential Proxies
  • Sneaker Proxies
  • Ticket Proxies
  • Crypto Proxies
  • Social Media Proxies
  • Betting Proxies

Company

  • Pricing
  • Partners
  • Imprint
  • Terms

Resources

  • Blog
  • Docs
  • Glossary
  • Integration Guides
  • Compare Providers
  • FAQ
  • Changelog
  • Brand Assets

Connect

  • Dashboard
  • Sign Up
  • Contact

© 2026 BirdProxies. All rights reserved.

Cancel contracts hereWithdraw from contract here
PrivacyCookiesRefunds