API Specification

API Specification

Overview

This document outlines the API specification for the Veri-Fact.ai misinformation detection and mitigation system.

• Base URL: https://api.veri-fact.ai/v1
• Authentication: Bearer Token (JWT)

Endpoints

1. Submit Query

Submit a claim or statement for fact-checking.

• URL: /query
• Method: POST
• Auth required: Yes

Request Body

{
  "text": "string",
  "context": "string (optional)"
}

Success Response

• Code: 200 OK
• Content example:

{
  "id": "string",
  "analysis": "string",
  "veracity": "true | mostly_true | mixed | mostly_false | false | unverifiable",
  "confidence": 0.95,
  "sources": [
    {
      "url": "string",
      "title": "string",
      "snippet": "string",
      "credibilityScore": 0.8
    }
  ]
}

2. Send Chat Message

Send a message in a chat session.

• URL: /chat
• Method: POST
• Auth required: Yes

Request Body

{
  "message": "string",
  "sessionId": "string"
}

Success Response

• Code: 200 OK
• Content example:

{
  "response": "string",
  "analysis": {
    // Same structure as Query Response
  }
}

3. Get Sources

Retrieve sources for a fact-checked claim.

• URL: /sources
• Method: GET
• Auth required: Yes
• URL Params: claimId=[string]

Success Response

• Code: 200 OK
• Content example:

{
  "claimId": "string",
  "sources": [
    {
      "url": "string",
      "title": "string",
      "snippet": "string",
      "credibilityScore": 0.8
    }
  ]
}

4. Create User

Create a new user account.

• URL: /user
• Method: POST
• Auth required: No

Request Body

{
  "username": "string",
  "email": "string",
  "password": "string"
}

Success Response

• Code: 201 Created
• Content example:

{
  "id": "string",
  "username": "string",
  "email": "string"
}

5. User Login

Authenticate a user and receive a JWT token.

• URL: /user/login
• Method: POST
• Auth required: No

Request Body

{
  "email": "string",
  "password": "string"
}

Success Response

• Code: 200 OK
• Content example:

{
  "token": "string",
  "user": {
    "id": "string",
    "username": "string",
    "email": "string"
  }
}

Error Responses

All endpoints can return the following error responses:

• 400 Bad Request: When the request is malformed or missing required fields.
• 401 Unauthorized: When authentication fails or is missing.

Error response body:

{
  "code": 400,
  "message": "Error description"
}

Data Models

Query

• text (string, required): The claim or statement to fact-check
• context (string, optional): Additional context for the query

Source

• url (string): URL of the source
• title (string): Title of the source
• snippet (string): Relevant excerpt from the source
• credibilityScore (float): Credibility rating of the source (0-1)

User

• id (string): Unique identifier for the user
• username (string): User's chosen username
• email (string): User's email address

Authentication

This API uses JWT for authentication. Include the JWT token in the Authorization header of your requests:

Authorization: Bearer <your_token_here>

Obtain a token by using the User Login endpoint.