Getting started with Vectros (preview)

The secure, AI-native backend for your app or your agents — in a few API calls.

Vectros is in invite-only preview

Vectros is the secure data, document, search, and AI layer you build on — a governed home for structured records and documents, with hybrid (keyword + semantic) search and retrieval-augmented inference, and sensitive-field handling built in for regulated and healthcare workloads.

Today it is an invite-only 0.x preview. The surface is real and the code below compiles against the published SDK, but the API is pre-1.0 and may still change between releases, access is gated, and you should use synthetic data only while in preview. There is no self-serve free tier yet.

Request early access — tell us what you're building and we'll get you an invite.

Two ways in

  1. Build on the SDK — install @vectros-ai/sdk, construct a client with a token, and call records / schemas / search / documents / inference directly from your app.
  2. No-code via blueprints + MCP — pick a bundled blueprint, run one vectros bootstrap command to provision schemas and a narrow scoped key, then drive it entirely from an MCP-connected agent (Claude Desktop, Cursor, …) or the app.vectros.ai reference app — zero app code.

Step 0 — Request early access & get your key

  1. Request access at the link above and wait for your invite.
  2. Once invited, sign in to the developer portal for your tenant.
  3. In the portal, open API Keys and create an API key (or a scoped key) for the data plane. Keys are bearer credentials — keep them out of source control.

Environments. The client's environment is the API base URL. Use your staging base URL while building in preview; switch to the production base URL only when your invite covers prod. The two base URLs are https://api.staging.vectros.ai (staging) and https://api.vectros.ai (production).

Note on signing in: the CLI / no-code path authenticates you to your tenant with vectros login (a browser sign-in). For a non-interactive shell, pass a bearer token you already hold with --token, or set VECTROS_BOOTSTRAP_TOKEN. The first sign-in is a human step in a browser; once you are signed in, --yes lets bootstrap run without prompts.

Build on the SDK

Install + construct the client

npm install @vectros-ai/sdk
import { VectrosClient } from '@vectros-ai/sdk';

// `token` may be a string or a `() => Promise<string>` supplier (the reference
// app uses the supplier form so it can refresh per (tenant, context)).
const client = new VectrosClient({
  token: process.env.VECTROS_TOKEN!,
  environment: 'https://api.staging.vectros.ai', // staging; production is https://api.vectros.ai
});

The reference app (ui/app-vectros-ai/src/api/vectrosApi.ts) constructs the client exactly this way, passing a token: () => Promise<string> supplier so the bearer is resolved (and refreshed) per (tenant, context).

Your first calls

The calls below are the ones the smoke tests in smoke-tests/tests/ exercise: records.spec.ts (schemas, records, search, paging), identity.spec.ts (auth.ping), and composite-lookup.spec.ts (lookupRecordsByBody).

1. Ping — confirm auth works.

await client.auth.ping();

2. Create a schema. A schema defines a record type, its fields, and how it's indexed. Mark PHI/PII fields sensitive: true — those are redacted from audit history at write time, excluded from the search index, and masked on read unless the token carries a reveal scope.

const schema = await client.schemas.createSchema({
  body: {
    typeName: 'patient_note',
    displayName: 'Patient Note',
    indexMode: 'HYBRID', // TEXT | SEMANTIC | HYBRID
    allowedSurfaces: ['record'],
    fields: [
      { fieldId: 'name', fieldType: 'string', required: true, searchable: true },
      { fieldId: 'notes', fieldType: 'string', searchable: true },
      { fieldId: 'department', fieldType: 'string', filterable: true },
      { fieldId: 'mrn', fieldType: 'string', sensitive: true }, // PHI — redacted/excluded/masked
    ],
    lookupFields: [{ fieldName: 'mrn', unique: true }],
    capabilities: { auditHistory: true },
  },
});
const schemaId = schema.id!;

3. Create a record. Use SYNTHETIC data only in preview.

const record = await client.records.createRecord({
  body: {
    typeName: 'patient_note',
    schemaId,
    payload: {
      name: 'Jane Doe',
      notes: 'presents with hypertension and complains of chest pain',
      department: 'cardiology',
      mrn: '000-00-0000', // synthetic
    },
  },
});
// Newly created records index asynchronously: indexStatus === 'PENDING_INDEX'.

Records index asynchronously, so a search right after create can miss the record until indexing finishes. Poll getRecord until it reads INDEXED first:

async function waitUntilIndexed(id: string): Promise<void> {
  for (let i = 0; i < 20; i++) {
    const r = await client.records.getRecord({ id });
    if (r.indexStatus === 'INDEXED') return;
    await new Promise((res) => setTimeout(res, 500));
  }
}
await waitUntilIndexed(record.id!);

4. Search it. One unified call over records + documents; mode is TEXT, SEMANTIC, or HYBRID.

const results = await client.search.content({
  query: 'chest pain',
  mode: 'HYBRID',
  limit: 20,
  // narrow with filters on filterable fields, e.g. { department: 'cardiology' }
});
for (const hit of results.results ?? []) {
  console.log(hit.documentId, hit.semanticScore, hit.textScore);
}

