File Formats

CSV and JSON file format specifications for batch uploads.

File Formats

Batch processing supports both CSV and JSON file formats. Files can be uploaded via the Upload File endpoint.

Limits

Limit	Value
Maximum file size	10 MB
Maximum items per file	100
Maximum content length per item	50,000 characters

CSV Format

CSV files must include a header row with column names.

Required Columns

Column	Description
`content`	The text content to verify (required)

Optional Columns

Column	Description
`idempotencyKey` or `idempotency_key`	Unique key for deduplication
`context.*`	Context fields (e.g., `context.source`, `context.category`)

Example CSV

content,context.source,context.category,idempotencyKey
"The Earth is approximately 4.5 billion years old.",wikipedia,science,claim-001
"Water boils at 100 degrees Celsius at sea level.",textbook,physics,claim-002
"The Great Wall of China is visible from space.",internet,myth,claim-003

CSV Parsing Rules

Header row - First row must contain column names (case-insensitive)
Quoting - Use double quotes for values containing commas or newlines
Escaping - Double quotes within quoted values should be escaped with another double quote ("")
Empty rows - Blank lines are ignored
Line endings - Both \n (Unix) and \r\n (Windows) are supported

Context Columns

Any column prefixed with context. will be parsed as a context field:

content,context.source,context.author,context.publishDate
"Claim text here",news-site,John Smith,2024-01-15

This creates:

{
  "content": "Claim text here",
  "context": {
    "source": "news-site",
    "author": "John Smith",
    "publishDate": "2024-01-15"
  }
}

JSON Format

JSON files can be either an array of items or an object with an items array.

Array Format

[
  {
    "content": "The Earth is approximately 4.5 billion years old.",
    "context": {
      "source": "wikipedia",
      "category": "science"
    },
    "idempotencyKey": "claim-001"
  },
  {
    "content": "Water boils at 100 degrees Celsius at sea level.",
    "context": {
      "source": "textbook"
    },
    "idempotencyKey": "claim-002"
  }
]

Object Format

{
  "items": [
    {
      "content": "The Earth is approximately 4.5 billion years old.",
      "context": {
        "source": "wikipedia"
      }
    },
    {
      "content": "Water boils at 100 degrees Celsius at sea level."
    }
  ]
}

Item Schema

interface BatchItem {
  // Required
  content: string;          // 1-50,000 characters

  // Optional
  context?: {
    [key: string]: unknown; // Arbitrary context data
  };
  idempotencyKey?: string;  // Max 255 characters
}

Validation

Content Validation

Required - Content field cannot be empty
Length - Maximum 50,000 characters
Whitespace - Leading/trailing whitespace is preserved

Item Limits

Files with more than 100 valid items will be truncated
A warning is returned indicating rows were ignored

Error Handling

Items with validation errors are skipped, and the error is returned in the upload response:

{
  "fileId": "abc123",
  "itemCount": 98,
  "validationErrors": [
    { "row": 15, "error": "Content is empty" },
    { "row": 42, "error": "Content exceeds maximum length (50000 chars)" }
  ],
  "message": "File uploaded with 2 validation warning(s). Items with errors were skipped."
}

Format Detection

File format is automatically detected by:

File extension - .csv or .json
Content inspection - If extension is ambiguous, content is inspected
Explicit format - Pass format field in the upload request

# Force JSON format detection
curl -X POST https://api.check.ai/v1/batch/upload \
  -H "Authorization: Bearer vfy_your_api_key" \
  -F "file=@data.txt" \
  -F "format=json"

Best Practices

For large datasets: Split files into multiple batches of 100 items each for better error handling and progress tracking.

Use idempotency keys - Prevent duplicate processing if you need to retry
Include context - Context helps verification methods provide better results
Validate locally - Check your file format before uploading to avoid validation errors
Use JSON for complex context - CSV is limited to string values for context fields

Sample Files

Minimal CSV

content
"First claim to verify"
"Second claim to verify"
"Third claim to verify"

Full-Featured JSON

[
  {
    "content": "The human brain contains approximately 86 billion neurons.",
    "context": {
      "source": "neuroscience-journal",
      "category": "biology",
      "author": "Dr. Smith",
      "publishDate": "2024-01-10",
      "confidence_level": "peer-reviewed"
    },
    "idempotencyKey": "neuro-fact-001"
  }
]

