API documentation

Classifies free-text credential and education descriptions into a standard taxonomy. Everything below reflects the live, deployed API.

Authentication

Every request except /signup and /verify-token needs an X-API-Key header. Don't have one yet? Get a free key. 

curl -X POST https://degree-classification.onrender.com/classify \
     -H "Content-Type: application/json" \
     -H "X-API-Key: YOUR_KEY" \
     -d '{"text": "bachlers in compueter sciecne"}'

Quick start

curl -X POST https://degree-classification.onrender.com/classify \
     -H "Content-Type: application/json" \
     -H "X-API-Key: YOUR_KEY" \
     -d '{"text": "bachlers in compueter sciecne"}'
import requests

response = requests.post(
    "https://degree-classification.onrender.com/classify",
    headers={"X-API-Key": "YOUR_KEY"},
    json={"text": "bachlers in compueter sciecne"},
)
print(response.json())
const res = await fetch("https://degree-classification.onrender.com/classify", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "X-API-Key": "YOUR_KEY",
  },
  body: JSON.stringify({ text: "bachlers in compueter sciecne" }),
});
const data = await res.json();
console.log(data);

Response

{
  "input": "bachlers in compueter sciecne",
  "level": "bachelor",
  "field": "computer science",
  "confidence": 0.91,
  "method": "fuzzy_alias_match"
}

Endpoints

Classify

POST /classify

Classifies a single piece of text.

Field Type Description
text string, required The free-text credential description.
use_trained_classifier boolean, optional Use the trained ML model instead of the default rules and embeddings pipeline for the semantic match layer. Default false. See the demo page for a side by side comparison.
POST /classify/batch

Same as above, but takes a JSON array of {"text": "...", "use_trained_classifier": false} objects and returns an array of results in the same order. 

curl -X POST https://degree-classification.onrender.com/classify/batch \
     -H "Content-Type: application/json" \
     -H "X-API-Key: YOUR_KEY" \
     -d '[{"text": "PharmD"}, {"text": "some made up credential"}]'

Response fields

Field Description
input The original text you sent.
level One of the 11 taxonomy levels below, or null if nothing matched confidently. Never a guessed answer.
field Extracted major or field if present (for example "computer science" from "bachelor's in computer science"), else null.
confidence 0.0 to 1.0. Exact and keyword matches are typically 0.9 and up. Semantic matches vary.
method Which pipeline layer produced the answer. See below.

Taxonomy levels

ged_or_hs_equivalency high_school_diploma vocational_certificate associate bachelor master doctorate_academic doctorate_professional rn_diploma residency_fellowship professional_certification

Method values

Method Meaning
exact_alias_match The input exactly matched a known phrasing.
keyword_containment_match A distinctive alias phrase was found standalone inside a longer sentence.
fuzzy_alias_match Typo tolerant match against a known phrasing.
semantic_match Matched by meaning or similarity, not exact wording.
llm_fallback An LLM resolved genuinely novel phrasing the rules above missed.
negation_detected The input explicitly denies holding a credential, like "not a real degree." Returns null.
incomplete_education_detected The input describes education in progress or never finished. Returns null.
unmatched_needs_review Nothing matched confidently. Returns null rather than guessing.

Usage

GET /usage

Returns your call count and last called time.

curl https://degree-classification.onrender.com/usage \
     -H "X-API-Key: YOUR_KEY"
{ "tenant_id": "you@company.com", "call_count": 42, "last_called": "2026-08-01T12:00:00Z" }

Signup, no auth required

POST /signup

Email plus optional company. Sends a one-time verification link and does not issue a key directly. See the Get API key page for the actual signup form.

POST /verify-token

Exchanges a valid, unused verification token from the emailed link for a real API key. Single use.

Rate limits and errors

Status Meaning
401 Missing, invalid, or revoked X-API-Key.
429 Rate limit exceeded. Self-serve keys default to 30 requests per minute.
400 Malformed request, for example an invalid email at signup or an expired or already-used verification token.

Need a higher limit for production use? Reach out. Early-access limits are intentionally conservative, not a hard ceiling.

Good to know

Get an API key ยท Try the live demo