Get your BlackVec API key, choose a licensed dataset, and make your first /query request to retrieve verifiable domain knowledge for your AI agents.

BlackVec quickstart

BlackVec delivers licensed, curated, continuously updated domain data that’s production‑ready for agents and RAG — no ETL, chunking, or hosting. Use a single API to query datasets like finance news and filings, with optional citations and freshness filters.

1) Create an API key

Request early access or sign in at https://www.blackvec.com/
Select your dataset(s) and create an API key in the dashboard.

Store your key and workspace as environment variables.

macOS / Linux

export BLACKVEC_API_KEY="sk_live_..."
export BLACKVEC_WORKSPACE="your-workspace-id-or-slug"

Windows (PowerShell)

setx BLACKVEC_API_KEY "sk_live_..."
setx BLACKVEC_WORKSPACE "your-workspace-id-or-slug"

2) Make your first query

The /v1/query endpoint returns a concise answer with optional citations. Replace the dataset, query, and filters with values relevant to your use case.

cURL

curl -sS https://api.blackvec.com/v1/query \
  -X POST \
  -H "Authorization: Bearer $BLACKVEC_API_KEY" \
  -H "Content-Type: application/json" \
  -H "X-BV-Workspace: $BLACKVEC_WORKSPACE" \
  -d @- << 'JSON'
{
  "dataset": "finance.news",
  "q": "M&A activity this week",
  "top_k": 3,
  "cite": true,
  "filters": { "region": "US" },
  "freshness": "7d"
}
JSON

Sample response

{
  "answer": "Acme acquired Globex for $4.1B.",
  "citations": ["reuters:2025-10-18", "ft:2025-10-19"],
  "latency_ms": 238,
  "cache_hit": true
}

JavaScript (Node 18+)

const res = await fetch('https://api.blackvec.com/v1/query', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.BLACKVEC_API_KEY}`,
    'Content-Type': 'application/json',
    'X-BV-Workspace': process.env.BLACKVEC_WORKSPACE ?? '',
    // Optional: client tag and tracing for observability
    'X-BV-Client': 'docs-quickstart',
    'X-BV-Trace': '1',
  },
  body: JSON.stringify({
    dataset: 'finance.news',
    q: 'M&A activity this week',
    top_k: 3,
    cite: true,
    filters: { region: 'US' },
    freshness: '7d',
  }),
});

if (!res.ok) {
  throw new Error(`BlackVec error ${res.status}: ${await res.text()}`);
}

const data = await res.json();
console.log(data.answer, data.citations);

Python

import os, requests

resp = requests.post(
    'https://api.blackvec.com/v1/query',
    headers={
        'Authorization': f"Bearer {os.environ.get('BLACKVEC_API_KEY','')}",
        'Content-Type': 'application/json',
        'X-BV-Workspace': os.environ.get('BLACKVEC_WORKSPACE',''),
        'X-BV-Client': 'docs-quickstart',
        'X-BV-Trace': '1',
    },
    json={
        'dataset': 'finance.news',
        'q': 'M&A activity this week',
        'top_k': 3,
        'cite': True,
        'filters': { 'region': 'US' },
        'freshness': '7d',
    },
)

resp.raise_for_status()
print(resp.json())

3) Tune results with parameters

dataset — the licensed dataset to query (example: finance.news).
q — your natural‑language question or keywords.
top_k — how many context items to retrieve for answering.
cite — include verifiable citation identifiers in the response.
filters — narrow by metadata such as region, source, or timeframe.
freshness — limit to recent data (e.g., "24h", "7d").

Headers

Authorization: Bearer <key> — your API key.
X-BV-Workspace: <id-or-slug> — routes traffic to your workspace.
X-BV-Client — optional free‑form tag for analytics/observability.
X-BV-Trace — optional; when enabled, includes retrieval diagnostics.

Next steps

Request access or manage datasets at https://www.blackvec.com/
Add your service’s domain logic (filters, prompt templates) around the /query call.
Cache answers and set freshness to balance latency vs. recency.
Add monitoring. Log X-BV-Client, latencies, and cache hits.

Have questions or want to publish a dataset? Get in touch via the website.

Quickstart