Verafy Private API Key Usage (Beta)

General Info

⚠️ Currently we are distributing API keys only by DM (direct message) on Telegram.

If you would like to apply for a key.

1. Find @csjcode on Telegram or X
2. Explain in the DM (direct message):
   • what your project is,
   • how it works (user UX flow and tech stack),
   • what endpoint/response you need
3. Give an estimate of expected usage and calls per day.
4. We will respond with 24-48 hrs, and, if approved, send a unique private API key by DM).

🔐 Authentication

• Private API key (unique to you) will be given to you.
• Required header: X-API-Key: <your api key here>
• The API will return an error if this header is missing.
• Keep your key secret and do not share it with others.
• Keys should be stored in a `.env` file in the root directory of your project and not hard-coded into your codebase.

📦 API Usage and Limits

• You start with 500 Verafy credits for testing.
• Each AI model queried uses 1 Verafy credit.
• Example: Requesting 5 validators uses 5 Verafy credits.
• Credit top-ups can be done manually by us as needed, DM (direct message) @csjcode with key.
• There is also an hourly rate limit. Avoid accidental code loops or spam. Verafy pays for queries, please be responsible.

⚠️ Notes

• The API is in beta and may change over time.
• The URL is temporary and may be updated in the future.
• Some active/inactive LLMs may change over time
• Some AIs may return malformed JSON. Add error handling if needed. This does not happen a lot but is more common if querying many (over 10) AIs at once.

🧾 Required Headers (all endpoints)

• Content-Type: application/json
• X-API-Key: <your api key here>

📝 POST /broadcast-query - Body (JSON)

• queryText: The sentence or claim to fact-check
• queryMode: Always set to fact-check currently.
• queriesRequested: Number of AIs to consult (max recommended: 5). Allows up to 20 but is slower and will deplete credits fast. (required only if no selectedLLMIds given)
• selectedLLMIds (optional): Number of AIs to consult (max recommended: 5). Allows up to 20 but is slower and will deplete credits fast.

📊 Response Fields (New: Confidence Data)

• consensusConfidence: A numerical value (0-1) representing the overall confidence in the consensus result based on individual validator confidence scores
• confidence (in validatorResponses): Each validator now includes their confidence level (0-1) in their individual response
• Higher confidence values indicate stronger certainty in the validator's assessment

📍 Example cURL Request

curl -X POST https://api.verafy.ai/api/v1/public/broadcast-query \
  -H "Content-Type: application/json" \
  -H "X-API-Key: <your api key here>" \
  -d '{
    "queryText": "Earth is bigger than Mars",
    "queryMode": "fact-check",
    "queriesRequested": 5
  }'

✅ Expected JSON Response

{
  "id": "7c9d7dfe-331e-4d62-82c8-03caf8e39591",
  "isConsensusReached": true,
  "consensusValue": true,
  "consensusConfidence": 0.95,
  "queryText": "Earth is bigger than Mars.",
  "validatorResponses": [
    {
      "id": "...",
      "provider": "OpenRouter",
      "profileName": "...",
      "vote": "YES",
      "rationale": "Earth is bigger than Mars because...",
      "confidence": 1.0
    }
    // More validators...
  ],
  "votingResult": {
    "yes": 5,
    "no": 0,
    "notVoted": 0
  },
  "timestamp": "2025-07-04T15:45:10.341Z"
}

📍 Example cURL Request (Selected LLMS)

curl -X POST https://api.verafy.ai/api/v1/public/broadcast-query \
  -H "Content-Type: application/json" \
  -H "X-API-Key: <your api key here>" \
  -d '{
    "queryText": "Earth is bigger than Mars",
    "queryMode": "fact-check",
    "selectedLLMIds":["65462fc9-04f8-4a31-9d97-181812e3dcac","0667d739-69f0-4cd6-80ea-cf9fe1774ec9","38cb31ac-e3ee-4398-96d1-a7d91d4528e3"]
  }'

