Skip to content

API_REFERENCE.md

Latest commit

 

History

History
242 lines (175 loc) · 4.77 KB

API_REFERENCE.md

File metadata and controls

242 lines (175 loc) · 4.77 KB

API Reference

The MechaPulse backend exposes a REST API built with FastAPI. Two server variants exist; both share the prediction model and the core /predict endpoint.

Server File Base URL Extra Capabilities
Lightweight desktop-app/backend/main.py http://localhost:8000 Prediction only
Full-featured desktop-app/backend/api/app.py http://localhost:8000 Prediction + audio recording

Interactive API documentation (Swagger UI) is auto-generated by FastAPI and available at:

http://localhost:8000/docs

ReDoc documentation:

http://localhost:8000/redoc

Table of Contents

Data Models

Input

The feature vector used for machine failure prediction.

{
  "RMS":  0.0,
  "Mean": 0.0,
  "MA1":  0.0,
  "MA2":  0.0,
  "MA3":  0.0,
  "F1":   0.0,
  "F2":   0.0,
  "F3":   0.0
}
Field Type Description
RMS float Root Mean Square of the audio signal amplitude
Mean float Mean absolute amplitude of the audio signal
MA1 float Largest FFT magnitude (dominant frequency amplitude)
MA2 float Second largest FFT magnitude
MA3 float Third largest FFT magnitude
F1 float Frequency (Hz) corresponding to MA1
F2 float Frequency (Hz) corresponding to MA2
F3 float Frequency (Hz) corresponding to MA3

Endpoints

GET /

Health-check / root endpoint.

Response

{
  "msg": "Machine Failure Predictor"
}
Code Meaning
200 OK Service is running

POST /predict

Submit a pre-computed feature vector and receive a machine failure prediction.

Request Body — application/json (Input model)

{
  "RMS":  120.45,
  "Mean": 98.12,
  "MA1":  5430.0,
  "MA2":  3210.0,
  "MA3":  1890.0,
  "F1":   440.0,
  "F2":   880.0,
  "F3":   1320.0
}

Response

{
  "prediction": 1
}
Field Type Description
prediction int 0 = Normal operation · 1 = Fault detected

Status Codes

Code Meaning
200 OK Prediction returned successfully
422 Unprocessable Entity Request body validation failed

Example (curl)

curl -X POST "http://localhost:8000/predict" \
  -H "Content-Type: application/json" \
  -d '{
        "RMS": 120.45, "Mean": 98.12,
        "MA1": 5430.0, "MA2": 3210.0, "MA3": 1890.0,
        "F1": 440.0,   "F2": 880.0,   "F3": 1320.0
      }'

POST /start-recording

(Full-featured server only — api/app.py)

Start capturing audio from the local microphone, extract features, and return a prediction. Recording continues in a loop until /stop-recording is called.

Request Body — none

Response

{
  "status": "success",
  "prediction": 0
}
Field Type Description
status string "success" on successful capture + prediction
prediction int 0 = Normal · 1 = Fault

Recording parameters (hardcoded in api/app.py):

Parameter Value
Sample rate 48 000 Hz
Duration 5 seconds per capture
Channels 1 (mono)

Status Codes

Code Meaning
200 OK Recording started and first prediction returned
500 Internal Server Error Audio device not available

POST /stop-recording

(Full-featured server only — api/app.py)

Stop the continuous recording loop started by /start-recording.

Request Body — none

Response

{}
Code Meaning
200 OK Recording stopped

POST /receive-request

(Lightweight server only — backend/main.py)

Acknowledge receipt of an HTTP request from an edge device (e.g., ESP32 sending an alert).

Request Body — none

Response

{
  "status": "success",
  "message": "Request received successfully"
}
Code Meaning
200 OK Request acknowledged

Error Responses

FastAPI returns standard HTTP error responses with a JSON body:

{
  "detail": [
    {
      "loc": ["body", "RMS"],
      "msg": "value is not a valid float",
      "type": "type_error.float"
    }
  ]
}
Code Cause
422 Unprocessable Entity Request body does not match the Input schema
500 Internal Server Error Model loading failure or audio device error