API Reference

Overview

CategorizeAPI provides a single HTTP endpoint that accepts a URL or a block of text and returns a category, an optional subcategory, a confidence score, and a short reasoning. The API is designed to be minimal and predictable — one endpoint, JSON in, JSON out.

Base URL

Key capabilities

• URL or text input — Send a link and we fetch the page server-side, or send text directly
• Auto-detection — Set type to auto and we'll detect which one you sent
• Fixed taxonomy — 25 top-level categories, consistent across every request
• Confidence + reasoning — Every response includes a 0-1 confidence score and a one-line explanation
• Automatic failover — Backup infrastructure kicks in if the primary call fails

Authentication

All requests must include a valid API key in the Authorization header using the Bearer scheme.

Authorization: Bearer YOUR_API_KEY

API key format

API keys follow the format sk_live_xxxxxxxxxxxxxxxxxxxxxxxx (production) or sk_test_xxxxxxxxxxxxxxxxxxxxxxxx (test environment). Keep your key secret — treat it like a password.

Quick Start

Send a POST request to /api/categorize with a URL or text. You'll get a category back in a couple of seconds.

# Linux / macOS — line continuation with \

curl -X POST https://categorizeapi.com/api/categorize \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"input": "https://example.com", "type": "auto"}'

:: Windows CMD — use ^ for line continuation, \" inside double quotes

curl -X POST https://categorizeapi.com/api/categorize ^
  -H "Authorization: Bearer YOUR_API_KEY" ^
  -H "Content-Type: application/json" ^
  -d "{\"input\": \"https://example.com\", \"type\": \"auto\"}"

const categorize = async (input) => {
  const res = await fetch('https://categorizeapi.com/api/categorize', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ input, type: 'auto' })
  });
  const data = await res.json();
  console.log(data.category, data.confidence);
};

categorize('https://example.com');

import requests

response = requests.post(
    "https://categorizeapi.com/api/categorize",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    json={"input": "https://example.com", "type": "auto"}
)

data = response.json()
print(data["category"], data["confidence"])

<?php
$response = file_get_contents('https://categorizeapi.com/api/categorize', false,
    stream_context_create(['http' => [
        'method'  => 'POST',
        'header'  => "Authorization: Bearer YOUR_API_KEY\r\nContent-Type: application/json",
        'content' => json_encode(['input' => 'https://example.com', 'type' => 'auto'])
    ]])
);
$data = json_decode($response, true);
echo $data['category'];

Example response

{
  "success": true,
  "category": "Technology & Computing",
  "category_id": "technology-computing",
  "subcategory": "Software",
  "subcategory_id": "software",
  "confidence": 0.93,
  "reasoning": "The page describes a software product and its documentation.",
  "input_type": "url",
  "processing_time": 1.14,
  "requests_remaining": 4997
}

Endpoints

The main categorization call, a synchronous batch version, an async batch-job version for larger jobs, saved-taxonomy management, and a public taxonomy lookup.

Categorizes a single URL or block of text and returns a structured JSON response.

Categorizes up to 20 items in one call, synchronously. Body: {"items": [{"input": "...", "type": "auto"}, ...], ...shared options}. Any categories/language/multi_label/top_n/moderation/etc. params apply to every item. Each item counts as one request against your quota and your 60/minute burst limit — a partial failure (e.g. one bad URL) doesn't fail the whole batch, each result is reported individually.

