Survey Health Check

Analyze a set of survey questions for common quality issues. This is a public endpoint — no API key or authentication is required.

Request Body

Send a JSON body with a mode and a single content string. The analyzer parses questions out of the content according to the selected mode. Content is limited to 100KB and at most 50 questions are analyzed.

Modes

Example Request (Plain Text)

curl -X POST "https://surventrics.ai/api/health-check/analyze" \
  -H "Content-Type: application/json" \
  -d '{
    "mode": "text",
    "content": "1. Do you agree that our product is the best?\n2. How often do you use our product and are you satisfied?\n3. What is your age and income level?"
  }'

Example Request (Google Forms CSV)

curl -X POST "https://surventrics.ai/api/health-check/analyze" \
  -H "Content-Type: application/json" \
  -d '{
    "mode": "google_forms_csv",
    "content": "Timestamp,How satisfied are you with our product and service?,What is your age and income level?\n2024-01-01 09:00:00,Very satisfied,32"
  }'

Response

{
  "overallScore": 42,
  "questionCount": 3,
  "questions": [
    {
      "index": 0,
      "text": "Do you agree that our product is the best on the market?",
      "issues": [
        {
          "questionIndex": 0,
          "questionText": "Do you agree that our product is the best on the market?",
          "type": "leading_question",
          "severity": "high",
          "message": "This question uses leading language ('the best') that pushes respondents toward agreement.",
          "suggestion": "How would you compare our product to alternatives you have used?"
        }
      ]
    },
    {
      "index": 1,
      "text": "How often do you use our product and are you satisfied?",
      "issues": [
        {
          "questionIndex": 1,
          "questionText": "How often do you use our product and are you satisfied?",
          "type": "double_barreled",
          "severity": "high",
          "message": "This question asks about two things at once (usage frequency and satisfaction). Respondents cannot answer accurately.",
          "suggestion": "Split into two questions: 'How often do you use our product?' and 'How satisfied are you with our product?'"
        }
      ]
    },
    {
      "index": 2,
      "text": "What is your age and income level?",
      "issues": []
    }
  ],
  "issues": [
    {
      "questionIndex": 0,
      "questionText": "Do you agree that our product is the best on the market?",
      "type": "leading_question",
      "severity": "high",
      "message": "This question uses leading language ('the best') that pushes respondents toward agreement.",
      "suggestion": "How would you compare our product to alternatives you have used?"
    },
    {
      "questionIndex": 1,
      "questionText": "How often do you use our product and are you satisfied?",
      "type": "double_barreled",
      "severity": "high",
      "message": "This question asks about two things at once (usage frequency and satisfaction). Respondents cannot answer accurately.",
      "suggestion": "Split into two questions: 'How often do you use our product?' and 'How satisfied are you with our product?'"
    }
  ],
  "strengths": [
    "33% of questions have no detected issues.",
    "Short and focused survey, which can improve completion rates."
  ],
  "importSignals": {
    "typeConfidence": 0.95,
    "piiDetected": false,
    "ambiguities": []
  }
}

Response Fields

issues[]

Array of detected quality issues, ordered by severity:

Issue Types

Errors & Availability

On error, the endpoint returns a JSON body with an error field. Validation and rate-limit failures return a string message; the availability kill-switch returns a structured { code, message } object.

503 Kill-Switch

When the health_check_public feature flag is turned off, the endpoint short-circuits before doing any work and responds with a 503:

{
  "error": {
    "code": "unavailable",
    "message": "Health check is temporarily unavailable."
  }
}

Use Cases

Quick Quality Check

Run a health check before launching any survey to catch common pitfalls:

// JavaScript example
async function checkSurveyHealth(text) {
  const response = await fetch(
    'https://surventrics.ai/api/health-check/analyze',
    {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ mode: 'text', content: text })
    }
  );

  const data = await response.json();

  if (data.overallScore < 70) {
    console.log('Survey needs improvement.');
    data.issues
      .filter(i => i.severity === 'high')
      .forEach(i => console.log(`  [${i.type}] ${i.message}`));
  } else {
    console.log('Survey looks good! Score:', data.overallScore);
    data.strengths.forEach(s => console.log('  +', s));
  }
}

CI/CD Integration

Add a health check step to your deployment pipeline to enforce minimum quality standards:

# Shell script example
SCORE=$(curl -s -X POST "https://surventrics.ai/api/health-check/analyze" \
  -H "Content-Type: application/json" \
  -d @survey.json | jq '.overallScore')

if [ "$SCORE" -lt 60 ]; then
  echo "Survey quality score too low: $SCORE/100"
  exit 1
fi