Get started

Install the SDK, grab an API key, and run your first query — in minutes.

1) Create an account & API key

# macOS / Linux
export COSINIA_API_KEY="sk_live_***"

# Windows (PowerShell)
$Env:COSINIA_API_KEY = "sk_live_***"

2) Install the SDK

Python

pip install cosinia

TypeScript / Node

npm i cosinia
# or
yarn add cosinia
# or
pnpm add cosinia

3) Hello World: create, upsert, query

Below is the same minimal flow in Python and TypeScript — create a collection, upsert a few vectors, then run a cosine-similarity query.

Python

from cosinia import Client
import os

client = Client(api_key=os.getenv("COSINIA_API_KEY"))

# 1) Create or get a collection
col = client.collections.get_or_create(name="demo")

# 2) Upsert a few vectors (id, values, metadata)
col.upsert([
  {"id": "a", "values": [0.11, 0.72, 0.07], "metadata": {"label": "alpha"}},
  {"id": "b", "values": [0.44, 0.25, 0.31], "metadata": {"label": "beta"}},
  {"id": "c", "values": [0.02, 0.90, 0.08], "metadata": {"label": "gamma"}}
])

# 3) Query by vector
res = col.query(vector=[0.10, 0.70, 0.10], top_k=2, include=["metadata","score"])
print(res)

TypeScript

import { Cosinia } from "cosinia";

const client = new Cosinia({ apiKey: process.env.COSINIA_API_KEY! });

// 1) Create or get a collection
const col = await client.collections.getOrCreate({ name: "demo" });

// 2) Upsert vectors
await col.upsert([
  { id: "a", values: [0.11, 0.72, 0.07], metadata: { label: "alpha" } },
  { id: "b", values: [0.44, 0.25, 0.31], metadata: { label: "beta" } },
  { id: "c", values: [0.02, 0.90, 0.08], metadata: { label: "gamma" } }
]);

// 3) Query
const res = await col.query({
  vector: [0.10, 0.70, 0.10],
  topK: 2,
  include: ["metadata", "score"],
});
console.log(res);

4) cURL smoke test

curl -s https://api.cosinia.com/healthz \
  -H "Authorization: Bearer $COSINIA_API_KEY"

Expect 200 OK with a small JSON payload.

5) Auth pattern

Always load COSINIA_API_KEY from the environment (never hard-code it). In browser apps, call your backend; do not expose the key client-side.

Next steps

Try Vector Laboratory^™ to test normalization, clustering, and whitening before ingestion.
Turn on Vector Health^™ for drift monitoring and quality diagnostics over time.
Enable Vector Shield^™ to guard against poisoning and keep retrieval reliable.
Read about Zero Retention and privacy posture in the platform overview.