API Documentation

Base URL

https://api.openclassifier.ai

Authentication

Include your API key in the Authorization header:

Authorization: Bearer YOUR_API_KEY

Rate Limits

Request Body

Single-Label Example

curl -X POST https://api.openclassifier.ai/classify/text \
  -H "Authorization: Bearer $OPENCLASSIFIER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "The package arrived damaged and I want a refund",
    "labels": ["shipping", "returns", "billing", "general"]
  }'

Response

{
  "success": true,
  "results": {
    "label": "returns",
    "confidence": 0.94
  }
}

Multi-Label Example

Classify text across multiple categories simultaneously by passing an object with category keys:

curl -X POST https://api.openclassifier.ai/classify/text \
  -H "Authorization: Bearer $OPENCLASSIFIER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Your service is terrible, I have been waiting for weeks!",
    "labels": {
      "intent": ["complaint", "inquiry", "feedback", "request"],
      "sentiment": ["positive", "neutral", "negative"],
      "urgency": ["low", "medium", "high"]
    }
  }'

Response

{
  "success": true,
  "results": {
    "intent": { "label": "complaint", "confidence": 0.97 },
    "sentiment": { "label": "negative", "confidence": 0.95 },
    "urgency": { "label": "high", "confidence": 0.88 }
  }
}

Request Body

Example Request

curl -X POST https://api.openclassifier.ai/classify/image \
  -H "Authorization: Bearer $OPENCLASSIFIER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "inputs": [
      { "url": "https://example.com/document1.png" },
      { "url": "https://example.com/document2.png" }
    ],
    "labels": ["invoice", "receipt", "contract", "letter"]
  }'

Response

{
  "success": true,
  "results": [
    {
      "input": "https://example.com/document1.png",
      "label": "invoice",
      "confidence": 0.92
    },
    {
      "input": "https://example.com/document2.png",
      "label": "receipt",
      "confidence": 0.89
    }
  ]
}

Supported Image Formats

• JPEG / JPG
• PNG
• GIF (first frame only)
• WebP

Maximum image size: 20MB per image

Request Body

Classification Modes

• per_page: Returns classification for each page individually
• document: Also returns an aggregated classification for the entire document based on page votes

Example Request

curl -X POST https://api.openclassifier.ai/classify/pdf \
  -H "Authorization: Bearer $OPENCLASSIFIER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "input": { "url": "https://example.com/document.pdf" },
    "labels": ["invoice", "contract", "report", "letter"],
    "mode": "document"
  }'

Response

{
  "success": true,
  "totalPages": 3,
  "results": [
    { "page": 1, "label": "invoice", "confidence": 0.94 },
    { "page": 2, "label": "invoice", "confidence": 0.91 },
    { "page": 3, "label": "invoice", "confidence": 0.89 }
  ],
  "documentLabel": {
    "label": "invoice",
    "confidence": 0.91
  }
}

How It Works

1. PDF is fetched from URL or decoded from base64
2. Each page is converted to a high-resolution image (2x scale)
3. All pages are classified in parallel for speed
4. Results are returned per-page with optional document-level aggregation

Maximum PDF size: 50MB, Maximum pages: 100

Python

import requests

# Single-label classification
response = requests.post(
    "https://api.openclassifier.ai/classify/text",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    json={
        "content": "I need to change my delivery address",
        "labels": ["shipping", "returns", "billing", "account"]
    }
)
result = response.json()
print(result["results"]["label"], result["results"]["confidence"])

# PDF classification
response = requests.post(
    "https://api.openclassifier.ai/classify/pdf",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    json={
        "input": {"url": "https://example.com/document.pdf"},
        "labels": ["invoice", "contract", "report"],
        "mode": "document"
    }
)
result = response.json()
print(f"Document type: {result['documentLabel']['label']}")

TypeScript / JavaScript

// Classify a PDF document
const response = await fetch(
  "https://api.openclassifier.ai/classify/pdf",
  {
    method: "POST",
    headers: {
      "Authorization": "Bearer YOUR_API_KEY",
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      input: { url: "https://example.com/document.pdf" },
      labels: ["invoice", "contract", "report"],
      mode: "document"
    })
  }
);

const data = await response.json();
console.log("Document type:", data.documentLabel.label);
console.log("Pages classified:", data.totalPages);

Error Response Format

{
  "success": false,
  "error": {
    "code": "INVALID_REQUEST",
    "message": "Content is required"
  }
}

Error Codes