For larger jobs: up to 500 items, processed asynchronously in the background. Same body shape as categorize-batch, plus an optional webhook_url (must be https://). Returns immediately with a job_id and a poll_url. If webhook_url is set, the final results are POSTed there when done, signed with X-CategorizeAPI-Signature: sha256=<hmac> (HMAC-SHA256 of the raw JSON body, keyed with your API key) so you can verify authenticity — recompute the same HMAC and compare.

Poll a batch job's status and (partial or final) results — useful whether or not you're also using webhook_url.

List your saved custom taxonomies. Also manageable from the Taxonomies page in your dashboard.

Save a taxonomy: {"name": "...", "categories": [...]} (2-50 entries, up to 20 saved per account). categories entries may be plain strings or {label, subcategories} objects, same as the categories request parameter. Returns an id — pass it as taxonomy_id to /api/categorize instead of resending the full categories array every call.

Edit a saved taxonomy in place. Body: {"name"?: "...", "categories"?: [...]} — both fields are optional, a partial update; omit one to leave it unchanged. Same response shape as POST.

Delete a saved taxonomy.

Public, unauthenticated. Returns the full default taxonomy (categories + example subcategories, each with a stable id) and the list of supported languages. Doesn't require an API key or count against your quota. Optional ?language=<code> query param returns the catalog itself — category and subcategory names — localized, rather than translating a classification result; covers en, fr, es, de, it, pt, nl, ar, zh, ja, ko, ru, other codes fall back to English. This is separate from the language parameter on POST /api/categorize, which translates a classification result via the model across all 34 supported languages.

Request headers (categorize / categorize-batch / batch-jobs / taxonomies)

Request Parameters

Send a JSON body with the following fields. Only input is required.

Full request example

{
  "input": "https://example.com/blog/electric-vehicles-2030",
  "type": "auto"
}

Response Format

All responses are JSON. A successful request returns HTTP 200.

{
  "success": true,
  "category": "News & Politics",
  "category_id": "news-politics",
  "subcategory": "World News",
  "subcategory_id": "world-news",
  "confidence": 0.87,
  "reasoning": "The text reports on an international diplomatic event.",
  "input_type": "text",
  "processing_time": 0.92,
  "requests_remaining": 4996
}

Response fields

Multi-label response example

{
  "success": true,
  "category": "Sports",
  "category_id": "sports",
  "confidence": 0.9,
  "categories": [
    { "category": "Sports", "category_id": "sports", "confidence": 0.9 },
    { "category": "Technology & Computing", "category_id": "technology-computing", "confidence": 0.8 },
    { "category": "Health & Fitness", "category_id": "health-fitness", "confidence": 0.7 }
  ]
}

Multi-language response example (language: "fr")

{
  "success": true,
  "category": "Technology & Computing",
  "category_id": "technology-computing",
  "subcategory": "Consumer Electronics",
  "subcategory_id": "consumer-electronics",
  "translated": {
    "language": "fr",
    "category": "Technologie et informatique",
    "subcategory": "Électronique grand public",
    "reasoning": "Le contenu décrit la sortie d'un nouveau modèle d'ordinateur portable."
  }
}

Categories & Languages

Every response's category field is exactly one of these 25 values, verbatim — unless you pass your own categories array (see Request Parameters), in which case it's one of yours instead. Every response also carries a category_id, a stable slug derived from the label (and a subcategory_id when subcategory is set) — see Response Format. The full list, ids included, is also available live at GET /api/categories (no API key required).

Custom taxonomy with strict subcategories

Both the nested categories shape and the standalone subcategories param constrain subcategory to a fixed list, verbatim, instead of letting the model guess freeform text. Mix and match plain strings with {label, subcategories} objects in the same categories array:

{
  "input": "Our new noise-cancelling headphones ship next month, starting at $199.",
  "categories": [
    { "label": "Electronics", "subcategories": ["Audio", "Wearables", "Computers"] },
    "Apparel",
    "Home Goods"
  ]
}

Here, if the model chooses "Electronics", subcategory is forced to be exactly one of "Audio"/"Wearables"/"Computers"; "Apparel" and "Home Goods" stay freeform. Equivalently, without redefining categories at all, you can layer the same constraint onto the default 25 (or a taxonomy_preset) with the standalone subcategories param:

{
  "input": "Our new noise-cancelling headphones ship next month, starting at $199.",
  "subcategories": {
    "Shopping & Retail": ["Product Reviews", "Deals & Coupons", "E-commerce", "Comparison Shopping"]
  }
}

The key must match a label already in whatever taxonomy is active for the call — the default 25 unless overridden by categories, taxonomy_preset, or taxonomy_id. Saved taxonomies (/api/taxonomies) can store the nested {label, subcategories} shape too, and you can browse or build one interactively from the Taxonomies dashboard page.

Supported languages (language parameter)

Pass any of these ISO 639-1 codes to get translated output. English (en) is the default and requires no parameter.

Errors

Error responses include an error field describing what went wrong. HTTP status codes follow standard conventions.

{
  "error": "Invalid API key"
}

cURL Examples

Complete examples using curl — available on Linux, macOS, and Windows.

Categorize a URL

curl -X POST https://categorizeapi.com/api/categorize \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "input": "https://www.espn.com",
    "type": "url"
  }'

curl -X POST https://categorizeapi.com/api/categorize ^
  -H "Authorization: Bearer YOUR_API_KEY" ^
  -H "Content-Type: application/json" ^
  -d "{\"input\": \"https://www.espn.com\", \"type\": \"url\"}"

Categorize raw text

curl -X POST https://categorizeapi.com/api/categorize \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "input": "The Federal Reserve announced a quarter-point rate cut today, citing cooling inflation and a softening labor market.",
    "type": "text"
  }'

curl -X POST https://categorizeapi.com/api/categorize ^
  -H "Authorization: Bearer YOUR_API_KEY" ^
  -H "Content-Type: application/json" ^
  -d "{\"input\": \"The Federal Reserve announced a quarter-point rate cut today.\", \"type\": \"text\"}"

JavaScript Examples