✅ Expected JSON Response (Selected LLMS)

{
  "id": "7c258853-e374-4a4a-8fb8-a9fde3663608",
  "isConsensusReached": true,
  "consensusValue": true,
  "consensusConfidence": 0.98,
  "queryText": "Earth is bigger than Mars.",
  "validatorResponses": [
      {
          "id": "65462fc9-04f8-4a31-9d97-181812e3dcac",
          "provider": "OpenRouter",
          "profileName": "Claude 3 Sonnet Validator",
          "vote": "YES",
          "rationale": "Earth has a diameter of approximately 12,742 km, while Mars has a diameter of around 6,779 km. Earth is significantly larger than Mars in terms of size and mass.",
          "confidence": 1.0
      },
      {
          "id": "0667d739-69f0-4cd6-80ea-cf9fe1774ec9",
          "provider": "OpenRouter",
          "profileName": "DeepSeek: DeepSeek V3 0324 (free) Validator",
          "vote": "YES",
          "rationale": "Earth has a diameter of approximately 12,742 km, while Mars has a diameter of about 6,779 km, making Earth significantly larger.",
          "confidence": 0.95
      },
      {
          "id": "38cb31ac-e3ee-4398-96d1-a7d91d4528e3",
          "provider": "OpenRouter",
          "profileName": "OpenAI: GPT-4o Validator",
          "vote": "YES",
          "rationale": "Earth is indeed larger than Mars. Earth has a diameter of about 12,742 kilometers, while Mars has a diameter of about 6,779 kilometers. Therefore, Earth is significantly bigger than Mars in terms of both diameter and volume.",
          "confidence": 1.0
      }
  ],
  "votingResult": {
      "yes": 3,
      "no": 0,
      "notVoted": 0
  },
  "timestamp": "2025-07-06T12:30:24.458Z"
}

📝 GET /validators/active - Query Parameters

• No query parameters currently - returns list of AI LLMs with ID.
• ID in UUID format is used with selectedLLMIds

📍 Example cURL Request (List of AI LLMS)

curl --location 'https://api.verafy.ai/api/v1/public/validators/active' --header 'X-API-Key: <your api key>'

✅ Expected JSON Response (List of AI LLMS)

{
  [
    {
        "id": "2be6d724-a525-483f-ad68-bf023bcac613",
        "name": "Llama 3.1 8B Validator",
        "provider": "OpenRouter",
        "modelName": "meta-llama/llama-3.1-8b-instruct",
        "active": true
    },
    {
        "id": "1192bc8f-32d9-406d-ba33-673d8996ada4",
        "name": "GROK-1 Validator",
        "provider": "Grok",
        "modelName": "grok-1",
        "description": "This validator leverages xAI's grok-1 model for fact-checking, providing fast and contextually aware reasoning.",
        "validatorType": "Contextual Reasoning Engine",
        "active": true,
        "keyId": "1192bc8f-32d9-406d-ba33-673d8996ada4"
    },
    {
        "id": "c9caf2ff-ac05-4688-b1b9-54ff46d26f78",
        "name": "Llama 3 8B Validator",
        "provider": "OpenRouter",
        "modelName": "meta-llama/llama-3-8b-instruct",
        "active": true
    },


    etc...

}

💳 GET /credits - Check Credit Usage

Check your current credit balance and API key status.

• No query parameters required - simply provide your API key in the header
• Returns current credit balance, API key status, and last usage information

📍 Example cURL Request (Check Credits)

curl -X GET https://api.verafy.ai/api/v1/public/credits \
  -H "X-API-Key: <your api key here>"

✅ Expected JSON Response (Check Credits)

{
  "apiKeyId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "credits": 450,
  "lastUsed": "2024-08-24T21:00:00.000Z",
  "isActive": true,
  "timestamp": "2024-08-24T21:15:00.000Z"
}