API Reference

Endpoint


POST https://api.classifai.com/v1

Request Parameters

Payload

Parameter	Type	Required	Description
`urls`	string[]	Yes	Array of URLs to classify. Maximum 500 URLs per request.
`api_key`	string	Yes	Your API key received after account creation.
`taxonomy`	string	No	Specifies the taxonomy version to use for classification. Available values: `iab-1.0`, `iab-2.0`, `iab-3.1`. Coming soon: `iab-2.1`, `iab-2.2`, and `iab-3.0`.

💡

For optimal efficiency, it is very important to provide as many URLs as possible in a single request, up to the maximum of 500.

Example Request


{
  "urls": ["https://www.example.com/", "https://www.tech-blog.com/"],
  "api_key": "your_api_key_here",
  "taxonomy": "iab-1.0"
}

Response

The API returns a JSON object containing classification results for each URL.

Response Structure


{
  "results": [
    {
      "url": "string",
      "scraped_successfully": boolean,
      "predictions": [
        {
          "tier1": {
            "name": "string",
            "code": "string",
            "confidence": number
          },
          "tier2": {
            "name": "string",
            "code": "string",
            "confidence": number
          },
          "tier3": {
            "name": "string",
            "code": "string",
            "confidence": number
          },
          "tier4": {
            "name": "string",
            "code": "string",
            "confidence": number
          }
        }
      ]
    }
  ]
}

Response Fields

Field	Type	Description
`results`	array	Array of classification results for each URL
`url`	string	The URL that was classified
`scraped_successfully`	boolean	Indicates if the URL was successfully scraped. If false, classification was based on URL only
`predictions`	array	Array of predictions for the URL
`tier1`	object	Always present. Contains the top-level category
`tier2`	object	May be missing if no suitable category is found
`tier3`	object	May be present for taxonomies `iab-2.0` and above. Contains the third-level category.
`tier4`	object	May be present for taxonomies `iab-2.0` and above. Contains the fourth-level category.
`name`	string	Category name
`code`	string	IAB category code
`confidence`	number	Confidence score (0-1)

Example Response


{
  "results": [
    {
      "url": "https://www.example.com/",
      "scraped_successfully": true,
      "predictions": [
        {
          "tier1": {
            "name": "Technology & Computing",
            "code": "IAB19",
            "confidence": 0.99
          },
          "tier2": {
            "name": "Web Development",
            "code": "IAB19-2",
            "confidence": 0.98
          }
        }
      ]
    },
    {
      "url": "https://www.tech-blog.com/",
      "scraped_successfully": true,
      "predictions": [
        {
          "tier1": {
            "name": "Technology & Computing",
            "code": "IAB19",
            "confidence": 0.98
          },
          "tier2": {
            "name": "Tech News",
            "code": "IAB19-1",
            "confidence": 0.98
          }
        },
        {
          "tier1": {
            "name": "Business",
            "code": "IAB3",
            "confidence": 0.72
          },
          "tier2": {
            "name": "Business News",
            "code": "IAB3-1",
            "confidence": 0.71
          }
        }
      ]
    }
  ]
}

Important Notes

Batch Processing: For optimal performance, it is very important to provide as many URLs as possible in a single request. The API supports up to 500 URLs per request.
URL Requirements:
- URLs must include the protocol (http:// or https://)
- URLs must be valid and accessible
- Maximum URL length is 2048 characters
Error Handling:
- If a URL is invalid or its server is down, the API will still attempt classification using the URL string
- In such cases, scraped_successfully will be set to false
- The API will continue processing other URLs in the batch
Multi-Predict (Coming Soon):
- Currently, the API already provides multiple predictions for each URL when available
- Predictions are ordered by confidence (highest first)
- If you only need one prediction, simply use the first item in the predictions array
- The multi_predict parameter to control the number of predictions is coming soon
- Range: 1-3 predictions per URL