Research ReviewPro+

AI-powered methodology review that scores survey design across four dimensions and provides actionable recommendations to improve research quality.

Dashboard endpoint — session authentication

These research-review endpoints are part of the in-app dashboard surface, not the public API-key surface. They authenticate via your logged-in Clerk session (the same session used by the web app) and cannot be called with an Authorization: Bearer YOUR_API_KEY header. There are no API-key scopes for these routes. The curl examples below assume a request made with valid session cookies.

Run Research Review

POST/api/dashboard/surveys/:id/research-review

Trigger a new AI-powered research review for a survey. The review analyzes methodology, structure, statistical validity, and respondent experience, returning an overall score and per-dimension breakdowns with recommendations.

Auth:Clerk session (dashboard)

Plan:Pro+or higher

Rate limit:5 per hour per org (POST only)

Path Parameters

Name	Type	Description
`id`	string	Survey ID (UUID)

Request Body

No request body required. Send an empty body or {}.

Example Request

# Session-authenticated (sends your logged-in dashboard cookies)
curl -X POST "https://surventrics.ai/api/v1/surveys/SURVEY_ID/research-review" \
  -H "Content-Type: application/json" \
  --cookie "__session=YOUR_SESSION_COOKIE"

Response

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "surveyId": "660e9500-f39c-52e5-b827-557766551111",
  "organizationId": "770ea600-049d-63f6-c938-668877662222",
  "requestedBy": "880fb700-159e-74g7-da49-779988773333",
  "overallScore": 74,
  "methodologyScore": 82,
  "structureScore": 70,
  "statisticsScore": 65,
  "respondentScore": 78,
  "reviewData": { "...": "full structured review (summary, per-dimension findings, recommendations)" },
  "summary": "Solid methodology with some structural improvements available.",
  "status": "completed",
  "createdAt": "2024-06-10T14:30:00.000Z",
  "recommendations": [
    {
      "id": "aa11bb22-cc33-dd44-ee55-ff6677889900",
      "reviewId": "550e8400-e29b-41d4-a716-446655440000",
      "priority": "high",
      "action": "Rephrase Q3 to 'To what extent do you agree or disagree that...'",
      "rationale": "The phrasing 'Don't you agree that...' introduces acquiescence bias.",
      "status": "pending",
      "dismissedReason": null,
      "resolvedAt": null,
      "createdAt": "2024-06-10T14:30:00.000Z"
    },
    {
      "id": "bb22cc33-dd44-ee55-ff66-778899001122",
      "reviewId": "550e8400-e29b-41d4-a716-446655440000",
      "priority": "medium",
      "action": "Consider splitting into two shorter surveys.",
      "rationale": "At 45 questions, expected completion rate drops below 60%.",
      "status": "pending",
      "dismissedReason": null,
      "resolvedAt": null,
      "createdAt": "2024-06-10T14:30:00.000Z"
    }
  ]
}

Response Fields

Name	Type	Description
`id`	string	Unique ID for this review (UUID)
`surveyId`	string	The survey that was reviewed
`organizationId`	string	Organization that owns the survey
`requestedBy`	string	ID of the user who triggered the review
`overallScore`	number	Aggregate quality score (0-100)
`methodologyScore`	number	Methodology dimension score (0-100)
`structureScore`	number	Structure dimension score (0-100)
`statisticsScore`	number	Statistics dimension score (0-100)
`respondentScore`	number	Respondent-experience dimension score (0-100)
`reviewData`	object	Full structured review payload (summary, per-dimension findings, and the raw recommendations the AI produced)
`summary`	string	Human-readable summary of the review
`status`	string	Review status (completed or dismissed)
`recommendations`	array	Persisted, individually-trackable recommendation rows (see Recommendation Fields below)
`createdAt`	string	ISO 8601 timestamp

Scoring Dimensions

