Quickstart - Classify

Authenticate

Every request carries your API key as a bearer token. Keys look like ck_... and are shown once at creation.

export CLASSIFY_API_KEY=ck_your_key_here

Classify a URL

curl -s -X POST https://api.classify.ai/v1/classify \
  -H "Authorization: Bearer $CLASSIFY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"urls": ["https://en.wikipedia.org/wiki/Electric_vehicle"]}'

If the URL is in ContentGraph, classifications come back inline:

{
  "results": [{
    "url": "https://en.wikipedia.org/wiki/Electric_vehicle",
    "status": "classified",
    "classifications": [
      { "rank": 0, "distance": "0.13", "iab_code": "22",
        "iab_name": "Automotive > Auto Type > Green Vehicles" }
    ]
  }],
  "count": 1,
  "latency_ms": 8
}

If it isn’t, we classify it on demand: you get status: "unknown" plus a job_id, and a hold is placed on the on-demand credits while we work. Poll the job:

curl -s https://api.classify.ai/v1/jobs/JOB_ID \
  -H "Authorization: Bearer $CLASSIFY_API_KEY"

If the page can’t be classified, the job finishes as unknown and the hold is released, so you’re never charged for it. Each result carries a diag object you can inspect.

Result statuses

Status	Meaning
`classified`	Ranked IAB 3.1 classifications, strongest match first
`unknown / no_match`	The page was read, but nothing in the reference set is a close enough match to label
`unknown / insufficient_content`	Too little readable content to classify, most often client-rendered JS shells
`error`	Fetch or processing failure; `reason` names it

Classify returns insufficient_content when a page has too little to read. The diag object shows what was read so you can verify.