REST API

Everything the dashboard does, as HTTP. Create proxy users, reset passwords, read your balances and usage, and generate proxy lists from your own scripts, authenticated with an API key rather than a browser session.

Authentication

Create a key under Settings → API keys in your dashboard. It is shown once, at creation: we store only a hash, so we cannot show it again, and a key you lose is a key you revoke and replace. Send it as a bearer token on every request.

curl -H "Authorization: Bearer avo_live_EXAMPLEEXAMPLEEXAMPLEEXAMPLEEXAMPLEEXAMPLE" \
  https://www.avocadoproxies.com/api/v1/me

Every key starts with avo_live_ followed by 32 random bytes. You may hold up to 10 active keys; revoking one takes effect immediately.

Scopes

Scopes are independent and there is no hierarchy: a key with generate cannot read your account, and a key made for one job cannot quietly do another. Give each integration the narrowest set that works.

• read: Read your account, balances and usage
• proxies: Create, update and rotate proxy credentials, and reveal their passwords
• generate: Generate proxy lists from a credential

Conventions

• Base URL: https://www.avocadoproxies.com/api/v1
• Every JSON response is either {"ok":true,"data":…} or {"ok":false,"error":{"code","message"}}. Check ok, not the shape of the body.
• Every response carries Cache-Control: private, no-store. Nothing we return may be held in a shared cache.
• Bearer routes ignore the session cookie entirely, so there is no CSRF token to send and no origin to match.

Rate limits

A budget of 600 requests a minute, per key; the call that reaches it is the one refused. That answers 429 with AVO_TOO_MANY_REQUESTS and a Retry-After header in seconds; wait that long rather than retrying immediately. The budget is per key, so a busy worker slows down that worker and nothing else on your account.

Your ACCOUNT has a second budget of 1200 requests a minute across every key it holds, so a fleet of keys is not a way around the figure above. It is set well clear of two or three busy integrations running at once.

Two endpoints are additionally bounded per ACCOUNT, and share one budget with the dashboard: GET /proxies/{id}/secret and POST /generate both reveal a password, so both spend one of 60 reveals an hour and both leave a row in your audit trail. Generate a long list once instead of a short one in a loop.

Endpoints

curl -H "Authorization: Bearer avo_live_EXAMPLEEXAMPLEEXAMPLEEXAMPLEEXAMPLEEXAMPLE" \
  https://www.avocadoproxies.com/api/v1/me

curl -H "Authorization: Bearer avo_live_EXAMPLEEXAMPLEEXAMPLEEXAMPLEEXAMPLEEXAMPLE" \
  https://www.avocadoproxies.com/api/v1/proxies

curl -X POST -H "Authorization: Bearer avo_live_EXAMPLEEXAMPLEEXAMPLEEXAMPLEEXAMPLEEXAMPLE" \
  -H "Content-Type: application/json" \
  -d '{"kind":"RESIDENTIAL","label":"scraper"}' \
  https://www.avocadoproxies.com/api/v1/proxies

curl -X PATCH -H "Authorization: Bearer avo_live_EXAMPLEEXAMPLEEXAMPLEEXAMPLEEXAMPLEEXAMPLE" \
  -H "Content-Type: application/json" \
  -d '{"enabled":false}' \
  https://www.avocadoproxies.com/api/v1/proxies/cmxk0ph2t0001qz8yv1example

curl -X POST -H "Authorization: Bearer avo_live_EXAMPLEEXAMPLEEXAMPLEEXAMPLEEXAMPLEEXAMPLE" \
  https://www.avocadoproxies.com/api/v1/proxies/cmxk0ph2t0001qz8yv1example/rotate

curl -H "Authorization: Bearer avo_live_EXAMPLEEXAMPLEEXAMPLEEXAMPLEEXAMPLEEXAMPLE" \
  https://www.avocadoproxies.com/api/v1/proxies/cmxk0ph2t0001qz8yv1example/secret

curl -H "Authorization: Bearer avo_live_EXAMPLEEXAMPLEEXAMPLEEXAMPLEEXAMPLEEXAMPLE" \
  "https://www.avocadoproxies.com/api/v1/usage?days=7"

curl -H "Authorization: Bearer avo_live_EXAMPLEEXAMPLEEXAMPLEEXAMPLEEXAMPLEEXAMPLE" \
  "https://www.avocadoproxies.com/api/v1/usage/live?minutes=15"

curl -X POST -H "Authorization: Bearer avo_live_EXAMPLEEXAMPLEEXAMPLEEXAMPLEEXAMPLEEXAMPLE" \
  -H "Content-Type: application/json" \
  -d '{"proxyId":"cmxk0ph2t0001qz8yv1example","count":100,"format":"host:port:user:pass","country":"de","session":"sticky","ttl":30}' \
  https://www.avocadoproxies.com/api/v1/generate > proxies.txt

Generating lists

POST /generate takes a proxy user and returns up to 10,000 lines built exactly as the dashboard's Generate tab builds them; the same code produces both. Supply format as one of host:port:user:pass, user:pass@host:port, host:port@user:pass, user:pass:host:port, http://user:pass@host:port, and session as rotating or sticky. A sticky request also takes ttl in minutes, up to the ceiling of the proxy user's product (55 minutes on residential and mobile, 115 minutes on premium residential), and every line gets its own session id so the list holds separate sessions rather than one shared address.

Targeting is validated against the product the proxy user belongs to: asking for a city on a product that offers country targeting only is refused with AVO_TARGETING_NOT_SUPPORTED rather than silently widened. country is a two-letter code from the list the dashboard offers (de, not germany), and a state or city has to be one of ours too; anything else is refused rather than turned into lines the gateway would reject. The login in each line is your own, e.g. avo_7f3c2a-cc-de-sid-a1b2c3-ttl-30.

Error codes

These are the codes this API returns. The gateway your proxy traffic goes through has its own set; see the error reference for those.