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.
•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.
Scope
Allows
read
View the account, plans, usage, invoices and credentials, and generate proxy lists.
manage
Everything 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:
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.
Code
HTTP
Meaning
missing_api_key
401
No API key sent. Use Authorization: Bearer bp_live_....Can happen on every endpoint.
invalid_api_key
401
The API key is unknown or was revoked.Can happen on every endpoint.
api_key_expired
401
The API key has expired.Can happen on every endpoint.
ip_not_allowed
403
This key is not allowed from your IP address.Can happen on every endpoint.
insufficient_scope
403
This key does not have the scope this endpoint needs.Can happen on every endpoint.
validation_error
400
The request is invalid. See details.fields.
not_found
404
Not found.
conflict
409
The resource is busy or already in the requested state.
cooldown_active
429
This action is on cooldown.
rate_limited
429
Rate limit reached. Retry after the time in Retry-After.Can happen on every endpoint.
payment_required
402
This action needs a purchase first (for example an IP Refresh Pass).
internal_error
500
Something went wrong on our side. Quote the request id to support.Can happen on every endpoint.
upstream_error
502
The 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.
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.
Bucket
Limit
Counts
Reads (apiRead)
120 per 1 hour
GET requests
Changes (apiWrite)
30 per 1 hour
POST, PUT, PATCH and DELETE requests that change something
Proxy generation (proxyGenerate)
20 per 1 hour
POST /residential/proxies and POST /mobile/proxies
Every response tells you where you stand:
Header
Meaning
X-Request-Id
Unique id of this request (req_...). Sent on every response, also on errors. Quote it to support.
X-RateLimit-Limit
Requests allowed in the current window of the bucket.
X-RateLimit-Remaining
Requests left in the current window.
X-RateLimit-Reset
Unix time (seconds) when the window resets.
X-RateLimit-Bucket
Which bucket the request counted against: apiRead, apiWrite or proxyGenerate.
Retry-After
Seconds 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
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.
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.