# SDKs

Vibedasher distribuye SDKs oficiales, completamente tipados, para **TypeScript** y **Python**, generados a partir de la especificación OpenAPI de la API para que se mantengan en sincronía con la plataforma. Son cómo tu propio código alcanza la plataforma mantenida: ejecutar SQL contra tus conjuntos de datos, disparar actualizaciones, gestionar conexiones y derechos de acceso, conectar un panel a datos en vivo, o automatizar desde un script cualquier cosa que hacen las [herramientas MCP](/es/guides/build-with-your-agent.md) desde un agente.

| Lenguaje   | Paquete                                                                  | Documentado aquí |
| ---------- | ------------------------------------------------------------------------ | ---------------- |
| TypeScript | [`@vibedasher/client`](https://www.npmjs.com/package/@vibedasher/client) | 4.1.5            |
| Python     | [`vibedasher`](https://pypi.org/project/vibedasher/)                     | 4.3.19           |

Ambos SDKs se autentican con una **clave de API** en la cabecera `X-Api-Key`. Genera una en la aplicación bajo **Ajustes → Claves de API** en [cloud.vibedasher.com](https://cloud.vibedasher.com) — mira [Autenticación](/es/api/authentication.md). (Los SDKs son la vía de *código*; si tu agente maneja Vibedasher por MCP, inicia sesión con `vibedasher login` en su lugar y no necesita ninguna clave — mira [Construir con tu agente](/es/guides/build-with-your-agent.md).)

Ninguno de los dos clientes necesita que le digas en qué región vive tu cuenta. Sin URL base y sin `region`, ambos resuelven a `https://api.vibedasher.com/api`, que enruta cada petición por la credencial que lleva — mira [Un solo host, enrutado por tu credencial](/es/api/authentication.md#one-host-routed-by-your-credential). Pasar `region` sigue soportado y fija el cliente al nombre de host propio de esa región, `https://api.{region}.vibedasher.com/api`; un `baseUrl` / `base_url` explícito prevalece sobre ambos. (`region` pasó a ser opcional en `@vibedasher/client` 4.1.5 y `vibedasher` 4.3.19.)

¿Buscas un endpoint concreto? Explora la **[API Reference](/es/reference/vibedasher-sdk-api.md)** completa — cada operación agrupada por recurso, con ejemplos de petición en curl / Python / TypeScript generados a partir de las mismas firmas con las que se construyen los SDKs.

## La forma de cada llamada[​](#la-forma-de-cada-llamada "Enlace directo al La forma de cada llamada")

Ambos SDKs exponen el mismo **cliente fluido agrupado por recurso**. Constrúyelo una vez, y luego llama a métodos agrupados por recurso. Las firmas son **planas**: primero los parámetros de ruta (en el orden de la ruta), luego el cuerpo de la petición, y luego un objeto de opciones final opcional que contiene los parámetros de consulta. No hay objetos envoltorio `path` / `query` / `body`.

Los recursos son los mismos 23 en ambos lenguajes, camelCase en TypeScript y snake\_case en 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 respuesta no-2xx **lanza** — `VibedasherApiError` en ambos lenguajes. Los métodos nunca resuelven a una unión de error, así que no compruebas un resultado antes de usarlo.

## TypeScript[​](#typescript "Enlace directo al TypeScript")

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

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



const client = new Vibedasher({

  apiKey: process.env.VIBEDASHER_API_KEY!,

});



// Listar conjuntos de datos — los parámetros de consulta van en el objeto de opciones final

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



// Crear — el cuerpo es posicional

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



// Obtener uno por id — los parámetros de ruta son posicionales

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



// Actualizar — parámetro de ruta, luego cuerpo

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

Cada método está tipado de principio a fin: los tipos de los argumentos y el tipo de respuesta resuelto vienen de la especificación, y las interfaces por recurso (`DatasetsResource`, `DatasetsListOptions`, …) y los tipos de modelo (`DatasetResponse`, `DatasetUpdate`, …) se exportan desde la raíz del paquete si quieres anotar una variable.

### Ejecutar SQL[​](#ejecutar-sql "Enlace directo al Ejecutar SQL")

`client.query` es el método escrito a mano que la superficie generada no tiene: una llamada, resultados columnares tipados de vuelta.

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

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

});

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

`datasetIds` es opcional — omítelo y el servidor resuelve el conjunto de datos a partir de los alias que referencia tu SQL, aplicando exactamente la misma autorización.

### Subir un CSV[​](#subir-un-csv "Enlace directo al Subir un CSV")

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

  name: 'Sales',

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

});

