VPIN RATINGS

Developer platform · v1

Connect your app
to the community.

Read centralized VPSDB ratings and publish user scores with separate application and user identities.

API operationalBase URL /api/v1
01

TWO IDENTITIES

Application first. User when needed.

Every ratings request requires a registered application key. Add a user credential when reading personal ratings or submitting a score.

ALWAYS REQUIRED

Application key

X-Application-Key: vpxa_…

Identifies and rate-limits the consuming application.

PERSONAL READS + WRITES

User credential

X-User-Key: vpxr_…

A static profile key, or an OAuth bearer token in Authorization.

Shell · aggregate read
curl https://vpinratings.com/api/v1/ratings/batch \
  -H 'X-Application-Key: vpxa_your_application_key' \
  -H 'Content-Type: application/json' \
  -d '{"itemIds":["-5yMpqSy"]}'
02

USER AUTHORIZATION

Browser OAuth + PKCE or device authorization

Users can create a static key in their profile. Applications can instead obtain an application-scoped bearer token through authorization code + PKCE or the device flow. Callback URLs are optional for applications that only use static keys or device authorization.

Browser authorization code + PKCE

  1. AuthorizeGET /api/v1/oauth/authorizeSend client_id, registered redirect_uri, state, and an S256 PKCE challenge.
  2. ExchangePOST /api/v1/oauth/tokenSend the application key plus the returned code, redirect URI, and PKCE verifier.
  3. CallAuthorization: Bearer vpxu_…The token is scoped to the application that requested it.

Cabinet and device flow

  1. StartPOST /api/v1/oauth/device/authorizeSend the application key. Show user_code, or render verification_uri_complete as a QR code.
  2. PollPOST /api/v1/oauth/tokenUse the device grant type, application key, and secret device_code. Respect interval and the authorization_pending or slow_down response.
  3. Protectdevice_code ≠ user_codeThe short code can only approve a request. Token retrieval requires the high-entropy device secret, which is stored only as a hash by VPIN Ratings.
03

RATING ENDPOINTS

Read the network. Manage one user.

POST/ratings/batchAPP REQUIRED

Return aggregate ratings for VPSDB entry IDs. Add a user credential to include that user’s ratings.

REQUEST BODY{ "itemIds": ["-5yMpqSy"] }
PUT/ratings/batchAPP + USER

Atomically synchronize up to 100 offline ratings. Any invalid rating, duplicate ID, or unknown VPSDB entry rejects the complete batch.

REQUEST BODY{ "ratings": [{ "itemId": "-5yMpqSy", "rating": 4.5 }] }
GET/ratingsAPP + USER

Return the authenticated user’s complete rating list, resolved against current VPSDB metadata.

POST/ratingsAPP + USER

Create or replace the user’s rating for a current VPSDB entry on the five-star scale. Ratings use half-star increments; aggregate responses are rounded to two decimal places.

REQUEST BODY{ "itemId": "-5yMpqSy", "rating": 4.5 }
PUBLIC

itemId means a canonical VPSDB entry ID. Administrative APIs remain excluded from the published contract.

OpenAPI 3.1 JSON →
04

API EXPLORER

Try the live API

Register an application first. User credentials are optional only for aggregate reads.

RESPONSEReady
Run a request to see the response.