API fundamentals

All authored examples use the API hostname declared by the first servers entry in the root OpenAPI document:

https://api.proxyrequest.com/api/v1

The documentation resolves OpenAPI server variables during the build, so examples and generated API Reference stay on the same host. Update servers[0] in openapi.yaml when the deployment API hostname changes.

Authentication schemes

JWT bearer

Use the login and refresh operations for an account session. Send the access token as Authorization: Bearer YOUR_JWT.

Static API key

Create a key through the API-key resource and send it as Authorization: Static YOUR_API_KEY for server-to-server integrations.

JWT

curl 'https://api.proxyrequest.com/api/v1/profile' \
  --header 'Authorization: Bearer YOUR_JWT' \
  --header 'Accept: application/json'

Static key

curl 'https://api.proxyrequest.com/api/v1/profile' \
  --header 'Authorization: Static YOUR_API_KEY' \
  --header 'Accept: application/json'

API keys are backend credentials

Do not put a static API key in a browser bundle or expose it to reseller customers. Route customer actions through your authenticated backend.

JSON requests

Send JSON for request bodies unless an operation explicitly documents another media type:

Content-Type: application/json
Accept: application/json

UUID-like resource identifiers should be treated as opaque strings. Do not parse business meaning from them.

Pagination

List operations commonly accept limit and offset and return a page envelope:

{
  "count": 125,
  "next": "https://api.proxyrequest.com/api/v1/users?limit=25&offset=25",
  "previous": null,
  "results": []
}

Follow next until it is null when a complete export is required. For an interactive UI, keep the selected limit stable and store the current offset in view state.

Error model

Errors can contain a top-level message, non-field validation errors, a localization key, or dynamic field arrays:

{
  "non_field_errors": ["The request could not be processed."],
  "translation": "errors.request.invalid"
}

Status	Integration response
400	Show field-safe validation feedback and preserve the submitted form
401	Refresh a JWT once or replace an invalid key; do not retry indefinitely
403	Stop and check account role or resource ownership
404	Verify both the identifier and authenticated account scope
429	Respect retry guidance and reduce request rate
5xx	Retry bounded, idempotent reads with backoff and record the request context

Catalog caching

Cache packages and location catalogs in your application, but do not hard-code a universal TTL that the API does not publish. Refresh on package changes, administrative invalidation, or a cache miss. Do not cache balance-changing responses as catalog data.

Browse exact parameters and responses in the generated API Reference or download the OpenAPI YAML.