5. Look up by an exact field. The lookup returns the standard list envelope. mrn is a sensitive field, so its value must travel in a request body rather than the URL query string: use lookupRecordsByBody (POST /v1/records/lookup). For a non-sensitive field, the query-string form lookupRecords works too.

const page = await client.records.lookupRecordsByBody({
  type: 'patient_note',
  field: 'mrn',
  value: '000-00-0000',
});
const found = page.data ?? []; // { data, nextCursor } — the list envelope

The list envelope. Every list / lookup / version endpoint returns { data, nextCursor }. When nextCursor is non-null, feed it back as startFrom and drain in a loop:

const ids: (string | undefined)[] = [];
let cursor: string | null | undefined;
do {
  const p = await client.schemas.listSchemas(
    cursor ? { startFrom: cursor, limit: 100 } : { limit: 100 });
  ids.push(...(p.data ?? []).map((s) => s.id));
  cursor = p.nextCursor;
} while (cursor);

(search.content is not enveloped — its hits are on results.results.)

No-code via blueprints + MCP

A blueprint is a reviewed, bundled package that provisions a complete, governed data model — schemas, a least-privilege access profile, a service principal, and seed data — in one command. Four ship in the preview:

  • agentic-sdlc — a whole-SDLC system of record for an AI development team: decisions, designs, references, runbooks, and post-mortems as documents, plus controls, conventions, gotchas, and a glossary as records — cross-linked and recalled by meaning; and a private memory tier each agent keeps for itself (a principal holding the member role sees only its own).
  • task-management — structured task tracking, shareable across sessions, agents, and users.
  • second-brain — a personal knowledge base: capture notes, ideas, and links, then ask them anything by meaning.
  • clinical-intake — a behavioral-health intake with PHI fields, demonstrating redact-at-write, audit history, and search exclusion. Synthetic data only.

Install the CLI (@vectros-ai/cli, exposes the vectros command):

# bash (macOS / Linux / Git Bash)
npm install -g @vectros-ai/cli      # then: vectros bootstrap …
# …or run without installing: npx @vectros-ai/cli bootstrap …
# PowerShell (Windows) — quote the scoped package so the leading @ isn't parsed
npm install -g "@vectros-ai/cli"    # then: vectros bootstrap …
# …or run without installing: npx "@vectros-ai/cli" bootstrap …

Sign in, then bootstrap. The CLI authenticates to your tenant with vectros login, a browser sign-in. In a non-interactive shell, pass a bearer token you already hold with --token <t>, or set VECTROS_BOOTSTRAP_TOKEN (bash: export VECTROS_BOOTSTRAP_TOKEN=<t>; PowerShell: $env:VECTROS_BOOTSTRAP_TOKEN = "<t>"):

# bash
npx @vectros-ai/cli bootstrap --blueprint second-brain
# PowerShell
npx "@vectros-ai/cli" bootstrap --blueprint second-brain

(production is the default environment — add --env staging only to target staging.)

bootstrap is idempotent: it provisions the schemas → a dedicated app context → a service principal → a gated, least-privilege access profile → a narrow ssk_* scoped key, then optionally seeds. The scoped key carries data-plane scopes only (for example records, schemas, search, documents, folders, inference); the blueprint's scope gate rejects control-plane scopes such as keys:c.

Then drive it — zero app code — two ways:

  • Via an MCP-connected agent. The ssk_* is stored in your machine's credential store and a non-secret alias for it is merged into the MCP server config, exposing data-plane tools (records, documents, folders, schemas, search, RAG) to your agent. Say "capture this thought" or "what did I note about onboarding?" and it reads and writes Vectros directly.
  • Via app.vectros.ai. The reference data-plane app shows your records, runs search, drives AI/RAG inference, and includes an audit History view so you can watch versioning (and redaction of sensitive fields) on real records.

Where to go next

Per-blueprint walkthroughs:

Compliance posture. Every write to an audited model emits a version row carrying a SHA-256 hash link to the prior state (a hash chain, not an immutable store; the hashes are not returned by the API and Vectros does not ship a verifier), removed only by your retention policy, an erasure request, or tearing down the context or tenant; heavy content is externalized to a retention-locked object store; sensitive fields are redacted at write (destroyed before the audit snapshot, not reversibly masked) and excluded from the search index; and isolation is enforced by a mandatory, auth-derived contextId on every row. The mechanisms and their limits are described in the compliance guide. A Business Associate Agreement can be signed in the developer portal on the Pro plan and above.

Notes

  • Invite-gated. The preview is invite-only; the CLI / no-code path additionally needs you to sign in with vectros login (or supply a token with --token / VECTROS_BOOTSTRAP_TOKEN).
  • Synthetic data only. Do not enter real PHI/PII into a preview tenant — every example here uses synthetic data.
  • Staging vs prod. Build against your staging base URL; move to production only when your invite covers it. The environment value is the only thing that changes.
  • Pre-1.0. This is a 0.x preview; surfaces may change between releases. Compliance retention is configurable in the developer portal (Settings). Some capabilities (storage outside the US, BYOK) are not part of the preview — ask us what's in scope for your use case.