File Formats

CSV and JSON file format specifications for batch uploads.

File Formats

Batch processing supports both CSV and JSON file formats. Files can be uploaded via the Upload File endpoint.

Limits

Limit	Value
Maximum file size	10 MB
Maximum items per file	100
Maximum content length per item	50,000 characters

CSV Format

CSV files must include a header row with column names.

Required Columns

Column	Description
`content`	The text content to verify (required)

Optional Columns

Column	Description
`idempotencyKey` or `idempotency_key`	Unique key for deduplication
`context.*`	Context fields (e.g., `context.source`, `context.category`)

Example CSV

content,context.source,context.category,idempotencyKey
"The Earth is approximately 4.5 billion years old.",wikipedia,science,claim-001
"Water boils at 100 degrees Celsius at sea level.",textbook,physics,claim-002
"The Great Wall of China is visible from space.",internet,myth,claim-003

CSV Parsing Rules

Header row - First row must contain column names (case-insensitive)
Quoting - Use double quotes for values containing commas or newlines
Escaping - Double quotes within quoted values should be escaped with another double quote ("")
Empty rows - Blank lines are ignored
Line endings - Both \n (Unix) and \r\n (Windows) are supported

Context Columns

Any column prefixed with context. will be parsed as a context field:

content,context.source,context.author,context.publishDate
"Claim text here",news-site,John Smith,2024-01-15

This creates:

{
  "content": "Claim text here",
  "context": {
    "source": "news-site",
    "author": "John Smith",
    "publishDate": "2024-01-15"
  }
}

JSON Format

JSON files can be either an array of items or an object with an items array.

Array Format

[
  {
    "content": "The Earth is approximately 4.5 billion years old.",
    "context": {
      "source": "wikipedia",
      "category": "science"
    },
    "idempotencyKey": "claim-001"
  },
  {
    "content": "Water boils at 100 degrees Celsius at sea level.",
    "context": {
      "source": "textbook"
    },
    "idempotencyKey": "claim-002"
  }
]

Object Format

{
  "items": [
    {
      "content": "The Earth is approximately 4.5 billion years old.",
      "context": {
        "source": "wikipedia"
      }
    },
    {
      "content": "Water boils at 100 degrees Celsius at sea level."
    }
  ]
}

Item Schema

interface BatchItem {
  // Required
  content: string;          // 1-50,000 characters

  // Optional
  context?: {
    [key: string]: unknown; // Arbitrary context data
  };
  idempotencyKey?: string;  // Max 255 characters
}

Validation

Content Validation

Required - Content field cannot be empty
Length - Maximum 50,000 characters
Whitespace - Leading/trailing whitespace is preserved

Item Limits

Files with more than 100 valid items will be truncated
A warning is returned indicating rows were ignored

Error Handling

Items with validation errors are skipped, and the error is returned in the upload response:

{
  "fileId": "abc123",
  "itemCount": 98,
  "validationErrors": [
    { "row": 15, "error": "Content is empty" },
    { "row": 42, "error": "Content exceeds maximum length (50000 chars)" }
  ],
  "message": "File uploaded with 2 validation warning(s). Items with errors were skipped."
}

Format Detection

File format is automatically detected by:

File extension - .csv or .json
Content inspection - If extension is ambiguous, content is inspected
Explicit format - Pass format field in the upload request

# Force JSON format detection
curl -X POST https://api.check.ai/v1/batch/upload \
  -H "Authorization: Bearer vfy_your_api_key" \
  -F "file=@data.txt" \
  -F "format=json"

Best Practices

For large datasets: Split files into multiple batches of 100 items each for better error handling and progress tracking.

Use idempotency keys - Prevent duplicate processing if you need to retry
Include context - Context helps verification methods provide better results
Validate locally - Check your file format before uploading to avoid validation errors
Use JSON for complex context - CSV is limited to string values for context fields

Sample Files

Minimal CSV

content
"First claim to verify"
"Second claim to verify"
"Third claim to verify"

Full-Featured JSON

[
  {
    "content": "The human brain contains approximately 86 billion neurons.",
    "context": {
      "source": "neuroscience-journal",
      "category": "biology",
      "author": "Dr. Smith",
      "publishDate": "2024-01-10",
      "confidence_level": "peer-reviewed"
    },
    "idempotencyKey": "neuro-fact-001"
  }
]