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.

Linguaggio	Pacchetto	Documentato qui
TypeScript	@vibedasher/client	4.1.5
Python	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 — vedi Autenticazione. (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.)

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. 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 — 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

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

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

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

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

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

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

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

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

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

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

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

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.