API Guide — ClassifyHub

1. Get an API key

Sign in to your workspace as an admin.
Make sure your workspace is on a paid plan (Pro or Enterprise) — keys are created freely but only authenticate while a paid subscription is active. Upgrade under Admin Console → Billing.
Open Admin Console → API Access, name your key after the integration (e.g. jira-sync) and click Create key.
Copy the key immediately — it is shown only once. We store a hash, not the key.

Treat keys like passwords. Never embed them in browser code or mobile apps, never commit them to git. Use one key per integration so you can revoke one without breaking the others.

2. Authenticate

Send your key in the X-API-Key header on every request. All endpoints are scoped to your workspace — you can only ever see your own data.

# Quick test — list your classification labels
curl https://YOUR-APP-URL/api/v1/labels \
  -H "X-API-Key: chk_your_key_here"

3. Endpoints

Method	Path	What it does
POST	`/api/v1/classify`	Classify one asset and store it in your inventory. Body: `name` (required), `asset_type`, `content`. Returns the label and matched rules.
GET	`/api/v1/assets`	List classified assets, newest first. Query params: `q` (name contains), `source` (manual \| csv \| agent \| api), `limit` (max 500).
GET	`/api/v1/labels`	Your label scheme with sensitivity levels and colors.
GET	`/api/v1/rules`	Your enabled detection rules in priority order — useful for classifying locally.

Example: classify a document

curl -X POST https://YOUR-APP-URL/api/v1/classify \
  -H "X-API-Key: chk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "vendor-contract-2026.pdf",
    "asset_type": "document",
    "content": "Confidential — NDA. Payment to IBAN DE89370400440532013000"
  }'

# Response
{
  "id": 1042,
  "name": "vendor-contract-2026.pdf",
  "label": { "name": "Confidential", "level": 2, "color": "#f59e0b" },
  "matched_rules": "Marked confidential, Financial data",
  "source": "api",
  "classified_at": "2026-06-12T08:30:00"
}

Example: Python

import requests

API = "https://YOUR-APP-URL/api/v1"
HEADERS = {"X-API-Key": "chk_your_key_here"}

r = requests.post(f"{API}/classify", headers=HEADERS, json={
    "name": "export-customers.csv",
    "content": open("export-customers.csv").read()[:64000],
})
print(r.json()["label"]["name"])

4. Errors

Status	Meaning
`401`	Missing, invalid or revoked API key.
`402`	Your workspace is not on an active paid plan, or an asset/plan quota was reached. The response `detail` says which.
`403`	Workspace suspended — contact support.
`422`	Request body failed validation; `detail` lists the fields.

5. Good practices

One key per integration — revoke compromised or retired integrations individually from Admin Console → API Access.
Rotate keys periodically — create a new key, switch your integration, revoke the old one. Zero downtime.
Send content, not just names — classification accuracy is far higher with the first ~64 KB of content included.
Batch politely — for large backfills, send requests sequentially or a few in parallel; asset quotas from your plan apply to API-created assets too.
Downgrades — if your subscription lapses to Free, keys stop authenticating (HTTP 402) but are not deleted; they resume on upgrade.

Full interactive reference (request/response schemas, try-it-out): /docs. Questions? Contact us.