# Music Monitor — API Documentation

Guida tecnica e architetturale per l'integrazione del frontend (Next.js) con il backend API-only di **Music Monitor**.

---

## 1. Intestazione ed Endpoint Base

Il backend è un'applicazione Laravel API-only che restituisce esclusivamente payload in formato JSON.

- **Base URL di produzione/LAN**: `http://192.168.178.100:8000/api` (o l'indirizzo IP/dominio configurato sul server).
- **Convenzione Next.js**:
  Nel progetto Next.js, configurare l'URL base tramite variabile d'ambiente:
  ```typescript
  const API_URL = process.env.NEXT_PUBLIC_API_URL ?? 'http://192.168.178.100:8000/api';
  ```

---

## 2. Autenticazione (Laravel Sanctum)

Tutti gli endpoint protetti richiedono l'invio dell'header di autorizzazione Bearer Token:

```http
Authorization: Bearer <tuo_token_sanctum>
Accept: application/json
Content-Type: application/json
```

### Token di Test Locale (per Giacomo)
Per i primi test di integrazione frontend, è possibile utilizzare il seguente token Sanctum valido pre-generato:
```text
1|UYpiKaP1Jpu5iDyLVfBo1jKpHqjuNPmuvXY7JuNsb945a3dd
```

---

## 3. Endpoint Health Check

Permette di monitorare lo stato di salute dei servizi critici (Database PostgreSQL, Redis e Ollama).

- **URL**: `GET /api/health`
- **Autenticazione**: Non richiesta (pubblico).

### Esempio di Risposta JSON (200 OK / 503 Se degraded)
```json
{
  "status": "ok",
  "timestamp": "2026-10-20T18:00:00+00:00",
  "services": {
    "database": "up",
    "redis": "up",
    "ollama": "up"
  }
}
```

---

## 4. Endpoint di Ricerca Ibrida (Vector + Deterministic Filters)

Esegue una ricerca semantica avanzata combinando la similarità vettoriale tramite `pgvector` (modello Ollama `nomic-embed-text`) con filtri strutturati opzionali.

- **URL**: `POST /api/search`
- **Autenticazione**: Richiesta (`Authorization: Bearer <token>`).

### Parametri del Body JSON (Request Payload)
| Parametro | Tipo | Obbligatorio | Default | Descrizione |
|---|---|---|---|---|
| `query` | string | **Sì** | - | Testo o descrizione della ricerca (es. `"Techno DJ based in Berlin"`). Minimo 2 caratteri. |
| `limit` | integer | No | 10 | Numero massimo di risultati restituiti (max 50). |
| `threshold` | float | No | 0.70 | Soglia minima di similarità coseno (da 0.0 a 1.0) per lo sbarramento semantico. |
| `country_iso2` | string | No | - | Filtro deterministico per nazione (es. `"DE"`, `"GB"`, `"US"`). Esattamente 2 caratteri. |
| `department` | string | No | - | Filtro deterministico parziale per dipartimento/ruolo (es. `"Marketing"`, `"A&R"`). |

### Esempio di Payload di Richiesta
```json
{
  "query": "Techno DJ based in Berlin",
  "limit": 5,
  "threshold": 0.60,
  "country_iso2": "DE",
  "department": "Music"
}
```

### Esempio di Risposta JSON (200 OK)
```json
{
  "status": "success",
  "query": "Techno DJ based in Berlin",
  "count": 1,
  "data": [
    {
      "id": 142,
      "external_id": 987654321,
      "full_name": "Hans Weber",
      "first_name": "Hans",
      "last_name": "Weber",
      "headline": "Resident DJ & Producer at Club der Visionaere",
      "summary": "Techno and minimal DJ based in Berlin, Germany.",
      "department": "Music & Production",
      "country_iso2": "DE",
      "is_decision_maker": true,
      "profile_score": 0.9500,
      "linkedin_url": "https://www.linkedin.com/in/hansweber",
      "website": "https://hansweber.de",
      "metadata": {
        "source": "import_file.json",
        "custom_fields": {}
      },
      "similarity": 0.8924,
      "created_at": "2026-10-20T12:00:00+00:00",
      "updated_at": "2026-10-20T12:00:00+00:00"
    }
  ]
}
```

---

## 5. Note Comportamentali ed Errori Standard

Tutte le risposte di errore seguono lo standard JSON di Laravel:

- **401 Unauthorized**: Token mancante o non valido.
  ```json
  {
    "message": "Unauthenticated."
  }
  ```
- **422 Unprocessable Entity**: Validazione dei parametri fallita (es. query mancante o formato errato).
  ```json
  {
    "message": "The query field is required.",
    "errors": {
      "query": ["The query field is required."]
    }
  }
  ```
- **503 Service Unavailable**: Servizio Ollama non raggiungibile in LAN o errore di generazione embedding.
  ```json
  {
    "error": "Servizio Ollama non raggiungibile o impossibile generare embedding"
  }
  ```
