API Reference

Complete reference for all ReviewX REST API endpoints. All authenticated requests must include an Authorization: Bearer {token} header.

BASE URLhttp://localhost:3001/raybags/v1/review-crawler

Users

POST/loginNo auth

Authenticate with email and password. Returns a JWT Bearer token and the full user object.

Request Fields

Field	Type	Description
`email`*	string	Registered account email address.
`password`*	string	Account password (min 8 characters).

* required

JSON Response

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "user": {
    "_id": "64a1f...",
    "name": "Jane Smith",
    "email": "[email protected]",
    "isAdmin": false,
    "isSuperUser": false,
    "isSubscribed": true,
    "DocumentCount": 142
  }
}

POST/create-userNo auth

Request Fields

Field	Type	Description
`name`*	string	Full display name.
`email`*	string	Unique email address.
`password`*	string	Secure password (min 8 chars).
`adminSecret`	string	Optional server secret to elevate to admin role.

* required

JSON Response

{
  "message": "User created successfully.",
  "user": {
    "_id": "64b2e...",
    "name": "Jane Smith",
    "email": "[email protected]",
    "isAdmin": false
  }
}

GET/get-userBearer token required

Retrieve the full profile for the currently authenticated user, including profile list and document count.

JSON Response

{
  "_id": "64a1f...",
  "name": "Jane Smith",
  "email": "[email protected]",
  "isAdmin": false,
  "isSuperUser": false,
  "isSubscribed": true,
  "userId": "usr_abc123",
  "DocumentCount": 142,
  "profiles": [
    {
      "_id": "64c3d...",
      "reviewSiteSlug": "booking-com",
      "name": "The Grand Hotel",
      "url": "https://booking.com/...",
      "uuid": "prop_xyz",
      "propertyType": "hotel",
      "propertyReviewCount": 312,
      "enabled": true
    }
  ]
}

Profiles

POST/create-{site}-profileBearer token required

Create a property profile for the given site. Replace {site} with: booking, agoda, expedia, opentable, trip, or google.

Request Fields

Field	Type	Description
`frontFacingUrl`*	string	The property's public URL on the review platform.
`name`*	string	Human-readable name for this profile.

* required

JSON Response

{
  "message": "Profile created.",
  "profile": {
    "_id": "64c3d...",
    "reviewSiteSlug": "booking-com",
    "name": "The Grand Hotel",
    "url": "https://booking.com/hotel/...",
    "uuid": "prop_xyz",
    "enabled": true
  }
}

DELETE/delete-profile/:idBearer token required

Delete a property profile by its ID. Associated review documents are not automatically removed — use delete-profile-and-docs for a full purge.

JSON Response

{
  "message": "Profile deleted successfully.",
  "deletedId": "64c3d..."
}

Reviews

POST/generate-{site}-reviewsBearer token required

Trigger a review crawl for the given platform. Replace {site} with the relevant slug. The crawler fetches all available reviews for the property.

Request Fields

Field	Type	Description
`frontFacingUrl`*	string	The property's public URL on the review platform.

* required

JSON Response

{
  "message": "Crawl complete.",
  "inserted": 47,
  "skipped": 12,
  "total": 59
}

GET/get-user-docsBearer token required

Retrieve a paginated list of all review documents belonging to the authenticated user.

Request Fields

Field	Type	Description
`page`	number	Page number (default: 1).
`limit`	number	Results per page (default: 20, max: 100).

* required

JSON Response

{
  "page": 1,
  "limit": 20,
  "total": 142,
  "docs": [
    {
      "_id": "64d4e...",
      "reviewSiteSlug": "booking-com",
      "author": "John D.",
      "title": "Fantastic stay!",
      "rating": 9.2,
      "reviewDate": "2025-11-14",
      "country": "US",
      "tripType": "Leisure",
      "reviewBody": "The staff were incredibly helpful...",
      "language": "en"
    }
  ]
}

GET/get-document/:idBearer token required

Retrieve a single review document by its database ID. Includes subratings and property response if available.

JSON Response

{
  "_id": "64d4e...",
  "reviewSiteSlug": "booking-com",
  "uuid": "rev_abc",
  "author": "John D.",
  "title": "Fantastic stay!",
  "rating": 9.2,
  "reviewDate": "2025-11-14",
  "country": "US",
  "tripType": "Leisure",
  "reviewBody": "The staff were incredibly helpful...",
  "propertyName": "The Grand Hotel",
  "stayDate": "2025-11-10",
  "language": "en",
  "propertyResponse": null,
  "subratings": {
    "cleanliness": 9.0,
    "comfort": 9.5,
    "location": 8.0
  }
}

DELETE/delete-document/:idBearer token required

Permanently delete a single review document by its ID.

JSON Response

{
  "message": "Document deleted.",
  "deletedId": "64d4e..."
}

GET/search-docsBearer token required

Full-text search across your review documents. Optionally filter by platform slug. Returns paginated matching results.

Request Fields

Field	Type	Description
`q`*	string	Search query string.
`slug`	string	Filter to a specific platform slug (e.g. booking-com).
`page`	number	Page number (default: 1).
`limit`	number	Results per page (default: 20).

* required

JSON Response

{
  "query": "breakfast buffet",
  "page": 1,
  "total": 8,
  "docs": [
    {
      "_id": "64d4e...",
      "title": "Great breakfast buffet selection",
      "rating": 8.8,
      "reviewSiteSlug": "booking-com",
      "reviewDate": "2025-10-02"
    }
  ]
}

System

GET/healthBearer token required

Returns server health status, uptime, and environment information.

JSON Response

{
  "status": "ok",
  "uptime": 86423,
  "environment": "production",
  "version": "2.4.1"
}

GET/metricsBearer token required

Returns system-wide metrics including request counts, error rates, and crawl statistics. Admin access recommended.

JSON Response

{
  "requestsTotal": 142380,
  "errorsTotal": 312,
  "crawlsToday": 48,
  "docsInsertedToday": 1204,
  "activeUsers": 87
}

GET/instanceBearer token required

Returns the current server instance identifier and load balancer node info.

JSON Response

{
  "instanceId": "node-3",
  "region": "us-east-1",
  "lbStatus": "healthy"
}

Integrations

ReviewX integrates with any system that can make HTTP requests. Use the Bearer token from POST /login to authenticate webhooks, cron jobs, or third-party automation tools. For platform-specific URLs, paste the property page link directly — the crawler handles URL normalisation internally.

Crawling

Crawls are triggered per-property via POST /generate-{site}-reviews. There is no fixed rate limit, but please crawl respectfully — excessive concurrent requests may result in temporary throttling. Each crawl session deduplicates reviews automatically, so re-crawling a profile is safe and incremental.

Analytics

Use the GET /get-user-docs and GET /search-docs endpoints to power custom analytics dashboards. Each review document includes language, country, trip type, rating, subratings, and a full review body — sufficient for sentiment analysis, trend detection, and competitive benchmarking.