ClearPath AI API Docs
Integrate ClearPath AI into your application. Classify user needs, detect crisis situations, and retrieve community resources across 6 major U.S. cities.
/api/classifyClassify needs
/api/classifyHealth check
/api/community-resourcesList resources
/api/contactContact form
/apiService status
/api/classifyThe core endpoint. Send a user's description of their situation and receive classified needs with matched community resources. Crisis detection is built-in and always active — it runs before AI classification and is never delegated to the model.
Request Body
| Parameter | Type | Required | Description |
|---|---|---|---|
| text | string | Required | The user's description of their situation. Minimum 1 character. |
| cityId | string | Optional | City to use for resource matching. Values: "houston", "newyork", "losangeles", "chicago", "dallas", "miami". If omitted, the city is auto-detected from lat/lng. |
| lat | number | Optional | User's latitude (-90 to 90). Used for distance calculations and city auto-detection. |
| lng | number | Optional | User's longitude (-180 to 180). Used for distance calculations and city auto-detection. |
Example Request
curl -X POST https://your-domain.com/api/classify \
-H "Content-Type: application/json" \
-d '{
"text": "I lost my job and I can not afford rent this month",
"cityId": "houston",
"lat": 29.7604,
"lng": -95.3698
}'{
"isCrisis": false,
"categories": [
{
"label": "Housing Assistance",
"confidence": 87,
"resources": [
{
"name": "Houston Housing Authority",
"detail": "Emergency housing assistance...",
"phone": "713-260-0600",
"address": "2640 Fountain View Dr, Houston, TX",
"hours": "Mon-Fri 8am-5pm",
"eligibility": "Low-income Houston residents",
"verified": true,
"distance": "3.2 mi",
"isNational": false
}
],
"why": "Matched by BART-large-MNLI semantic analysis of your description.",
"also": "You may also benefit from Food Assistance and Employment Services.",
"warning": "87% confidence — consider providing more detail for a better match"
}
],
"needsClarification": false,
"clarificationMessage": null,
"clarificationQuestions": null,
"model": "BART-large-MNLI (live)",
"classificationSource": "bart",
"hasLocation": true,
"cityId": "houston",
"cityLabel": "Houston, TX",
"outsideServiceArea": false,
"serviceArea": "Houston, TX",
"debug": { /* diagnostic info */ }
}Response Fields
isCrisisbooleanWhether crisis language was detected.categoriesarrayMatched categories with resources, confidence scores, and explanations.categories[].labelstringOne of 9 categories (see below).categories[].confidencenumber0–100 confidence score.categories[].resourcesarrayMatched community resources with name, phone, address, hours, distance, isNational flag.categories[].whystringHuman-readable explanation of why this category was matched.categories[].alsostring?Suggestion of other potentially relevant categories.categories[].warningstring?Shown when confidence is below 70%.needsClarificationbooleanTrue when top confidence is below 70% or no categories matched.clarificationQuestionsarray?Follow-up questions to help narrow down the user's needs.modelstringWhich model was used (BART-large-MNLI or keyword matching).classificationSourcestring"bart" or "keyword" — always honest about the source.hasLocationbooleanWhether lat/lng were provided.cityIdstringThe detected or selected city ID (e.g., "houston", "newyork").cityLabelstringHuman-readable city name (e.g., "Houston, TX", "New York, NY").outsideServiceAreabooleanWhether the user is more than 100 miles from ANY supported city.serviceAreastringThe detected or selected city name (e.g., "Houston, TX").debugobjectDiagnostic info about the classification pipeline (API key status, fetch results, etc.).Classification Categories
Text is classified against these 9 categories using BART-large-MNLI zero-shot classification (or keyword matching as a fallback):
Error Responses
{ "error": "Text input is required" }Returned when text is missing, empty, or not a string.
{ "error": "Internal server error" }Unexpected server error.
/api/classifyHealth check and diagnostics endpoint. Returns the current status of the classification service, including whether the BART model is available.
{
"status": "ok",
"service": "ClearPath AI Classification API",
"version": "4.0.0",
"model": "facebook/bart-large-mnli",
"bartAvailable": true,
"apiKeyPrefix": "hf_xxxx...",
"apiKeyLength": 40,
"classificationMode": "BART-large-MNLI (live)",
"crisisDetection": "regex-based (deterministic)",
"multiCity": true,
"supportedCities": [
{ "id": "houston", "label": "Houston, TX", "lat": 29.7604, "lng": -95.3698 },
{ "id": "newyork", "label": "New York, NY", "lat": 40.7128, "lng": -74.0060 },
{ "id": "losangeles", "label": "Los Angeles, CA", "lat": 34.0522, "lng": -118.2437 },
{ "id": "chicago", "label": "Chicago, IL", "lat": 41.8781, "lng": -87.6298 },
{ "id": "dallas", "label": "Dallas, TX", "lat": 32.7767, "lng": -96.7970 },
{ "id": "miami", "label": "Miami, FL", "lat": 25.7617, "lng": -80.1918 }
],
"labels": [
"Housing Assistance",
"Food Assistance",
"Mental Health",
"Employment Services",
"Legal Aid",
"Healthcare",
"Crisis Support",
"Senior Services",
"Veteran Services"
],
"resourceCount": 42
}Key Fields
bartAvailablebooleanWhether HUGGINGFACE_API_KEY is configured and BART classification is active.classificationModestringDescriptive label: "BART-large-MNLI (live)" or "Keyword matching (fallback)".crisisDetectionstringAlways "regex-based (deterministic)" — crisis detection never uses AI.multiCitybooleanWhether multi-city support is enabled. Always true in v4.0.0+.supportedCitiesarrayArray of supported city objects with id, label, and center coordinates.labelsstring[]The 9 classification categories.resourceCountnumberTotal number of community resources in the database./api/community-resourcesList community resources from the database. Optionally filter by category, city, or search by keyword across name, description, and services.
Query Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| category | string | Optional | Filter by category (e.g., "Housing Assistance", "Food Assistance"). Pass "All" or omit for all categories. |
| cityId | string | Optional | Filter by city. Values: "houston", "newyork", "losangeles", "chicago", "dallas", "miami". Omit for all cities. |
| search | string | Optional | Search across resource name, description, and services fields. |
Example Requests
All resources:
curl https://your-domain.com/api/community-resourcesFilter by category:
curl "https://your-domain.com/api/community-resources?category=Food%20Assistance"Filter by city:
curl "https://your-domain.com/api/community-resources?cityId=newyork"Search resources:
curl "https://your-domain.com/api/community-resources?search=snap"Response
{
"resources": [
{
"id": 1,
"name": "Houston Food Bank",
"description": "Distributes food to families in need across Houston.",
"services": "Food distribution, SNAP application assistance",
"category": "Food Assistance",
"phone": "832-369-9390",
"address": "535 Portwall St, Houston, TX 77029",
"hours": "Mon-Fri 8am-5pm",
"eligibility": "Open to all Houston residents",
"verified": true,
"cityId": "houston",
"isNational": false
}
],
"categories": [
"Crisis Support",
"Employment Services",
"Food Assistance",
"Healthcare",
"Housing Assistance",
"Legal Aid",
"Mental Health",
"Senior Services",
"Veteran Services"
]
}Response Fields
resourcesarrayArray of resource objects from the database, sorted alphabetically by name. Includes cityId and isNational fields for multi-city filtering.categoriesstring[]Distinct category values available for filtering. Useful for building filter UIs.Resources are stored in a SQLite database via Prisma ORM. If the database is unavailable, the endpoint returns empty arrays instead of crashing.
/api/contactSubmit a contact form message. Currently logs messages to the server console — email notification is planned for a future release.
Request Body
| Parameter | Type | Required | Description |
|---|---|---|---|
| name | string | Required | Contact's full name. |
| string | Required | Contact's email address. | |
| subject | string | Optional | Message subject. |
| message | string | Required | The message body. |
Example Request
curl -X POST https://your-domain.com/api/contact \
-H "Content-Type: application/json" \
-d '{
"name": "Jane Doe",
"email": "jane@example.com",
"subject": "Partnership inquiry",
"message": "We would love to partner with ClearPath AI..."
}'Success Response (200)
{
"success": true,
"message": "Thank you for your message. We'll get back to you soon."
}Error Responses
{ "error": "Name, email, and message are required" }Returned when any required field is missing.
{ "error": "Failed to process your message" }Unexpected server error.
Current status: Messages are logged to the server console. Email notification via SendGrid/Resend is planned. No data is persisted to the database yet.
/apiBasic health check endpoint. Returns the service status and version — useful for uptime monitoring.
{
"status": "ok",
"service": "ClearPath AI",
"version": "4.0.0"
}Response Fields
statusstringAlways "ok" when the service is running.servicestringService name: "ClearPath AI".versionstringAPI version: "4.0.0".For more detailed diagnostics (BART availability, API key status, resource count), use GET /api/classify instead.
Our Commitment to Honesty
ClearPath AI is built on a foundation of transparency. Here's what that means for the API:
Honest classification source
Every response tells you whether it used BART AI or keyword matching. We never pretend keyword results are AI-generated.
Deterministic crisis detection
Crisis detection uses regex patterns, not AI. The model is never trusted for crisis situations — it's too important to leave to probability.
Confidence-aware responses
When we're not sure, we say so — and ask follow-up questions instead of guessing.
Full debug transparency
The debug field in classify responses exposes the full classification pipeline — API key status, fetch results, fallback reasons.
Service Area
ClearPath AI serves 6 major U.S. cities: Houston, New York, Los Angeles, Chicago, Dallas, and Miami. Each city has its own set of community resources, and national resources are available everywhere.
Users outside all service areas still receive national resources and resources from the nearest supported city. Use the cityId parameter to explicitly select a city.
Quick Start
Check the API status
curl https://your-domain.com/api/classifyClassify a user's needs
const response = await fetch('/api/classify', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({
text: 'I need help finding affordable housing in Houston',
cityId: 'houston',
lat: 29.7604,
lng: -95.3698
})
});
const data = await response.json();
console.log('City:', data.cityLabel); // "Houston, TX"
if (data.isCrisis) {
// Show crisis resources immediately
console.log('Crisis detected:', data.crisisLines);
} else {
// Show classified categories with resources
data.categories.forEach(cat => {
console.log(`${cat.label} (${cat.confidence}%)`);
cat.resources.forEach(r => console.log(` - ${r.name}${r.isNational ? ' (National)' : ''}`));
});
}Browse community resources
// Get all resources
const res = await fetch('/api/community-resources');
const { resources, categories } = await res.json();
// Filter by category
const foodRes = await fetch('/api/community-resources?category=Food%20Assistance');
const { resources: foodResources } = await foodRes.json();
// Filter by city
const nyRes = await fetch('/api/community-resources?cityId=newyork');
const { resources: nyResources } = await nyRes.json();
// Search by keyword
const searchRes = await fetch('/api/community-resources?search=veteran');
const { resources: veteranResources } = await searchRes.json();Frequently Asked Questions
Ready to integrate?
Start classifying user needs and connecting people to community resources in minutes. No API key required.