Proxy Gateway

AI agent instructions

Read the Notte skill and follow its setup instructions when setting up Notte or building browser automation. This is the shared source for CLI setup, authentication, and the browser-to-code workflow.

Overview

The proxy gateway at proxy.notte.cc gives you Notte’s residential proxies outside a browser session. Use it from curl, an HTTP client, a scraper, or your own proxy, such as a secret proxy that should exit from the same IP as your session. You mint a short-lived credential with your API key, then use it as a standard proxy URL. Browser sessions do not need this: their built-in proxies are on by default.

Mint a credential

Call POST /proxies/gateway/credentials with your API key. The SDKs have no method for this endpoint, so call it over HTTP.

curl -X POST https://api.notte.cc/proxies/gateway/credentials \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"country": "us", "sticky_session": "checkout-4821"}'

All body fields are optional. Any other field is rejected.

Field	Description
`country`	Two-letter country code, such as `us`. Without `country` or `city`, traffic exits in the US.
`city`	City id, such as `new.york`. Takes precedence over `country`. An unsupported city returns `400` with examples of supported ones.
`sticky_session`	1 to 64 letters, digits or hyphens. Pins every connection made with the credential to one residential exit. See Share an exit IP with a session.

{
  "username": "country-us_sticky-checkout-4821.eyJlIjoi...",
  "password": "kq3V...",
  "expires_at": "2026-11-03T21:00:00Z",
  "proxy_url_tls": "https://country-us_sticky-checkout-4821.eyJlIjoi...:kq3V...@proxy.notte.cc:443",
  "proxy_url_plain": "http://country-us_sticky-checkout-4821.eyJlIjoi...:kq3V...@proxy.notte.cc:3128"
}

Field	Description
`proxy_url_tls`	`https://user:pass@proxy.notte.cc:443`. Your client connects to the gateway over TLS. Use it when your client supports HTTPS proxies.
`proxy_url_plain`	`http://user:pass@proxy.notte.cc:3128`. For clients that only support HTTP proxies. The credential then travels unencrypted to the gateway, even for `https://` sites, and anyone on the network path can reuse it until it expires. Prefer `proxy_url_tls`.
`username`, `password`	The same credential, for clients that take them separately.
`expires_at`	When the credential stops working.

Send requests through the gateway

Both proxy URLs work for https:// sites, through a CONNECT tunnel, and for plain http:// URLs. With curl:

# Mint a credential, then send a request through it
PROXY_URL=$(curl -sf -X POST https://api.notte.cc/proxies/gateway/credentials \
  -H "Authorization: Bearer $NOTTE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"country": "us"}' | jq -er '.proxy_url_tls') || {
  echo "could not mint a gateway credential" >&2
  exit 1
}

curl --proxy "$PROXY_URL" https://api.ipify.org

From Python or Node.js:

import os

import httpx

credential = (
    httpx.post(
        "https://api.notte.cc/proxies/gateway/credentials",
        headers={"Authorization": f"Bearer {os.environ['NOTTE_API_KEY']}"},
        json={"country": "us"},
    )
    .raise_for_status()
    .json()
)

# Every request made with this client exits from a residential IP in the US
with httpx.Client(proxy=credential["proxy_url_tls"]) as http:
    print(http.get("https://api.ipify.org").text)

import https from 'node:https';

const response = await fetch('https://api.notte.cc/proxies/gateway/credentials', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.NOTTE_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ country: 'us' }),
});
if (!response.ok) throw new Error(`Minting failed: HTTP ${response.status}`);
const credential = (await response.json()) as { proxy_url_tls: string };

// Requests made with this agent exit from a residential IP in the US (Node.js 24.5+)
const agent = new https.Agent({ proxyEnv: { HTTPS_PROXY: credential.proxy_url_tls } });
https.get('https://api.ipify.org', { agent }, (res) => {
  res.setEncoding('utf8');
  res.on('data', (chunk: string) => process.stdout.write(chunk));
});

In Node.js, the proxyEnv agent option needs Node.js 24.5 or later and applies to https.request and https.get, not to fetch. Mint the credential with a sticky_session, then start a browser session with the same sticky_session, and the same country or city, on its notte proxy. Connections made with the credential and the session’s own traffic then exit from the same IP. The secret proxy guide shows the full setup.

Lifetime and renewal

A credential is valid for your plan’s maximum session duration, up to 24 hours. You cannot choose a different lifetime. Reuse one credential for every request until it expires, then mint a new one before expires_at. An expired credential is rejected with 407.

Billing and limits

Traffic through the gateway is billed as built-in proxy bandwidth, at the built-in proxy rate, to the workspace whose API key minted the credential.

Status	Meaning
`407`	The credential is missing, invalid or expired.
`402`	The workspace has no remaining balance, or its plan’s proxy spend limit is reached.
`403`	The target is a private, loopback or link-local address.
`429`	Too many credentials minted, or too many connections open at once or opened too quickly. Retry with backoff.
`503`	From the mint endpoint: credentials or city targeting are temporarily unavailable. Retry, or omit `city`.

Getting Started

Sessions

Authentication

Functions

Web API

Guides

Proxy Gateway

Overview

Mint a credential

Send requests through the gateway

Lifetime and renewal

Billing and limits

​Overview

​Mint a credential

​Send requests through the gateway

​Share an exit IP with a session

​Lifetime and renewal

​Billing and limits

Overview

Mint a credential

Send requests through the gateway

Share an exit IP with a session

Lifetime and renewal

Billing and limits