Get Started with MassEngine Cloud

Create an Account & Pick an Existing Cluster

Open the MassEngine Cloud Console (https://massengine.com/console) and stay on the Create New Account tab:

1. Enter your Full Name and Company / Organization.
2. Choose a unique Workspace / Tenant ID (for example, acme-ai-labs). Every API key and database partition you create is cryptographically isolated under this tenant namespace.
3. In the Target Cluster (Pick an Existing Cluster) dropdown, select the cluster where you want your vector database hosted. For example, pick: 2-Node High-End NVMe Cluster (cluster-nvme-2n).
4. Enter your Work Email and Password, then click Create Workspace Account →.

Available Fleet Clusters

Activate Your Plan & Issue Your Tenant API Key (mk_...)

After creating your account, you land on Step 2: Target Cluster, Capacity Plan & Square Payment Setup in the Console:

1. Confirm your Target Cluster for Database Provisioning dropdown is set to your desired cluster (e.g., cluster-nvme-2n).
2. Select a capacity plan card (Developer Sandbox, Starter Tier, Growth Pro, or Scale Pod).
3. Click 2. Verify Payment & Provision DB ✓ (or click 1. Setup Payment via Square ↗ to test Square Hosted Checkout first, then click button 2).

Create & Configure a Vector Database Partition

Every activated workspace starts with a default database partition (1024-d float32, cosine/dot similarity). You can create additional isolated databases (for example, wiki-demo, docs-prod, or customer-support) under the same tenant quota:

1. In Step 3: Configure Vector Databases, enter a Database Name (e.g., wiki-demo).
2. Pick a Shard Routing Mode:
   • micro (Single-Shard Locality) — Pins the partition to a single shard replica pair so queries and writes touch only 1 shard (ideal for partitions under 100,000 vectors).
   • supercell (8-Shard Parallel) — Distributes vectors across all 8 shards by coarse centroid affinity with bounded-load overflow protection (ideal for multi-million-vector partitions).
3. Click + Create DB. Your new database is immediately selected as the Active Database for Playground & Code Snippets.

Upload Data Using the Open-Source Wikipedia Dataset

So you always have a realistic, reproducible working example, we host an open-source sample dataset on massengine.com containing 25 English Wikipedia articles (licensed under CC BY-SA 4.0) across 5 technical domains (distributed-systems, ai-ml, storage, space, and quantum), pre-embedded with real 1024-dimensional BAAI/bge-m3 unit vectors.

Option A: 1-Click Upload in the Cloud Console (Fastest)

In Step 4A of https://massengine.com/console, simply click the blue button: Load Open-Source Wikipedia Dataset (25 Articles). It downloads /samples/wikipedia-scitech-1024d.json and ingests all 25 articles into your currently selected database partition in ~15–40 ms.

Option B: Upload via curl (JSON Batch Ingest — POST /v1/ingest)

Replace mk_YOUR_API_KEY with the API key shown in your Console's Workspace API Credentials card, and set DB_NAME to your database name (e.g., default or wiki-demo):

export MASSENGINE_API_KEY="mk_YOUR_API_KEY"
export DB_NAME="default"

curl -sS https://massengine.com/samples/wikipedia-scitech-1024d.json \
  | jq --arg db "$DB_NAME" '.partition = $db' \
  | curl -sS -X POST https://massengine.com/v1/ingest \
      -H "Authorization: Bearer $MASSENGINE_API_KEY" \
      -H "Content-Type: application/json" \
      -d @- | jq .

Option C: Bulk Streaming Upload via NDJSON (POST /v1/import)

For larger datasets (thousands to millions of vectors), stream newline-delimited JSON (application/x-ndjson) directly to POST /v1/import?partition=default:

curl -sS https://massengine.com/samples/wikipedia-scitech-1024d.ndjson \
  | curl -sS -X POST "https://massengine.com/v1/import?partition=${DB_NAME:-default}" \
      -H "Authorization: Bearer $MASSENGINE_API_KEY" \
      -H "Content-Type: application/x-ndjson" \
      --data-binary @- | jq .

Option D: Upload via Python

import os
import requests

API_KEY = os.environ.get("MASSENGINE_API_KEY", "mk_YOUR_API_KEY")
DB_NAME = os.environ.get("DB_NAME", "default")
BASE_URL = "https://massengine.com"

# 1. Fetch the 25-article Wikipedia 1024-d sample dataset
dataset = requests.get(f"{BASE_URL}/samples/wikipedia-scitech-1024d.json", timeout=15).json()

# 2. Ingest into your MassEngine database partition
resp = requests.post(
    f"{BASE_URL}/v1/ingest",
    headers={"Authorization": f"Bearer {API_KEY}"},
    json={"partition": DB_NAME, "docs": dataset["docs"]},
    timeout=15,
)
resp.raise_for_status()
print("Routed Cluster:", resp.headers.get("X-MassEngine-Routed-Cluster"))
print("Ingest Response:", resp.json())

Query & Pre-Filter Your Vectors (POST /v1/search)

Once the 25 Wikipedia articles are loaded, you can run semantic kNN searches combined with structured metadata pre-filters.

Option A: Interactive Search in the Cloud Console

In Step 4B of the Cloud Console:

1. Pick one of the 5 real 1024-d BGE-M3 query vectors in Semantic Query / Target Vector (e.g., Distributed Consensus & Replication (Raft / Paxos) or NVMe Flash, Write-Ahead Log & LSM Trees).
2. Optionally choose a Metadata Pre-Filter (such as {"topic": "distributed-systems"}, {"tier": "hot"}, or {"year": {"$gte": 2025}}).
3. Click Run Search to inspect the ranked hits, similarity scores, metadata payloads, and the X-MassEngine-Routed-Cluster header.

Option B: Query via curl

We provide 5 pre-computed 1024-d BAAI/bge-m3 query vectors in /samples/wikipedia-scitech-queries.json:

• .queries[0] — "Distributed Consensus & Replication" (matches Raft, Paxos, Consistent hashing)
• .queries[1] — "AI Transformers & Vector RAG" (matches Vector database, RAG, Transformer)
• .queries[2] — "NVMe Flash & Database Storage Engines" (matches NVM Express, Write-ahead logging, LSM-tree)
• .queries[3] — "Deep Space Telescopes & Propulsion" (matches James Webb Space Telescope, Exoplanets, Ion thruster)
• .queries[4] — "Quantum Computing & Lattice Cryptography" (matches Quantum error correction, Post-quantum cryptography, Shor's algorithm)

# Query #0 ("Distributed Consensus & Replication") filtered to tier="hot" and year >= 2024
curl -sS https://massengine.com/samples/wikipedia-scitech-queries.json \
  | jq --arg db "${DB_NAME:-default}" '{
      partition: $db,
      vector: .queries[0].vector,
      k: 5,
      nprobe: 16,
      rerank_pool: 64,
      metadata_filter: {
        tier: "hot",
        year: { "$gte": 2024 }
      }
    }' \
  | curl -sS -i -X POST https://massengine.com/v1/search \
      -H "Authorization: Bearer $MASSENGINE_API_KEY" \
      -H "Content-Type: application/json" \
      -d @-

Option C: Query via Python

import os
import requests

API_KEY = os.environ.get("MASSENGINE_API_KEY", "mk_YOUR_API_KEY")
DB_NAME = os.environ.get("DB_NAME", "default")
BASE_URL = "https://massengine.com"

queries = requests.get(f"{BASE_URL}/samples/wikipedia-scitech-queries.json", timeout=15).json()["queries"]

for q in queries:
    res = requests.post(
        f"{BASE_URL}/v1/search",
        headers={"Authorization": f"Bearer {API_KEY}"},
        json={
            "partition": DB_NAME,
            "vector": q["vector"],
            "k": 3,
            "metadata_filter": {"tier": "hot"},
        },
        timeout=15,
    )
    res.raise_for_status()
    body = res.json()
    cluster = res.headers.get("X-MassEngine-Routed-Cluster", "unknown")
    print(f"\n=== Query: {q['label']} (Cluster: {cluster}, took {body.get('took_ms', 0):.2f} ms) ===")
    for rank, hit in enumerate(body.get("hits", []), 1):
        meta = hit.get("metadata", {})
        print(f"  #{rank} {hit['id']} (score={hit['score']:.4f}) -> {meta.get('title')} [{meta.get('topic')}]")

Supported Metadata Filter Operators

Zero-Reindex Metadata Patching & Live Cross-Cluster Migration

1. Update Metadata In-Place Without Re-Uploading the Vector (PATCH /v1/docs/{id})

You can mutate any document's JSON metadata, date, or category in sub-millisecond time without re-sending or re-indexing its 1024-d vector:

curl -sS -X PATCH https://massengine.com/v1/docs/wiki-raft-consensus \
  -H "Authorization: Bearer $MASSENGINE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "partition": "'"${DB_NAME:-default}"'",
    "metadata": {
      "reviewed": true,
      "priority": "p0"
    }
  }' | jq .

2. Live Cross-Cluster Migration (e.g., cluster-nvme-2n → hetzner-us-west-1)

MassEngine decouples your tenant API key (mk_...) from physical cluster IPs using our Cloudflare Edge Router. When an administrator migrates your workspace from one cluster to another (for example, from cluster-nvme-2n to hetzner-us-west-1 in the Fleet Operations Center):

1. Your tenant quota and existing mk_... API key are pre-staged on the destination cluster.
2. Every partition in your workspace is streamed via lossless NDJSON export/import (GET /v1/tenants/{tenant}/export → POST /v1/tenants/{tenant}/import).
3. The edge routing table atomically updates your workspace's cluster_id to the destination cluster.
4. Your existing application code and mk_... API key continue working without interruption — and the response header X-MassEngine-Routed-Cluster immediately reflects the new cluster (e.g., hetzner-us-west-1).

Data-Plane REST API Summary (https://massengine.com/v1)

All data-plane endpoints authenticate with your tenant key via Authorization: Bearer mk_...: