CSVLint.io API Documentation

The CSVLint API allows you to validate CSV files for structure and schema compliance. You can use this API to upload a file directly or provide a URL to a CSV and an optional schema. The API will return a JSON response with validation results if requested.

Privacy and Validation Records

CSVLint.io keeps a record of each validation report so it is possible to track service use and types of errors people are encountering. However, to ensure user privacy, all identifiable data is removed from these stored reports. This includes the URLs/filenames of the CSV and/or schema, as well as any content within these.

When you revisit a previously generated report by its ID (e.g., /validation/<id>), you will see a summary of the validation, but any identifiable information and in-depth details, such as specific content errors, are not available as we don't have them! For this reason, if you want to see the full validation detail, including error specifics and embed options, you must perform a new validation.

To prevent duplication, each validation report includes a one-way hash generated from the URLs of the CSV and schema files. This hash allows the service to detect if a validation for the same combination of URLs has been performed previously without retaining the actual URLs themselves. This privacy-preserving approach ensures we can keep track of usage without storing any identifable information.

This may seem risk averse, but it is done because many people will upload very sensitive data to publicly accessible locations and we do not want a record of these locations. If you want to validate a CSV file that contains sensitive information, use the POST API and send a file, not a URL!

For more on privacy please see the privacy policy.

Acceptable use

Please note that we have deployed a rate limiter on the free version of CSVLint. If you wish to deploy CSVLint across your platform, please contact us to enquire about the costs of doing this.

Endpoints

POST /validate

GET /validate

1. POST /validate

This endpoint validates a CSV file provided as a URL or file upload, with an optional schema for validation.

Headers

• Content-Type: multipart/form-data (required)
• Accept: application/json (optional, for JSON response)

Parameters

• csvUrl (string): URL of the CSV file to validate (optional if uploading a file).
• file (file): CSV file upload for validation (optional if using a URL).
• schemaUrl (string): URL of a JSON schema for the CSV structure (optional).
• schema (file): JSON schema file upload for the CSV structure (optional).
• Dialect Options: Optional CSV dialect options to customize validation.

Example Usage

Using a CSV URL

curl -X POST http://csvlint.io/validate \
  -H "Accept: application/json" \
  -F "csvUrl=http://example.com/mydata.csv" \
  -F "schemaUrl=http://example.com/myschema.json"

Using File Upload

curl -X POST http://csvlint.io/validate \
  -H "Accept: application/json" \
  -F "file=@/path/to/yourfile.csv" \
  -F "schema=@/path/to/yourschema.json"

Using Dialect Options

curl -X POST http://csvlint.io/validate \
  -H "Accept: application/json" \
  -F "file=@/path/to/yourfile.csv" \
  -F "delimiter=;" \
  -F "header=true"

2. GET /validate

This endpoint allows you to validate a CSV file by providing URLs for the CSV and schema directly in the query parameters, along with optional dialect settings. This is useful for integrations where files are hosted remotely.

Parameters

• csvUrl (string): URL of the CSV file to validate (required).
• schemaUrl (string): URL of a JSON schema for the CSV structure (optional).
• Dialect Options: Optional CSV dialect options as query parameters (e.g., delimiter, doubleQuote, lineTerminator, etc.)
• format (string): Set to svg or png to receive a badge representing the validation result.

Example Usage

Validate a CSV with a URL

curl -X GET "http://csvlint.io/validate?csvUrl=http://example.com/mydata.csv&schemaUrl=http://example.com/myschema.json"

Retrieve Validation Badge

Use ?format=svg or ?format=png to directly retrieve a badge for the validation result. This will return an SVG or PNG badge based on the CSV’s validation status.

curl -X GET "http://csvlint.io/validate?csvUrl=http://example.com/mydata.csv&format=svg"

Response Format (JSON)

If the Accept header is set to application/json, the API will respond with JSON in the following format:

{
  "version": "0.2",
  "licence": "http://opendatacommons.org/licenses/odbl/",
  "validation": {
    "source": "http://example.com/mydata.csv",
    "schema": "http://example.com/myschema.json",
    "state": "invalid",
    "errors": [
      {
        "type": "undeclared_header",
        "category": "structure",
        "row": null,
        "col": null
      }
    ],
    "warnings": [
      {
        "type": "header_name",
        "category": "schema",
        "row": null,
        "col": 1
      }
    ],
    "info": [
      {
        "type": "assumed_header",
        "category": "structure",
        "row": null,
        "col": null
      }
    ]
  }
}

Embed Badge Code

You can also directly embed a badge on your website to show its validation status.

Example Embed Code

<a href="http://csvlint.io/validate?csvUrl=http://example.com/mydata.csv" target="_blank">
  <img src="http://csvlint.io/validate?csvUrl=http://example.com/mydata.csv&format=svg" alt="CSV Validation Badge">
</a>