Southwind AI Developer Portal

Autenticazione

Invia la chiave API della tua organizzazione nell’header X-API-Key Conservala in un gestore di segreti o in una variabile d’ambiente: il valore completo viene mostrato una sola volta, al momento della creazione. Se lavori a una startup, scrivi a startup@southwind.ai per sbloccare una chiave API con 100 report Rover gratuiti.

curl https://app.southwind.ai/api/v1/me \
  --header 'X-API-Key: $SOUTHWIND_API_KEY'

Concetti fondamentali

Tre risorse accompagnano i dati dalla connessione iniziale fino a un’indagine basata sulle evidenze.

Origine dati

La connessione a monte o il file caricato. Nelle API è una Data Origin e può contenere più sorgenti dati.

Sorgente dati

Un dataset specifico e interrogabile ricavato da un’origine. I report fanno riferimento agli UUID delle sorgenti dati, non agli ID delle origini.

Report

Un’attività di analisi asincrona creata a partire da sorgenti dati pronte all’uso.

Quickstart: dall’origine dati al report

Crea un’origine, ricava gli ID delle sorgenti e attendi che tutte quelle necessarie siano pronte prima di creare il report.

1. Crea un’origine con POST /api/v1/origins/file/, POST /api/v1/origins/data-api/ oppure POST /api/v1/origins/postgres/.
2. Ricava gli ID delle sorgenti dati dalla ricevuta restituita dal connettore.
3. Per le origini file e API asincrone, attendi che tutte le sorgenti necessarie raggiungano lo stato completed. Preferisci lo stream degli eventi; il polling è l’alternativa.
4. Se una sorgente raggiunge awaiting_confirmation, consulta metadata.cleaning_plan e invia le decisioni richieste.
5. Se una sorgente file o API raggiunge failed, controlla ingest_error_code e ripeti l’acquisizione.
6. Crea il report con POST /api/v1/reports/ e gli ID delle sorgenti completed.

La risposta alla creazione di un’origine file o API è una ricevuta: le sorgenti tabellari vengono accodate e non sono subito pronte. Creare un report da una sorgente tabellare non ancora completed restituisce 409 Conflict. I documenti PDF, TXT e Markdown non sono soggetti a questo controllo.

Ricevute dei connettori

I tre connettori restituiscono intenzionalmente ricevute con strutture diverse.

Ciclo di acquisizione

Prima di poter essere usata in un report, una sorgente tabellare attraversa il ciclo di acquisizione dei dati, che ne indica lo stato di preparazione.

Create origin
     │
     ▼
  queued → ingesting → analyzing
                         │
              ┌──────────┴──────────┐
              ▼                     ▼
 awaiting_confirmation            failed
              │                     │
              ▼                     ▼
          cleaning             ingest/retry
              │                     │
              └──────────┬──────────┘
                         ▼
                     completed
                         │
                         ▼
                   Create report

Le risposte delle sorgenti dati includono anche ingest_run_id, row_count e size_bytes. I campi facoltativi, come ingest_error_code, non vengono restituiti quando non hanno un valore. collection_name è deprecato e non identifica più una posizione interrogabile.

Le sorgenti PostgreSQL live vengono interrogate direttamente tramite DuckDB, senza essere materializzate; per questo size_bytes è 0. La propagazione del ciclo a livello di origine è ancora in sviluppo, quindi lo stato dell’origine non è ancora un indicatore affidabile di disponibilità.

Attendere con SSE o polling

Lo stream consigliato restituisce lo stato di ogni sorgente circa ogni due secondi e si chiude quando tutte raggiungono completed, awaiting_confirmation oppure failed.

event: status
data: [{"id":"<source-id>","ingest_status":"analyzing","ingest_error_code":null}]

event: done
data: {}

In alternativa, chiama GET /api/v1/sources/?origin_id=<origin-id> ogni 2–5 secondi.

Una risposta positiva alla creazione, alla sincronizzazione o all’aggiornamento di una sorgente non garantisce che i nuovi dati siano già pronti. Attendi sempre la conclusione della nuova acquisizione.

Creare un report

Rover è il punto di partenza consigliato per un’analisi autonoma. Eseguilo su una o più sorgenti completed e orienta l’indagine con un obiettivo.

curl --request POST 'https://app.southwind.ai/api/v1/reports/' \
  --header 'X-API-Key: $SOUTHWIND_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{"agent_id":"rover_report","data_sources_ids":["DATA_SOURCE_ID"],"title":"Analisi delle performance","params":{"language":"italian","currency":"EUR","data_provenance":true,"target_sections":7,"goal":"Individua i principali fattori di performance e definisci le priorità di intervento."}}'

Un report passa normalmente da queued a running, quindi a completed oppure failed. Anche waiting_for_data indica un’elaborazione in corso e compare spesso quando si rigenera un report mentre le sorgenti vengono aggiornate. I client devono tollerare nuovi stati intermedi.

Confermare la pulizia dei dati

Ogni colonna indicata come ambigua in metadata.cleaning_plan richiede una decisione. Invia il formato temporale proposto, un’interpretazione numerica oppure keep_text.

{
  "decisions": [
    {
      "column": "order_date",
      "kind": "temporal",
      "target_type": "date",
      "format": "%d/%m/%Y"
    }
  ],
  "locale": "eu"
}

La sorgente passa a cleaning e poi a completed. Le decisioni vengono riutilizzate negli aggiornamenti successivi finché restano compatibili con i dati in ingresso.

Tradurre un report

Traduci un report completed con POST /api/v1/reports/{task_id}/translate, quindi controlla il report finché la lingua compare in available_languages. Durante l’elaborazione, translation_jobs mostra lo stato di ogni lingua.

POST /api/v1/reports/{task_id}/translate

GET /api/v1/reports/{task_id}?language=italian

Il parametro language è disponibile anche per il salvataggio, la rinomina, l’esportazione e la lettura pubblica del report. Queste operazioni modificano solo la lingua selezionata. Se in seguito cambia il report principale, le traduzioni restano disponibili con translation_stale: true finché non vengono sostituite.

Richiedere una traduzione già esistente o in corso senza replace: true restituisce 409 con translation_exists oppure translation_in_progress. Una lingua non supportata restituisce 400 invalid_language; un report non completed restituisce 409 report_not_ready. Le traduzioni vengono conteggiate separatamente.

Errori

Gli errori API usano una struttura JSON stabile con una descrizione leggibile, un codice utilizzabile dal software e un ID della richiesta.

{"error":{"detail":"...","code":"...","request_id":"..."}}

Gestisci le condizioni in base a code, che è stabile e pensato per il software, non in base a detail. Gli errori lato server includono normalmente request_id.