Coming soon

API reference

Base URL https://classifierhub.com. JSON in, JSON out. Versioned under /v1.

This capability is not live yet. The reference below describes how it works at launch. Join the waitlist to get Early Access.

Conventions

Authenticate with Authorization: Bearer ch_live_... (see Authentication).
input may be a string, a JSON object or an array, up to 64 KB serialized.
Responses include X-Request-Id, X-Credits-Remaining and X-RateLimit-* headers.
Credits are charged before the model call and refunded automatically if it fails.

POST /v1/decide

Run exactly one of: a saved decision (slug or id, optional version), a template id, an inline config, or a single yes/no question.

request

json

{ "template": "email-triage", "input": { "from": "a@b.co", "subject": "Refund", "body": "..." } }

{ "decision": "inbox-router", "version": 3, "input": "..." }

{ "question": { "instructions": "Does this action delete data?", "true": "Deletes or overwrites data", "false": "Read-only" },
  "input": { "action": "DROP TABLE users" } }

response

json

{
  "id": "0c6e...",
  "object": "decision.execution",
  "decision": { "id": null, "slug": null, "version": null, "template": "email-triage" },
  "outputs": {
    "category": { "type": "choice", "value": "billing", "confidence": 0.94, "probabilities": { "billing": 0.94, "...": 0 } },
    "urgent":   { "type": "boolean", "value": false, "probability": 0.21 }
  },
  "usage": { "credits": 1, "latency_ms": 450 },
  "model": { "provider": "openrouter_decisions", "name": "typesafe/jev-1.13" }
}

Output shapes: choice → value, confidence, probabilities. boolean → value, probability (value is true at ≥ 0.5 unless you set a threshold). score → value (0-based level), raw_score, label, confidence, probabilities.

POST /v1/classify

{ "input": "...", "instructions": "Which team?", "options": ["sales", "support", "billing"] }
// options may also be a map of id -> description (2-50 options)
// -> { "label": "billing", "confidence": 0.9, "probabilities": {...}, "usage": {...} }

POST /v1/score

{ "input": "...", "instructions": "How urgent is this?", "levels": ["Low", "Medium", "High", "Critical"] }
// -> { "score": 2, "raw_score": 2.3, "label": "High", "confidence": 0.7, "probabilities": [..], "usage": {...} }

POST /v1/extract

Reserved. Accepts { input, instructions, schema } and currently returns FEATURE_DISABLED without charging credits. Field extraction will be served by a dedicated provider.

POST /v1/batch

Queue one decision over up to 10,000 items (plan limits apply). Credits for all items are reserved up front and refunded for items that fail.

{ "template": "contact-form-routing",
  "items": [ { "id": "row-1", "input": "..." }, { "id": "row-2", "input": { "message": "..." } } ],
  "webhook_url": "https://example.com/hooks/classifierhub" }
// 202 -> { "job_id": "...", "status": "queued", "total_items": 2, "credits_reserved": 2, "status_url": "/v1/batch/...", "results_url": "/v1/batch/.../results" }

GET /v1/batch/{id}: status and counters.
GET /v1/batch/{id}/results?cursor=0&limit=200: results in input order, paginated with next_cursor.
POST /v1/batch/{id}/cancel: stop pending items and refund them.
If webhook_url is set we POST { type: "batch.completed", data: { job_id, status, ... } } when done. It contains no item data: fetch results with your key.

GET /v1/templates

Lists built-in templates with their outputs and output JSON Schema.

Errors

{ "error": { "code": "INSUFFICIENT_CREDITS", "message": "Not enough credits.", "details": { "required": 1, "available": 0 } } }

Code	HTTP	Meaning
`UNAUTHORIZED`	401	Missing Authorization header.
`INVALID_API_KEY`	401	Unknown, expired or revoked key.
`FORBIDDEN`	403	The key or user may not perform this action.
`VALIDATION_ERROR`	400	The body failed validation; see details.issues.
`NOT_FOUND`	404	Decision, template or batch not found.
`INSUFFICIENT_CREDITS`	402	Not enough credits; details.required and details.available.
`RATE_LIMITED`	429	Too many requests; honor Retry-After.
`FEATURE_DISABLED`	403	Endpoint or output type not available yet (e.g. extraction).
`PAYLOAD_TOO_LARGE`	413	Input over 64 KB or body too large.
`PROVIDER_UNAVAILABLE`	503	Model provider timed out or is overloaded. Credits refunded; retry with backoff.
`PROVIDER_ERROR`	502	Model provider returned an invalid answer. Credits refunded.
`NOT_CONFIGURED`	503	Service temporarily unavailable.
`CONFLICT`	409	The request conflicts with current state.
`INTERNAL`	500	Unexpected error. Credits refunded.

Rate limits

Per workspace, per minute: Free 30, Starter 120, Pro 300, Business 600. Batch submissions: 10 per minute. On 429, wait for Retry-After seconds.