SDKs

A Vibedasher entrega SDKs oficiais e totalmente tipados para TypeScript e Python, gerados a partir da especificação OpenAPI da API para que permaneçam sincronizados com a plataforma. É assim que seu próprio código alcança a plataforma mantida: execute SQL contra seus conjuntos de dados, dispare atualizações, gerencie conexões e direitos de acesso, conecte um painel a dados ao vivo, ou automatize a partir de um script qualquer coisa que as ferramentas MCP fazem a partir de um agente.

Linguagem	Pacote	Documentado aqui
TypeScript	@vibedasher/client	4.1.5
Python	vibedasher	4.3.19

Ambos os SDKs se autenticam com uma chave de API no cabeçalho X-Api-Key. Gere uma no app em Configurações → Chaves de API em cloud.vibedasher.com — veja Autenticação. (Os SDKs são o caminho de código; se seu agente está conduzindo a Vibedasher via MCP, ele faz login com vibedasher login em vez disso e não precisa de chave nenhuma — veja Construa com seu agente.)

Nenhum dos dois clientes precisa que você diga em qual região sua conta vive. Sem URL base e sem region, ambos resolvem para https://api.vibedasher.com/api, que roteia cada requisição pela credencial que ela carrega — veja Um único host, roteado pela sua credencial. Passar region continua suportado e fixa o cliente no hostname próprio daquela região, https://api.{region}.vibedasher.com/api; um baseUrl / base_url explícito prevalece sobre os dois. (region passou a ser opcional em @vibedasher/client 4.1.5 e vibedasher 4.3.19.)

Procurando um endpoint específico? Navegue pela Referência da API completa — cada operação agrupada por recurso, com exemplos de requisição em curl / Python / TypeScript gerados a partir das mesmas assinaturas com as quais os SDKs são construídos.

O formato de cada chamada

Ambos os SDKs expõem o mesmo cliente fluente agrupado por recurso. Construa-o uma vez, depois chame métodos agrupados por recurso. As assinaturas são simples: primeiro os parâmetros de caminho (na ordem do caminho), depois o corpo da requisição, depois um objeto de opções opcional no final contendo os parâmetros de consulta. Não há objetos wrapper path / query / body.

Os recursos são os mesmos 23 em ambas as linguagens, camelCase em TypeScript e snake_case em Python:

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

Uma resposta não-2xx lança uma exceção — VibedasherApiError em ambas as linguagens. Métodos nunca resolvem para uma união de erro, então você não verifica um resultado antes de usá-lo.

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' });

Todo método é tipado de ponta a ponta: os tipos de argumento e o tipo de resposta resolvido vêm da especificação, e as interfaces por recurso (DatasetsResource, DatasetsListOptions, …) e os tipos de modelo (DatasetResponse, DatasetUpdate, …) são exportados a partir da raiz do pacote, caso você queira anotar uma variável.

Executando SQL

client.query é o método escrito à mão que a superfície gerada não tem: uma chamada de entrada, resultados colunares tipados de saída.

const result = await client.query({
  sql: 'SELECT country, SUM(revenue) AS revenue FROM sales GROUP BY 1',
});
console.log(result.columns, result.rows);

datasetIds é opcional — omita-o e o servidor resolve o conjunto de conjuntos de dados a partir dos aliases que seu SQL referencia, aplicando exatamente a mesma autorização.

Enviando um 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

Válvula de escape

O cliente fetch subjacente está na instância como client.http, caso você precise de interceptadores, um fetch personalizado, ou sobreposições por chamada. Não há um singleton em nível de módulo para configurar: cada instância de Vibedasher é dona do seu próprio cliente, então dois clientes em um mesmo processo nunca sobrescrevem a URL base ou a chave um do outro.

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"))

Modelos de requisição e resposta vivem em vibedasher.models. Os atributos de recurso são snake_case (client.datasets, client.api_keys, client.ai_providers, client.embed_tokens, client.viz, …), e os métodos também são.

Executando SQL

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

Enviando um 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

Válvula de escape

Os módulos de operação simples sob vibedasher.api.<tag> ainda são entregues para qualquer coisa que a fachada não cobre. Construa um cliente bruto com create_client e chame .sync(), .sync_detailed(), .asyncio(), ou .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)

Tratamento de erros

Ambos os SDKs lançam uma exceção em uma resposta não-2xx, então o caminho feliz é lido direto e os erros são capturados onde você quer tratá-los.

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 status comuns: 401/403 (chave de API ausente ou inválida, ou uma chave usada em uma rota somente por sessão), 404 (não encontrado, ou uma viz que não está publicada), 422 (erro de validação de requisição). A página de referência de cada endpoint lista as respostas exatas que ele pode retornar.

Paginação

Endpoints de listagem retornam uma página de resultados mais um cursor nextKey. Você raramente precisa conduzir esse cursor você mesmo: todo recurso listável carrega iterAll() (TypeScript) / iter_all() (Python), que percorre as páginas e produz as linhas.

TypeScript:

for await (const ds of client.datasets.iterAll()) {
  handle(ds);
}

Python:

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

Ambos também expõem a forma em nível de página (iterPages() / iter_pages()) quando você quer o envelope em vez das linhas. Conduzir o cursor manualmente ainda funciona — passe nextKey de volta como exclusiveStartKey (exclusive_start_key em Python) e pare quando ele voltar null/None — mas os iteradores também detectam um cursor que para de avançar e lançam uma exceção em vez de entrar em loop para sempre.

O nome no fio — o que a aba cURL e a tabela de parâmetros de cada página de referência mostram — é sempre exclusiveStartKey; o SDK TypeScript mantém essa grafia camelCase como chave da opção, e o SDK Python expõe o mesmo parâmetro como o argumento nomeado exclusive_start_key. É um único cursor, escrito conforme a linguagem — nunca os dois em uma mesma requisição.

Ressalva sobre tipagem de resposta

Algumas rotas da API atualmente retornam respostas fracamente tipadas (object / Any) porque declaram um formato de resposta genérico no backend. Corpos de requisição, parâmetros de consulta/caminho, e um conjunto crescente de respostas são totalmente tipados. Os tipos de resposta estão sendo reforçados módulo por módulo — atualize o SDK para obter as melhorias.

observação

Os SDKs são gerados, nunca editados à mão. Se você notar uma lacuna, ela quase sempre está a montante, na especificação OpenAPI da API — entre em contato pela página de contato.