Dimension	Score Range	Evaluates
`methodology`	0-100	Question bias, leading/loaded phrasing, double-barreled questions, scale design
`structure`	0-100	Question order, logical flow, survey length, section organization
`statistics`	0-100	Statistical power, sample size adequacy, measurability of outcomes
`respondent`	0-100	Respondent burden, clarity, accessibility, expected completion rate

Recommendation Fields

Name	Type	Description
`id`	string	Unique recommendation ID (UUID)
`reviewId`	string	ID of the review this recommendation belongs to
`priority`	string	high, medium, or low
`action`	string	The recommended action to take
`rationale`	string	Why this action is recommended
`status`	string	pending, accepted, or dismissed
`dismissedReason`	string	Reason supplied when dismissing the recommendation (null otherwise)
`resolvedAt`	string	ISO 8601 timestamp when the recommendation was accepted or dismissed (null while pending)
`createdAt`	string	ISO 8601 timestamp

Get Latest Research Review

GET/api/dashboard/surveys/:id/research-review

Returns the most recent research review for the survey. Response schema is identical to the POST response above.

Auth: Clerk session (dashboard)|

Plan:Pro+or higher

Rate limit:Not rate limited

Example Request

# Session-authenticated (sends your logged-in dashboard cookies)
curl -X GET "https://surventrics.ai/api/v1/surveys/SURVEY_ID/research-review" \
  --cookie "__session=YOUR_SESSION_COOKIE"

Error Codes

Code	Description
`review_not_found`	No review exists for this survey
`survey_not_found`	Survey does not exist

Accept or Dismiss Recommendation

PATCH/api/dashboard/surveys/:id/research-review

Update the status of a recommendation to indicate whether you have accepted it (and plan to act on it) or dismissed it.

Auth: Clerk session (dashboard)|

Plan:Pro+or higher

Rate limit:Not rate limited

Request Body

Name	Type	Description
`recommendationId`	string	ID of the recommendation to update (required)
`action`	string	accepted or dismissed (required)

Example Request

# Session-authenticated (sends your logged-in dashboard cookies)
curl -X PATCH "https://surventrics.ai/api/v1/surveys/SURVEY_ID/research-review" \
  --cookie "__session=YOUR_SESSION_COOKIE" \
  -H "Content-Type: application/json" \
  -d '{
    "recommendationId": "rec-a1b2c3d4",
    "action": "accepted"
  }'

Response

{
  "recommendationId": "rec-a1b2c3d4",
  "status": "accepted",
  "updatedAt": "2024-06-10T15:00:00Z"
}

Error Codes

Code	Description
`recommendation_not_found`	Recommendation ID does not exist
`invalid_action`	Action must be `accepted` or `dismissed`

Recommendation Workflow

A typical workflow for using research reviews:

Run a review — POST to generate a new review after creating or updating your survey.
Read the results — GET to retrieve the scores and recommendations.
Triage recommendations — For each recommendation, PATCH to accept or dismiss it.
Implement accepted fixes — Update your survey questions based on the accepted suggestions.
Re-run the review — POST again to verify improvements and track score changes.

Example: Full Review Cycle

// JavaScript example
async function reviewAndFix(surveyId) {
  // 1. Run a new review
  const review = await fetch(
    `https://surventrics.ai/api/v1/surveys/${surveyId}/research-review`,
    {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${API_KEY}`,
        'Content-Type': 'application/json'
      }
    }
  ).then(r => r.json());

  console.log(`Overall score: ${review.overallScore}/100`);

  // 2. Process high-severity recommendations
  for (const rec of review.recommendations) {
    if (rec.severity === 'high') {
      console.log(`[${rec.dimension}] ${rec.title}`);
      console.log(`  Fix: ${rec.suggestedFix}`);

      // 3. Accept the recommendation
      await fetch(
        `https://surventrics.ai/api/v1/surveys/${surveyId}/research-review`,
        {
          method: 'PATCH',
          headers: {
            'Authorization': `Bearer ${API_KEY}`,
            'Content-Type': 'application/json'
          },
          body: JSON.stringify({
            recommendationId: rec.id,
            action: 'accepted'
          })
        }
      );
    }
  }
}