Documentazione API
Riferimento completo per le API REST dell'Events Dashboard.
Autenticazione
Le API di lettura (GET) sono pubbliche. Le API di scrittura (POST) richiedono un API key nell'header.
# Header richiesto per POST
x-api-key: ek_your_api_key_here
Canali disponibili
Il campo channel accetta uno dei seguenti valori.
race_control pit_lane weather driver team session custom /api/events Richiede API key Crea un nuovo evento nel sistema.
Request body
Content-Type: application/json
{
"channel": "race_control",
"title": "Safety Car Deployed",
"description": "Yellow flag in Sector 2 after incident.",
"icon": "🚩",
"tags": [
"safety_car",
"sector_2"
],
"url": "https://example.com/race/lap-42",
"is_important": true,
"metadata": {
"lap": 42,
"sector": 2
}
} Campi
| Campo | Tipo | Obbligatorio | Note |
|---|---|---|---|
channel | string | No (default: custom) | Uno dei canali sopra elencati |
title | string | Sì | Max 200 caratteri |
description | string | No | Max 1000 caratteri |
icon | string | No | Emoji, max 10 caratteri |
tags | string[] | No | Max 10 tag |
url | string | No | URL valido |
is_important | boolean | No (default: false) | Marca evento come importante |
metadata | object | No | JSON arbitrario |
Response 201 Created
{
"status": "success",
"data": {
"id": "uuid-here",
"created_at": "2026-03-04T12:00:00Z"
}
} /api/events Pubblico Restituisce la lista degli eventi con supporto a filtri e paginazione.
Query parameters
GET /api/events?channel=race_control&q=safety&limit=20&offset=0
| Param | Tipo | Note |
|---|---|---|
channel | string | Filtra per canale |
q | string | Full-text search su title e description |
limit | number | Default 50, max 100 |
offset | number | Default 0 |
Response 200 OK
{
"status": "success",
"data": [
{
"id": "...",
"channel": "race_control",
"title": "...",
"created_at": "..."
}
],
"meta": {
"page": 1,
"limit": 20,
"total": 142,
"offset": 0,
"hasMore": true
}
} /api/events/stats Pubblico Restituisce statistiche aggregate: totali, trend giornaliero e distribuzione per canale.
Query parameters
GET /api/events/stats?period=24h
period: 24h (default) | 7d | 30d | all
Response 200 OK
{
"status": "success",
"data": {
"total": 142,
"today": 18,
"period": 18,
"periodLabel": "24h",
"uniqueChannels": 5,
"byChannel": {
"race_control": 40,
"driver": 35,
"weather": 20
},
"last7Days": [
{
"date": "2026-02-26",
"count": 12
},
{
"date": "2026-02-27",
"count": 8
}
],
"latest": {
"id": "...",
"title": "...",
"channel": "driver",
"created_at": "..."
}
}
} /api/search Pubblico Ricerca globale su eventi, canali e tag in un'unica chiamata. Richiede almeno 2 caratteri.
Query parameters
GET /api/search?q=safety&limit=10
q: stringa di ricerca (min 2 caratteri) |
limit: max risultati eventi (default 10, max 50)
Response 200 OK
{
"status": "success",
"data": {
"events": [
{
"id": "...",
"title": "Safety Car",
"channel": "race_control",
"created_at": "..."
}
],
"channels": [
{
"name": "race_control",
"count": 3
}
],
"tags": [
{
"name": "safety_car",
"count": 5
}
]
}
} Formato errori
Tutte le API restituiscono errori con lo stesso formato.
{
"status": "error",
"error": {
"code": "VALIDATION_ERROR",
"message": "Invalid request data",
"details": {
"title": [
"Il titolo è obbligatorio"
]
}
}
} | Codice | HTTP | Descrizione |
|---|---|---|
VALIDATION_ERROR | 400 | Body o parametri non validi |
UNAUTHORIZED | 401 | API key mancante |
FORBIDDEN | 403 | API key non valida o disabilitata |
RATE_LIMITED | 429 | Troppe richieste |
DATABASE_ERROR | 500 | Errore database |
INTERNAL_ERROR | 500 | Errore interno imprevisto |
Esempio rapido — curl
# Crea un evento
curl -X POST https://your-domain.vercel.app/api/events \
-H "Content-Type: application/json" \
-H "x-api-key: ek_your_key" \
-d '{
"channel": "driver",
"title": "Fastest Lap — Hamilton",
"icon": "🏎️",
"is_important": true
}' # Leggi gli eventi più recenti
curl https://your-domain.vercel.app/api/events?limit=10