turbopuffer-api-setup

Turbopuffer API Setup for Cursor AI Agents

Version: 1.0
Date: January 30, 2026
Owner: AI Team

---

1. Purpose

This guide enables Cursor AI agents to interact with Turbopuffer for vector search and full-text search operations. Turbopuffer stores our meeting transcripts and other searchable content.

---

2. Credentials Location

1Password:

• Vault: Brainforge AI Team
• Item: Turbopuffer API Key (or search for “Turbopuffer”)

Environment Variable:

TURBOPUFFER_API_KEY=your_api_key_here
TURBOPUFFER_NAMESPACE=zoom_recordings_fts_only

---

3. API Authentication

Turbopuffer uses Bearer token authentication.

cURL Authentication:

curl -X POST "https://api.turbopuffer.com/v1/namespaces/YOUR_NAMESPACE/query" \
  -H "Authorization: Bearer ${TURBOPUFFER_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{"query": "search terms"}'

---

4. Common Operations

4.1 Full-Text Search (Zoom Recordings)

curl -X POST "https://api.turbopuffer.com/v1/namespaces/zoom_recordings_fts_only/query" \
  -H "Authorization: Bearer ${TURBOPUFFER_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "top_k": 10,
    "rank_by": ["BM25", "content"],
    "filters": {},
    "include_attributes": ["name", "summary", "meeting_date", "participants"]
  }'

4.2 Search with Filters

curl -X POST "https://api.turbopuffer.com/v1/namespaces/zoom_recordings_fts_only/query" \
  -H "Authorization: Bearer ${TURBOPUFFER_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "top_k": 10,
    "rank_by": ["BM25", "content"],
    "filters": {
      "participants": {"$contains": "John Doe"}
    }
  }'

4.3 Upsert Documents

curl -X POST "https://api.turbopuffer.com/v1/namespaces/zoom_recordings_fts_only/upsert" \
  -H "Authorization: Bearer ${TURBOPUFFER_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "upsert_rows": [{
      "id": "unique-id",
      "content": "document content...",
      "name": "Document Name",
      "created_at": "2026-01-30T12:00:00Z"
    }],
    "schema": {
      "content": {"type": "string", "full_text_search": {"language": "english"}},
      "name": {"type": "string"},
      "created_at": {"type": "datetime"}
    }
  }'

---

5. Our Namespaces

Namespace	Purpose	Schema
zoom_recordings_fts_only	Zoom meeting transcripts	content, name, summary, participants, meeting_date

---

6. Zoom Recordings Schema

{
  "content": {
    "type": "string",
    "full_text_search": {
      "language": "english",
      "stemming": true,
      "remove_stopwords": true,
      "case_sensitive": false
    }
  },
  "supabase_id": {"type": "string", "full_text_search": {...}},
  "name": {"type": "string", "full_text_search": {...}},
  "created_at": {"type": "datetime"},
  "meeting_date": {"type": "datetime"},
  "participants": {"type": "[]string", "filterable": true, "full_text_search": {...}},
  "summary": {"type": "string", "full_text_search": {...}}
}

---

7. TypeScript SDK Usage

In brainforge-platform, we use the official TypeScript SDK:

import { Turbopuffer } from "@turbopuffer/turbopuffer";
 
const tpuf = new Turbopuffer({
  apiKey: process.env.TURBOPUFFER_API_KEY,
  region: "aws-us-east-2",
});
 
const ns = tpuf.namespace("zoom_recordings_fts_only");
 
// Query
const results = await ns.query({
  top_k: 10,
  rank_by: ["BM25", "content"],
});
 
// Upsert
await ns.write({
  upsert_rows: [{ id: "1", content: "..." }],
  schema: {...},
});

---

8. UI Access

• Dashboard: https://turbopuffer.com/
• Docs: https://turbopuffer.com/docs

---

9. Troubleshooting

“Namespace not found” error:

• Verify namespace name is exact
• Check API key has access to the namespace

“Invalid schema” error:

• Ensure schema matches existing namespace schema
• Types must be consistent with prior writes

---

10. Version History

• v1.0 (January 30, 2026) — Initial documentation