Quickstart

This quickstart gets you from an API key to a searchable VectorAmp dataset. By the end, you will have:

• created a dataset backed by SABLE,
• added searchable text,
• run semantic search,
• asked a cited question,
• and seen where to plug in real ingestion sources.

Best first run

Use a small real document set as soon as possible: one policy, one product doc, one contract excerpt, or one support article. VectorAmp’s strengths — citations, filters, hybrid search, and governed scoping — show up much better on real knowledge than on toy strings.

Prerequisites

You need:

• a VectorAmp account,
• an API key from Application → API Keys, or directly from Settings → API Keys,
• one integration surface:
  • VectorAmp CLI for terminal workflows,
  • Python SDK for notebooks and backend jobs,
  • JavaScript SDK for Node.js services,
  • or the REST API from any language.

info

The examples below use placeholder IDs such as ds_123. Use the dataset ID returned by your own account.

1. Configure credentials

CLI

export VECTORAMP_API_KEY=vsk_<64hex>
export VECTORAMP_BASE_URL=https://api.vectoramp.com

Or store credentials locally:

vectoramp config set --api-key vsk_<64hex>
vectoramp config set --base-url https://api.vectoramp.com

Python

export VECTORAMP_API_KEY=vsk_<64hex>

from vectoramp import VectorAmp

client = VectorAmp()

Node.js

export VECTORAMP_API_KEY=vsk_<64hex>

import { VectorAmp } from '@vectoramp/vectoramp';

const client = new VectorAmp({ apiKey: process.env.VECTORAMP_API_KEY });

2. Create a dataset

A dataset is the retrieval boundary your application queries. It owns vectors, metadata, index configuration, and search behavior. For most first runs, only the name is required.

CLI

vectoramp datasets create product-docs
vectoramp config use ds_123

Python

dataset = client.datasets.create("product-docs")
print(f"Created dataset: {dataset.id}")

Node.js

const dataset = await client.datasets.create({ name: 'product-docs' });
console.log(`Created dataset: ${dataset.id}`);

tip

VectorAmp defaults to the managed VectorAmp-Embedding-4B embedding model, infers the embedding dimension, uses cosine similarity, and indexes with SABLE. Use OpenAI or hybrid search when your workload needs those tradeoffs.

3. Add searchable content

For the smallest possible test, add text directly. For production, prefer ingestion sources and jobs so parsing, chunking, embedding, retries, and audit trails are handled consistently.

CLI

vectoramp --dataset ds_123 datasets add-texts \
  "SABLE is VectorAmp's filter-aware vector index for governed retrieval."

vectoramp --dataset ds_123 datasets add-texts \
  "VectorAmp returns cited answers grounded in retrieved source context."

Python

dataset.add_texts([
    {
        "text": "SABLE is VectorAmp's filter-aware vector index for governed retrieval.",
        "metadata": {"source": "quickstart", "doc_type": "overview"},
    },
    {
        "text": "VectorAmp returns cited answers grounded in retrieved source context.",
        "metadata": {"source": "quickstart", "doc_type": "overview"},
    },
])

Node.js

await dataset.addTexts([
  {
    text: "SABLE is VectorAmp's filter-aware vector index for governed retrieval.",
    metadata: { source: 'quickstart', doc_type: 'overview' },
  },
  {
    text: 'VectorAmp returns cited answers grounded in retrieved source context.',
    metadata: { source: 'quickstart', doc_type: 'overview' },
  },
]);

4. Search the dataset

Search is the lowest-level retrieval primitive. Use it when your application wants ranked chunks, documents, or metadata and will handle the final UI or model prompt itself.

CLI

vectoramp --dataset ds_123 datasets search \
  "What makes VectorAmp useful for governed retrieval?" \
  --top-k 5

Python

results = dataset.search(
    "What makes VectorAmp useful for governed retrieval?",
    top_k=5,
)

for result in results["results"]:
    print(result["score"], result.get("metadata"), result["text"][:120])

Node.js

const results = await dataset.search({
  queryText: 'What makes VectorAmp useful for governed retrieval?',
  topK: 5,
});

console.log(results.results);

5. Ask a cited question

Use ask when you want VectorAmp to retrieve evidence and produce an answer grounded in that evidence.

CLI

vectoramp --dataset ds_123 datasets ask \
  "Why is SABLE important?" \
  --stream

Python

answer = dataset.ask("Why is SABLE important?")
print(answer["answer"])
print(answer.get("citations"))

Node.js

const answer = await dataset.ask('Why is SABLE important?');
console.log(answer.answer);
console.log(answer.citations);

6. Add filters before you ship

Real retrieval almost always needs scope. Add metadata when you ingest content so searches can enforce boundaries such as tenant, customer, source, role, document type, region, version, or timestamp.

Example filter intent:

{
  "tenant_id": "org_123",
  "doc_type": "policy",
  "visibility": "internal",
  "region": "us"
}

Use filters when you are building:

• multi-tenant SaaS search,
• role-scoped internal knowledge bases,
• support tools scoped to one customer,
• compliance assistants restricted to approved policy sources,
• agent tools that must not retrieve outside their allowed context.

7. Move from sample text to ingestion

After the first successful search, switch to an ingestion path:

• Ingest cloud documents with the CLI
• Search company knowledge with citations
• Build a REST API cited search backend
• Add tenant-scoped semantic search to a SaaS app

Validate your first dataset

Before you call the quickstart “done,” check:

• Search returns the source text you expect for obvious questions.
• Cited answers include evidence, not just fluent prose.
• Metadata appears on results and can be used for filtering.
• A query outside the content’s scope returns no result or a low-confidence answer.
• The dataset name, API key, and environment match the app you are testing.

Next steps

• Introduction — understand VectorAmp’s retrieval model.
• Production readiness checklist — prepare a retrieval workflow for users.
• Datasets — manage dataset configuration and lifecycle.
• Pipelines — automate ingestion.
• API Reference — integrate from any backend.