# SDK

Vibedasher fornisce SDK ufficiali e completamente tipizzati per **TypeScript** e **Python**, generati dalla specifica OpenAPI dell'API in modo che restino sincronizzati con la piattaforma. Sono il modo in cui il tuo stesso codice raggiunge la piattaforma gestita: esegui SQL sui tuoi dataset, attiva aggiornamenti, gestisci connessioni e diritti di accesso, collega una dashboard a dati live, oppure automatizza da uno script, invece che da un agente, qualsiasi cosa facciano gli [strumenti MCP](/it/guides/build-with-your-agent.md).

| Linguaggio | Pacchetto                                                                | Documentato qui |
| ---------- | ------------------------------------------------------------------------ | --------------- |
| TypeScript | [`@vibedasher/client`](https://www.npmjs.com/package/@vibedasher/client) | 4.1.5           |
| Python     | [`vibedasher`](https://pypi.org/project/vibedasher/)                     | 4.3.19          |

Entrambi gli SDK si autenticano con una **chiave API** nell'header `X-Api-Key`. Generane una nell'app sotto **Impostazioni → Chiavi API** su [cloud.vibedasher.com](https://cloud.vibedasher.com) — vedi [Autenticazione](/it/api/authentication.md). (Gli SDK sono il percorso *codice*; se il tuo agente sta guidando Vibedasher via MCP, si autentica invece con `vibedasher login` e non ha bisogno di alcuna chiave — vedi [Crea con il tuo agente](/it/guides/build-with-your-agent.md).)

Nessuno dei due client ha bisogno che gli si dica in quale regione vive il tuo account. Senza URL di base e senza `region`, entrambi risolvono a `https://api.vibedasher.com/api`, che instrada ogni richiesta in base alla credenziale che porta — vedi [Un solo host, instradato dalla tua credenziale](/it/api/authentication.md#one-host-routed-by-your-credential). Passare `region` resta supportato e fissa il client all'hostname proprio di quella regione, `https://api.{region}.vibedasher.com/api`; un `baseUrl` / `base_url` esplicito prevale su entrambi. (`region` è diventato opzionale in `@vibedasher/client` 4.1.5 e `vibedasher` 4.3.19.)

Stai cercando un endpoint specifico? Esplora l'intero **[Riferimento API](/it/reference/vibedasher-sdk-api.md)** — ogni operazione raggruppata per risorsa, con esempi di richiesta curl / Python / TypeScript generati dalle stesse firme su cui gli SDK sono costruiti.

## La forma di ogni chiamata[​](#la-forma-di-ogni-chiamata "Link diretto a La forma di ogni chiamata")

Entrambi gli SDK espongono lo stesso **client fluent raggruppato per risorsa**. Costruiscilo una volta, poi chiama i metodi raggruppati per risorsa. Le firme sono **piatte**: prima i parametri di percorso (nell'ordine del percorso), poi il corpo della richiesta, poi un unico oggetto opzioni finale opzionale che contiene i parametri di query. Non ci sono oggetti wrapper `path` / `query` / `body`.

Le risorse sono le stesse 23 in entrambi i linguaggi, camelCase in TypeScript e snake\_case in Python:

`accounts`, `aiProviders`, `apiKeys`, `chats`, `connections`, `dashboardSubscriptions`, `datasets`, `dbt`, `embedTokens`, `folders`, `groups`, `images`, `questions`, `refreshes`, `skills`, `sql`, `subscriptions`, `tasks`, `templates`, `tools`, `upload`, `users`, `viz`.

Una risposta non-2xx **solleva un'eccezione** — `VibedasherApiError` in entrambi i linguaggi. I metodi non si risolvono mai in un'unione di errore, quindi non devi controllare un risultato prima di usarlo.

## TypeScript[​](#typescript "Link diretto a TypeScript")

```
npm install @vibedasher/client
```

```
import { Vibedasher, VibedasherApiError } from '@vibedasher/client';



const client = new Vibedasher({

  apiKey: process.env.VIBEDASHER_API_KEY!,

});



// List datasets — query params go in the trailing options object

const page = await client.datasets.list({ limit: 50 });



// Create — the body is positional

const created = await client.datasets.create({ name: 'Sales', type: 'csv' });



// Fetch one by id — path params are positional

const one = await client.datasets.get(created.dataset.id);



// Update — path param, then body

const updated = await client.datasets.update(one.dataset.id, { name: 'Sales 2026' });
```

Ogni metodo è tipizzato end-to-end: i tipi degli argomenti e il tipo di risposta risolto provengono dalla specifica, e le interfacce per risorsa (`DatasetsResource`, `DatasetsListOptions`, …) e i tipi di modello (`DatasetResponse`, `DatasetUpdate`, …) sono esportati dalla radice del pacchetto se vuoi annotare una variabile.

### Eseguire SQL[​](#eseguire-sql "Link diretto a Eseguire SQL")

`client.query` è il metodo scritto a mano che la superficie generata non ha: una chiamata in ingresso, risultati columnar tipizzati in uscita.

```
const result = await client.query({

  sql: 'SELECT country, SUM(revenue) AS revenue FROM sales GROUP BY 1',

});

console.log(result.columns, result.rows);
```

`datasetIds` è opzionale — omettilo e il server risolve l'insieme di dataset a partire dagli alias a cui il tuo SQL fa riferimento, applicando esattamente la stessa autorizzazione.

### Caricare un CSV[​](#caricare-un-csv "Link diretto a Caricare un CSV")

```
const uploaded = await client.datasets.upload({

  name: 'Sales',

  content: 'country,revenue\nFR,10\nDE,12\n',

});

console.log(uploaded.cleanSQLName); // the alias to use in client.query SQL
```

### Via di fuga[​](#via-di-fuga "Link diretto a Via di fuga")

Il client `fetch` sottostante è disponibile sull'istanza come `client.http` se hai bisogno di interceptor, un `fetch` personalizzato, o override per singola chiamata. Non c'è alcun singleton a livello di modulo da configurare: ogni istanza di `Vibedasher` possiede il proprio client, quindi due client nello stesso processo non si sovrascrivono mai a vicenda l'URL di base o la chiave.

## Python[​](#python "Link diretto a Python")

```
pip install vibedasher
```

```
from vibedasher import Vibedasher, VibedasherApiError

from vibedasher.models import DatasetCreate, DatasetUpdate



client = Vibedasher(api_key="<your-api-key>")



# List datasets — query params are keyword-only

page = client.datasets.list(limit=50)



# Create — the body is the first positional argument

created = client.datasets.create(DatasetCreate(name="Sales", type_="csv"))



# Fetch one by id — path params are positional

one = client.datasets.get(created.dataset.id)



# Update — path param, then body

updated = client.datasets.update(one.dataset.id, DatasetUpdate(name="Sales 2026"))
```

I modelli di richiesta e risposta vivono in `vibedasher.models`. Gli attributi delle risorse sono in snake\_case (`client.datasets`, `client.api_keys`, `client.ai_providers`, `client.embed_tokens`, `client.viz`, …), e lo sono anche i metodi.

### Eseguire SQL[​](#eseguire-sql-1 "Link diretto a Eseguire SQL")

```
result = client.query(sql="SELECT country, SUM(revenue) AS revenue FROM sales GROUP BY 1")

print(result.columns, result.rows)
```

### Caricare un CSV[​](#caricare-un-csv-1 "Link diretto a Caricare un CSV")

```
uploaded = client.datasets.upload(name="Sales", content="country,revenue\nFR,10\nDE,12\n")

print(uploaded["cleanSQLName"])  # the alias to use in client.query SQL
```

### Via di fuga[​](#via-di-fuga-1 "Link diretto a Via di fuga")

I moduli di operazione piatti sotto `vibedasher.api.<tag>` sono comunque forniti per qualsiasi cosa la facade non copra. Costruisci un client grezzo con `create_client` e chiama `.sync()`, `.sync_detailed()`, `.asyncio()`, o `.asyncio_detailed()`:

```
from vibedasher import create_client

from vibedasher.api.datasets import read_datasets



raw = create_client(api_key="<your-api-key>")

datasets = read_datasets.sync(client=raw)
```

## Gestione degli errori[​](#gestione-degli-errori "Link diretto a Gestione degli errori")

Entrambi gli SDK sollevano un'eccezione su una risposta non-2xx, quindi il percorso felice si legge in modo lineare e gli errori vengono catturati dove vuoi gestirli.

**TypeScript:**

```
import { Vibedasher, VibedasherApiError } from '@vibedasher/client';



try {

  const page = await client.datasets.list({ limit: 50 });

  console.log(page.datasets);

} catch (err) {

  if (err instanceof VibedasherApiError) {

    console.error(`Request failed (${err.status})`, err.detail, err.requestId);

  } else {

    throw err;

  }

}
```

**Python:**

```
from vibedasher import VibedasherApiError



try:

    page = client.datasets.list(limit=50)

except VibedasherApiError as err:

    print(f"Request failed ({err.status_code})", err.detail, err.request_id)
```

Codici di stato comuni: **401/403** (chiave API mancante o non valida, oppure una chiave usata su una route solo di sessione), **404** (non trovato, oppure una viz non pubblicata), **422** (errore di validazione della richiesta). La pagina di riferimento di ogni endpoint elenca le esatte risposte che può restituire.

## Paginazione[​](#paginazione "Link diretto a Paginazione")

Gli endpoint di elenco restituiscono una pagina di risultati più un cursore `nextKey`. Raramente devi guidare tu stesso quel cursore: ogni risorsa elencabile porta `iterAll()` (TypeScript) / `iter_all()` (Python), che percorre le pagine e restituisce le righe.

**TypeScript:**

```
for await (const ds of client.datasets.iterAll()) {

  handle(ds);

}
```

**Python:**

```
for ds in client.datasets.iter_all():

    handle(ds)
```

Entrambi espongono anche la forma a livello di pagina (`iterPages()` / `iter_pages()`) quando vuoi la busta invece delle righe. Guidare il cursore a mano funziona ancora — passa `nextKey` indietro come `exclusiveStartKey` (`exclusive_start_key` in Python) e fermati quando torna `null`/`None` — ma gli iteratori rilevano anche un cursore che smette di avanzare e sollevano un'eccezione invece di andare in loop per sempre.

Il nome sul filo — quello mostrato dalla scheda cURL e dalla tabella dei parametri di ogni pagina di riferimento — è sempre `exclusiveStartKey`; l'SDK TypeScript mantiene quella grafia camelCase come chiave dell'opzione, e l'SDK Python espone lo stesso parametro come argomento `exclusive_start_key`. È un unico cursore, scritto secondo il linguaggio — mai entrambi in una stessa richiesta.

## Avvertenza sulla tipizzazione delle risposte[​](#avvertenza-sulla-tipizzazione-delle-risposte "Link diretto a Avvertenza sulla tipizzazione delle risposte")

Alcune route dell'API attualmente restituiscono risposte tipizzate in modo lasco (`object` / `Any`) perché dichiarano una forma di risposta generica sul backend. I corpi delle richieste, i parametri di query/percorso, e un insieme crescente di risposte sono completamente tipizzati. I tipi di risposta vengono irrobustiti modulo per modulo — aggiorna l'SDK per ottenere i miglioramenti.

note

Gli SDK sono generati, mai modificati a mano. Se noti una lacuna, è quasi sempre a monte nella specifica OpenAPI dell'API — contattaci tramite la [pagina di contatto](https://vibedasher.com/contact).