Collision Intake Triage API

A deployable FastAPI service that turns collision-repair intake notes into a structured operational assessment. It demonstrates API design, typed AI outputs, environment-based configuration, JSON logging, graceful fallback behavior, tests, and Docker packaging.

This service supports intake workflow only. It does not provide a repair estimate or guarantee that a vehicle is safe to drive.

Live demo

• API health: https://collision-intake-api-production.up.railway.app/health
• Swagger docs: https://collision-intake-api-production.up.railway.app/docs

Why this matters

Collision shops lose time when intake details arrive as incomplete calls, emails, photos, and claim notes. This API turns the first customer intake into a structured operational handoff: urgency, conservative drivability guidance, likely damage areas, next steps, customer-ready language, and escalation reasons.

The service intentionally avoids repair estimates, coverage decisions, and safety guarantees. It is designed as a production-style workflow layer that helps a shop triage work faster while keeping human review in the loop.

What it returns

• urgency level
• conservative drivability guidance
• likely damage areas
• required next steps
• customer-ready follow-up language
• escalation reasons
• confidence score
• persisted audit record retrievable by request ID

Architecture

flowchart LR
    Client["Client or shop intake form"] --> API["FastAPI service"]
    API --> Validation["Pydantic validation"]
    Validation --> Model["OpenAI Responses API"]
    Model --> Assessment["Typed IntakeAssessment"]
    Assessment --> Store["SQLite database on Railway volume"]
    Store --> Response["JSON response and audit record"]

Loading

When OPENAI_API_KEY is absent, the service uses a deterministic fallback so local development, health checks, and tests still work.

Assessments are stored in SQLite so each intake can be retrieved later for auditing or workflow handoff.

API endpoints

• POST /v1/intakes creates and assesses an intake.
• POST /v1/intakes/assess keeps backward compatibility with the original assessment endpoint.
• GET /v1/intakes lists recent intake summaries.
• GET /v1/intakes/{request_id} retrieves the full stored intake and assessment.
• GET /health supports deployment health checks.

Run locally

python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
cp .env.example .env
uvicorn app.main:app --reload

Open Swagger UI at http://localhost:8000/docs.

Run with Docker

docker build -t collision-intake-api .
docker run --rm -p 8000:8000 --env-file .env collision-intake-api

Deploy on Railway

1. Push this repository to GitHub.
2. Create a Railway project from the GitHub repository.
3. Railway will detect the Dockerfile and use railway.toml for the /health deployment check.
4. Add service variables:

APP_ENV=production
LOG_LEVEL=INFO
OPENAI_API_KEY=<your key>
OPENAI_MODEL=gpt-5-mini
REQUEST_TIMEOUT_SECONDS=30
DATABASE_PATH=/data/intakes.db

5. Add a volume mounted at /data so saved intake records survive redeploys.
6. Generate a public domain from the service Networking settings.

Example request

curl -X POST http://localhost:8000/v1/intakes \
  -H 'Content-Type: application/json' \
  -d '{
    "customer_name": "Jordan",
    "vehicle": "2021 Toyota RAV4",
    "incident_description": "Rear-ended. Liftgate will not open and the rear bumper is pushed inward.",
    "drivable": true,
    "airbags_deployed": false,
    "warning_lights": [],
    "insurer": "Example Insurance"
  }'

Test

pytest -q

ruff check .
ruff format --check .

The GitHub Actions workflow runs linting, formatting checks, tests, and a Docker image build on every push and pull request.

Retrieve a saved intake

curl http://localhost:8000/v1/intakes/<request_id>

Evaluation fixtures

The tests/fixtures/evaluation_cases.json file captures representative collision scenarios and expected triage behavior. Current fixtures cover airbag deployment, fluid leaks, minor bumper scrape, dashboard warning lights, and non-drivable vehicles.

Production considerations

• Put the container behind HTTPS and an authenticated gateway.
• Do not log claim numbers, phone numbers, images, or other sensitive customer data.
• Add rate limiting and database migrations before multi-environment deployment.
• Run evaluation fixtures before changing prompts or models.
• Human review remains required before communicating safety or repair decisions.

Portfolio talking points

• Designed a typed AI API around a real collision-shop workflow.
• Used structured outputs rather than parsing untrusted free-form JSON.
• Implemented deterministic fallback behavior for resilience and local testing.
• Added request IDs, structured logs, health checks, validation, tests, and Docker packaging.