Skip to main content

Quickstart

Get started with Helix Fact Checking in under 5 minutes. This guide walks you through submitting your first fact-check request and retrieving results.

Prerequisites​

Before you begin, you'll need:

  • A Helix API key (see API Reference)
  • A command-line terminal or API client
  • Text content you want to fact-check

Step 1: Submit a Fact-Check Request​

Submit text for fact-checking. You can optionally provide source URLs for verification.

curl -X POST https://api.feeds.onhelix.ai/fact-check \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "The Eiffel Tower was completed in 1889 and stands 324 meters tall. It was designed by Gustave Eiffel for the 1889 World Fair.",
    "sourceUrls": [
      "https://www.toureiffel.paris/en/the-monument",
      "https://en.wikipedia.org/wiki/Eiffel_Tower"
    ]
  }'

Response:

{
  "success": true,
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "text": "The Eiffel Tower was completed in 1889...",
    "sourceUrls": [
      "https://www.toureiffel.paris/en/the-monument",
      "https://en.wikipedia.org/wiki/Eiffel_Tower"
    ],
    "status": "pending",
    "finalDetermination": null,
    "finalConfidence": null,
    "createdAt": "2024-01-15T10:30:00.000Z"
  }
}

Save the id value—you'll need it to check the results.

What happens next?

  • The system extracts individual factual claims from your text
  • Each claim is verified against the provided sources
  • Evidence is gathered supporting or contradicting each claim
  • A final determination and confidence score are calculated

Step 2: Check Fact-Check Status​

Poll the API to check if processing is complete:

curl "https://api.feeds.onhelix.ai/fact-check/550e8400-e29b-41d4-a716-446655440000" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response (when complete):

{
  "success": true,
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "text": "The Eiffel Tower was completed in 1889...",
    "status": "completed",
    "finalDetermination": "mostly_accurate",
    "finalConfidence": 0.92,
    "processingTimeMs": 45230,
    "aggregatedStats": {
      "totalClaims": 3,
      "verifiedClaims": 3,
      "disputedClaims": 0,
      "unverifiedClaims": 0
    },
    "completedAt": "2024-01-15T10:30:45.230Z"
  }
}

The fact-check is complete when status is completed or failed.

Step 3: Retrieve Claims and Evidence​

Get detailed claims with supporting or contradicting evidence:

curl "https://api.feeds.onhelix.ai/fact-check/550e8400-e29b-41d4-a716-446655440000/claims?includeEvidence=true" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response:

{
  "success": true,
  "data": [
    {
      "id": "claim_1",
      "claimText": "The Eiffel Tower was completed in 1889",
      "verificationResult": "verified",
      "evidenceConfidence": 0.98,
      "evidence": [
        {
          "id": "evidence_1",
          "sourceUrl": "https://www.toureiffel.paris/en/the-monument",
          "evidenceText": "The Eiffel Tower was built between 1887 and 1889...",
          "evidenceType": "supporting",
          "relevanceScore": 0.98,
          "confidenceScore": 0.99,
          "explanation": "Official source confirms the 1889 completion date"
        }
      ]
    }
  ]
}

Understanding the Results​

The system provides both an overall assessment and per-claim verification:

Final Determination (finalDetermination):

  • mostly_accurate - Most claims are verified or supported
  • mostly_inaccurate - Most claims are disputed or contradicted
  • mixed_results - Mix of supporting and contradicting evidence
  • insufficient_evidence - Not enough evidence to determine

Confidence Levels (finalConfidence, 0.0-1.0):

  • 0.8-1.0 - High confidence
  • 0.6-0.8 - Moderate confidence
  • 0.0-0.6 - Low confidence (may warrant manual review)

Per-Claim Results (verificationResult):

  • verified - Claim is supported by evidence
  • disputed - Claim is contradicted by evidence
  • unverified - Insufficient evidence to verify
  • mixed - Both supporting and contradicting evidence

See the Overview for detailed explanations.

Next Steps​

Now that you have fact-checked your first text, you can:

  • Set up webhooks: Get notified when fact-checks complete
  • List all fact-checks: Retrieve and filter your fact-check history
  • Retry failed checks: Automatically retry fact-checks that failed
  • Integrate into your application: Build fact-checking into your workflow

Common Patterns​

Polling with Retry​

# Check status every 5 seconds until complete
while true; do
  STATUS=$(curl -s "https://api.feeds.onhelix.ai/fact-check/550e8400-e29b-41d4-a716-446655440000" \
    -H "Authorization: Bearer YOUR_API_KEY" | jq -r '.data.status')

  if [ "$STATUS" = "completed" ] || [ "$STATUS" = "failed" ]; then
    break
  fi

  sleep 5
done

Batch Processing​

# Submit multiple fact-checks
for text in "Claim 1" "Claim 2" "Claim 3"; do
  curl -X POST https://api.feeds.onhelix.ai/fact-check \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d "{\"text\": \"$text\"}"
done