# Authenticated proxy lease API
BASE_URL=https://parseshelf.com
AUTHORIZATION=Bearer $PARSESHELF_PROXY_TOKEN
GET /api/internal/v1/proxies/status
POST /api/internal/v1/proxies/leases
POST /api/internal/v1/proxies/leases/{lease_id}/feedback
DELETE /api/internal/v1/proxies/leases/{lease_id}
{"capability":"product","count":2,"ttl_seconds":300}
{"proxy_index":0,"outcome":"success","latency_ms":842}
Proxy integration
Authenticated Proxy Lease API.
Use a small authenticated lease API when another project needs a checked ParseShelf route. Capacity, expiry and feedback stay explicit; this is not an open proxy relay.
Lease quickstart
Check, lease, report, release.
Keep each request bounded and make the route outcome observable.
| Step | Request | Result |
|---|---|---|
| 1. Check | GET /api/internal/v1/proxies/status | Freshness, capability counts and full/degraded capacity |
| 2. Lease | POST /api/internal/v1/proxies/leases | Short-lived proxy URIs and zero-based proxy indexes |
| 3. Report | POST /api/internal/v1/proxies/leases/{id}/feedback | Success, timeout, blocked, network_error or bad_content |
| 4. Release | DELETE /api/internal/v1/proxies/leases/{id} | Routes return to the shared allocator immediately |
Guide
How to use this ParseShelf resource.
What the broker provides
Approved projects can request a short-lived lease over checked pool members for connect, search or product work. The response contains proxy URIs, observed latency and the capabilities recorded by the latest check.
The broker never fetches an arbitrary destination for the caller, never exposes an unauthenticated CONNECT endpoint and never returns browser-only routes. It is a bounded handoff of a checked route, not a public relay.
Lease lifecycle
Create a lease with a capability, count and TTL. Use the returned proxy_index values in your own client, send success or failure feedback, then release the lease when the work finishes. Expired leases are reclaimed on the next broker request.
Per-client limits bound active leases, proxy count and TTL. During a refresh gap the broker may reuse a retained successful route for a short capped lease; outside that reuse window it returns 503 instead of pretending capacity exists.
Feedback and quarantine
Send one feedback event per attempted route with success, timeout, blocked, network_error or bad_content. One recent failed route is temporarily suppressed for that client, so it does not consume the next lease again.
Keep the feedback outcome tied to the actual request and latency. Do not report success for a response that was blocked or malformed; the broker uses this signal to keep the shared pool useful.
Safe use
Use free public routes only for public, unauthenticated data. Never send account sessions, payment information, private customer payloads or internal network requests through them. Keep the bearer token in a secret manager or environment variable, never in a URL, source file or log.
The status response exposes full versus degraded capacity. Each client is also bounded to 60 authenticated API requests per minute by default; a rejected request returns 429 with Retry-After: 60. Treat 503 as a normal capacity response, back off with jitter and retry later rather than starting parallel lease storms.
Production checklist
Start with one small input and compare the delivered fields with the report, catalog or pipeline you actually need.
Keep the job ID, source URL, mode and run date with downstream exports so operators and developers can audit the same result.
Related pages
Continue the Amazon data workflow.
FAQ
Authenticated Proxy Lease API questions.
Is this an open proxy?
No. Every request requires an approved bearer token, destination fetching is never performed by the broker and the checked pool is capacity-limited.
How long does a lease last?
The client requests a TTL within its configured limit. Stale-pool leases are capped at five minutes and all leases expire automatically.
What happens when the pool is degraded?
The status endpoint reports ready_degraded and the broker may issue a smaller checked lease; when no usable route remains it returns 503.
Can I use browser sessions or private data?
No. Free public routes are for public, unauthenticated requests only; do not use them for logins, payments, private data or internal destinations.