Works in Node.js 18+ (built-in fetch) and all modern browsers.

class CategorizeAPIClient {
  constructor(apiKey, baseURL = 'https://categorizeapi.com/api') {
    this.apiKey = apiKey;
    this.baseURL = baseURL;
  }

  async categorize(input, type = 'auto') {
    const res = await fetch(`${this.baseURL}/categorize`, {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${this.apiKey}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({ input, type })
    });
    if (!res.ok) {
      const err = await res.json();
      throw new Error(err.error || 'API error');
    }
    return res.json();
  }
}

// Usage
const client = new CategorizeAPIClient('YOUR_API_KEY');

const result = await client.categorize('https://example.com');
console.log('Category:', result.category);
console.log('Confidence:', Math.round(result.confidence * 100) + '%');

// npm install axios
const axios = require('axios');

const client = axios.create({
  baseURL: 'https://categorizeapi.com/api',
  headers: { 'Authorization': 'Bearer YOUR_API_KEY' }
});

async function categorize(input, type = 'auto') {
  const { data } = await client.post('/categorize', { input, type });
  return data;
}

categorize('https://example.com')
  .then(r => console.log(r.category, r.confidence))
  .catch(e => console.error(e.response?.data?.error || e.message));

Python Examples

Works with Python 3.7+. Uses the requests library (pip install requests).

import requests

class CategorizeAPIClient:
    def __init__(self, api_key: str, base_url: str = "https://categorizeapi.com/api"):
        self.api_key = api_key
        self.base_url = base_url

    def categorize(self, input: str, type: str = "auto") -> dict:
        response = requests.post(
            f"{self.base_url}/categorize",
            headers={"Authorization": f"Bearer {self.api_key}"},
            json={"input": input, "type": type},
            timeout=30
        )
        response.raise_for_status()
        return response.json()

# Usage
client = CategorizeAPIClient("YOUR_API_KEY")
result = client.categorize("https://example.com")

print(f"Category: {result['category']}")
print(f"Confidence: {round(result['confidence'] * 100)}%")

import aiohttp
import asyncio

async def categorize(api_key: str, input: str, type: str = "auto") -> dict:
    async with aiohttp.ClientSession() as session:
        async with session.post(
            "https://categorizeapi.com/api/categorize",
            headers={"Authorization": f"Bearer {api_key}"},
            json={"input": input, "type": type}
        ) as resp:
            return await resp.json()

# Usage
result = asyncio.run(categorize(
    "YOUR_API_KEY",
    "https://example.com"
))
print(result["category"])

PHP Examples

Works with PHP 7.4+. Uses cURL (enabled by default in most PHP installations).

<?php

class CategorizeAPIClient {
    private string $apiKey;
    private string $baseUrl = 'https://categorizeapi.com/api';

    public function __construct(string $apiKey) {
        $this->apiKey = $apiKey;
    }

    public function categorize(string $input, string $type = 'auto'): array {
        $payload = json_encode(['input' => $input, 'type' => $type]);
        $ch = curl_init($this->baseUrl . '/categorize');
        curl_setopt_array($ch, [
            CURLOPT_RETURNTRANSFER => true,
            CURLOPT_POST           => true,
            CURLOPT_POSTFIELDS     => $payload,
            CURLOPT_HTTPHEADER     => [
                'Authorization: Bearer ' . $this->apiKey,
                'Content-Type: application/json'
            ],
            CURLOPT_TIMEOUT        => 30
        ]);
        $body     = curl_exec($ch);
        $httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
        curl_close($ch);

        if ($httpCode !== 200) {
            $err = json_decode($body, true);
            throw new \RuntimeException($err['error'] ?? 'API error');
        }
        return json_decode($body, true);
    }
}

// Usage
$client = new CategorizeAPIClient('YOUR_API_KEY');

$result = $client->categorize('https://example.com');

echo $result['category'] . PHP_EOL;
echo $result['confidence'] . PHP_EOL;

<?php
// composer require guzzlehttp/guzzle
use GuzzleHttp\Client;

$client = new Client([
    'base_uri' => 'https://categorizeapi.com/api/',
    'headers'  => ['Authorization' => 'Bearer YOUR_API_KEY']
]);

$response = $client->post('categorize', [
    'json' => [
        'input' => 'https://example.com',
        'type'  => 'auto'
    ]
]);

$data = json_decode($response->getBody(), true);
echo $data['category'];

Rate Limits

Monthly request limits are enforced per calendar month and reset on the 1st of each month. A separate burst limit of 60 requests/minute applies to every plan.

When you exceed your monthly limit, the API returns HTTP 429. The requests_remaining field in every successful response lets you track usage programmatically.

Changelog

Have a feature request or found a bug? Contact us — we read every message.