API Reference

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.

No API key required
RESTful JSON
Built-in crisis detection
6 Cities Supported
POST
/api/classify

Classify needs

GET
/api/classify

Health check

GET
/api/community-resources

List resources

POST
/api/contact

Contact form

GET
/api

Service status

POST/api/classify

The 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

ParameterTypeRequiredDescription
textstringRequiredThe user's description of their situation. Minimum 1 character.
cityIdstringOptionalCity to use for resource matching. Values: "houston", "newyork", "losangeles", "chicago", "dallas", "miami". If omitted, the city is auto-detected from lat/lng.
latnumberOptionalUser's latitude (-90 to 90). Used for distance calculations and city auto-detection.
lngnumberOptionalUser's longitude (-180 to 180). Used for distance calculations and city auto-detection.

Example Request

bash
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
  }'
json
{
  "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):

🏠Housing Assistance
🍲Food Assistance
🧠Mental Health
💼Employment Services
⚖️Legal Aid
🏥Healthcare
🆘Crisis Support
👴Senior Services
🎖️Veteran Services

Error Responses

400
{ "error": "Text input is required" }

Returned when text is missing, empty, or not a string.

500
{ "error": "Internal server error" }

Unexpected server error.

GET/api/classify

Health check and diagnostics endpoint. Returns the current status of the classification service, including whether the BART model is available.

json
{
  "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.
GET/api/community-resources

List community resources from the database. Optionally filter by category, city, or search by keyword across name, description, and services.

Query Parameters

ParameterTypeRequiredDescription
categorystringOptionalFilter by category (e.g., "Housing Assistance", "Food Assistance"). Pass "All" or omit for all categories.
cityIdstringOptionalFilter by city. Values: "houston", "newyork", "losangeles", "chicago", "dallas", "miami". Omit for all cities.
searchstringOptionalSearch across resource name, description, and services fields.

Example Requests

All resources:

bash
curl https://your-domain.com/api/community-resources

Filter by category:

bash
curl "https://your-domain.com/api/community-resources?category=Food%20Assistance"

Filter by city:

bash
curl "https://your-domain.com/api/community-resources?cityId=newyork"

Search resources:

bash
curl "https://your-domain.com/api/community-resources?search=snap"

Response

json
{
  "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.

POST/api/contact

Submit a contact form message. Currently logs messages to the server console — email notification is planned for a future release.

Request Body

ParameterTypeRequiredDescription
namestringRequiredContact's full name.
emailstringRequiredContact's email address.
subjectstringOptionalMessage subject.
messagestringRequiredThe message body.

Example Request

bash
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)

json
{
  "success": true,
  "message": "Thank you for your message. We'll get back to you soon."
}

Error Responses

400
{ "error": "Name, email, and message are required" }

Returned when any required field is missing.

500
{ "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.

GET/api

Basic health check endpoint. Returns the service status and version — useful for uptime monitoring.

json
{
  "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.

25 mi
City Metro Core
Exact distance shown
100 mi
Extended Service Area
"Outside metro area" note
100+ mi
Outside All Service Areas
National + nearest city

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

1

Check the API status

bash
curl https://your-domain.com/api/classify
2

Classify a user's needs

javascript
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)' : ''}`));
  });
}
3

Browse community resources

javascript
// 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.