Documentation

Everything you need to integrate Classivore into your application.

Quickstart

Make your first request:

curl

curl -X POST https://api.classivore.com/v1/classify \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text": "Tesla announces new electric vehicle"}'

Get structured categories back:

{
  "model": "iab-2.2",
  "model_version": "1.1.0",
  "categories": [
    {"id": "22", "name": "Automotive", "confidence": 0.94, "path": ["Automotive"]},
    {"id": "19", "name": "Technology & Computing", "confidence": 0.81, "path": ["Technology & Computing"]}
  ],
  "usage": {"credits": 1}
}

Authentication

All API requests require a Bearer token in the Authorization header.

Authorization: Bearer cv_live_your_api_key_here

API keys start with cv_live_. Keep your key secret. Never expose it in client-side code.

POST /v1/classify

Classify a single text against a taxonomy model. Costs 1 credit per request.

Request body

Parameter	Type	Description
text	string	Required. 1–50,000 characters.
model	string	Default: `"iab-2.2"`
options.max_labels	int	1–10. Default: 3
options.min_confidence	float	0.0–1.0. Default: 0.5

Examples

curl

curl -X POST https://api.classivore.com/v1/classify \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text": "Tesla announces new electric vehicle with 400-mile range."}'

Python (httpx)

import httpx

r = httpx.post(
    "https://api.classivore.com/v1/classify",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    json={"text": "Tesla announces new electric vehicle with 400-mile range."},
)
print(r.json())

JavaScript (fetch)

const r = await fetch("https://api.classivore.com/v1/classify", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ text: "Tesla announces new electric vehicle with 400-mile range." }),
});
console.log(await r.json());

POST /v1/classify/batch

Classify up to 100 texts in a single request. Costs 1 credit per text.

Request body

Parameter	Type	Description
texts	array<string>	Required. 1–100 items. Each text 1–50,000 chars.
model	string	Default: `"iab-2.2"`
options	object	Same fields as `/classify`.

Examples

curl

curl -X POST https://api.classivore.com/v1/classify/batch \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "texts": [
      "Tesla announces new electric vehicle.",
      "The Fed raised interest rates by a quarter point."
    ]
  }'

Python (httpx)

import httpx

r = httpx.post(
    "https://api.classivore.com/v1/classify/batch",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    json={"texts": ["First article...", "Second article..."]},
)
for result in r.json():
    print(result["categories"])

POST /v1/classify/url

Fetch a URL, extract its main text content, and classify it. Costs 2 credits per URL.

URL fetching is SSRF-protected: private network, loopback, and link-local addresses are rejected. Pages are capped at 5 MB. Only HTML is accepted; the response is stripped to its readable body text before classification.

Request body

Parameter	Type	Description
url	string	Required. 1–2,048 characters. http(s) only.
model	string	Default: `"iab-2.2"`
options	object	Same fields as `/classify`.

The response shape is identical to /v1/classify. Returns 422 if the URL is unreachable, returns non-HTML, exceeds 5 MB, or has no extractable text.

Example

curl

curl -X POST https://api.classivore.com/v1/classify/url \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://classivore.com"}'

POST /v1/classify/url/batch

Fetch up to 50 URLs concurrently, extract text, and classify each. Costs 2 credits per URL (charged regardless of individual success or failure).

Unlike /classify/batch, individual URL failures do not fail the whole request. Failures return as {"url": "...", "error": "..."} entries in the response array, alongside successful classifications.

Request body

Parameter	Type	Description
urls	array<string>	Required. 1–50 URLs. Each 1–2,048 chars.
model	string	Default: `"iab-2.2"`
options	object	Same fields as `/classify`.

Example

curl

curl -X POST https://api.classivore.com/v1/classify/url/batch \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "urls": [
      "https://classivore.com",
      "https://example.com"
    ]
  }'

Response

[
  {
    "url": "https://classivore.com",
    "model": "iab-2.2",
    "model_version": "1.1.0",
    "categories": [{"id": "19", "name": "Technology & Computing", "confidence": 0.92, "path": ["Technology & Computing"]}],
    "usage": {"credits": 2}
  },
  {
    "url": "https://example.com",
    "error": "No text content could be extracted."
  }
]

Models

GET /v1/models

List all available taxonomy models. No authentication required.

{
  "models": [
    {
      "slug": "iab-2.2",
      "name": "IAB Content Taxonomy 2.2",
      "description": "Interactive Advertising Bureau content taxonomy",
      "category_count": 698
    }
  ]
}

GET /v1/models/{slug}

Return full metadata for a single model. Returns 404 if the slug is not recognized.

curl https://api.classivore.com/v1/models/iab-2.2

Error codes

Code	Meaning
401	Invalid or missing API key
404	Model not found
422	Invalid request body, unreachable URL, or unextractable page
429	Rate limit exceeded
500	Server error

Every response includes X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers. Rate-limited (429) responses also include Retry-After.