console.log(uploaded.cleanSQLName); // el alias para usar en el SQL de client.query
```

### Escape hatch[​](#escape-hatch "Enlace directo al Escape hatch")

El cliente `fetch` subyacente está en la instancia como `client.http` si necesitas interceptores, un `fetch` personalizado, o anulaciones por llamada. No hay ningún singleton a nivel de módulo que configurar: cada instancia de `Vibedasher` posee su propio cliente, así que dos clientes en un mismo proceso nunca se pisan la URL base ni la clave.

## Python[​](#python "Enlace directo al Python")

```
pip install vibedasher
```

```
from vibedasher import Vibedasher, VibedasherApiError

from vibedasher.models import DatasetCreate, DatasetUpdate



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



# Listar conjuntos de datos — los parámetros de consulta son solo por palabra clave

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



# Crear — el cuerpo es el primer argumento posicional

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



# Obtener uno por id — los parámetros de ruta son posicionales

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



# Actualizar — parámetro de ruta, luego cuerpo

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

Los modelos de petición y respuesta viven en `vibedasher.models`. Los atributos de recurso son snake\_case (`client.datasets`, `client.api_keys`, `client.ai_providers`, `client.embed_tokens`, `client.viz`, …), y también lo son los métodos.

### Ejecutar SQL[​](#ejecutar-sql-1 "Enlace directo al Ejecutar SQL")

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

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

### Subir un CSV[​](#subir-un-csv-1 "Enlace directo al Subir un CSV")

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

print(uploaded["cleanSQLName"])  # el alias para usar en el SQL de client.query
```

### Escape hatch[​](#escape-hatch-1 "Enlace directo al Escape hatch")

Los módulos de operación planos bajo `vibedasher.api.<tag>` se siguen distribuyendo para cualquier cosa que la fachada no cubra. Construye un cliente en bruto con `create_client` y llama a `.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)
```

## Manejo de errores[​](#manejo-de-errores "Enlace directo al Manejo de errores")

Ambos SDKs lanzan en una respuesta no-2xx, así que el camino feliz se lee de corrido y los errores se capturan donde quieras manejarlos.

**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)
```

Códigos de estado comunes: **401/403** (clave de API ausente o inválida, o una clave usada en una ruta solo de sesión), **404** (no encontrado, o una viz que no está publicada), **422** (error de validación de la petición). La página de referencia de cada endpoint lista las respuestas exactas que puede devolver.

## Paginación[​](#paginación "Enlace directo al Paginación")

Los endpoints de listado devuelven una página de resultados más un cursor `nextKey`. Rara vez necesitas manejar ese cursor tú mismo: cada recurso listable lleva `iterAll()` (TypeScript) / `iter_all()` (Python), que recorre las páginas y va entregando filas.

**TypeScript:**

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

  handle(ds);

}
```

**Python:**

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

    handle(ds)
```

Ambos también exponen la forma a nivel de página (`iterPages()` / `iter_pages()`) para cuando quieres el sobre en lugar de las filas. Manejar el cursor a mano sigue funcionando — pásale de vuelta `nextKey` como `exclusiveStartKey` (`exclusive_start_key` en Python) y detente cuando vuelva `null`/`None` — pero los iteradores también detectan un cursor que deja de avanzar y lanzan un error en lugar de dar vueltas para siempre.

El nombre en el cable — el que muestran la pestaña cURL y la tabla de parámetros de cada página de referencia — es siempre `exclusiveStartKey`; el SDK de TypeScript conserva esa grafía camelCase como clave de opción, y el SDK de Python expone el mismo parámetro como el argumento `exclusive_start_key`. Es un único cursor, escrito según el lenguaje — nunca ambos en una misma petición.

## Advertencia sobre el tipado de respuestas[​](#advertencia-sobre-el-tipado-de-respuestas "Enlace directo al Advertencia sobre el tipado de respuestas")

Algunas rutas de la API actualmente devuelven respuestas poco tipadas (`object` / `Any`) porque declaran una forma de respuesta genérica en el backend. Los cuerpos de petición, los parámetros de consulta/ruta, y un conjunto cada vez mayor de respuestas están completamente tipados. Los tipos de respuesta se están reforzando módulo a módulo — actualiza el SDK para recoger las mejoras.

nota

Los SDKs son generados, nunca editados a mano. Si encuentras una laguna, casi siempre está en origen en la especificación OpenAPI de la API — contáctanos a través de la [página de contacto](https://vibedasher.com/contact).