REST API Reference

Interact with Pulsbase using native HTTP requests from any environment.

Authentication & Universal AI Agent Access

All API requests support **Universal Dual Authentication**. You may pass either your developer JWT session token or your secret API key (`pb_live_...` / `sk_live_...`) inside the `Authorization` header. When AI coding agents (such as Cursor IDE, Claude Dev, AutoGPT, LangChain, or Vercel AI SDK) pass a developer API key to Management endpoints (`/v1/databases`), our edge engine verifies the key via SHA-256 and resolves identity automatically.

Authorization: Bearer pb_live_xxxxxxxxxxxxxxxxx

Management API (AI Agent Provisioning)

Base URL: https://api.pulsbase.com/v1

POST /v1/databases

Provisions a new globally distributed SQLite database cluster. If an AI Agent omits the x-workspace-id header, the API automatically assigns the cluster to your default workspace.

Request Body (JSON)

{
  "name": "ai-agent-memory-db",
  "jurisdiction": "global"
}

Response (201 Created)

{
  "database": {
    "id": "01J...db_abc123",
    "name": "ai-agent-memory-db",
    "jurisdiction": "global",
    "status": "ready",
    "created_at": "2026-07-14T15:30:00Z"
  }
}

Query API

Base URL: https://api.query.pulsbase.com/v1

POST /v1/sql

Executes parameterized SQL queries against your database. Automatic vector embeddings are triggered if configured.

Request Body (JSON)

{
  "database_id": "db_123",
  "query": "INSERT INTO users (name, email) VALUES (?, ?)",
  "params": ["Alice", "[email protected]"]
}

Response (200 OK)

{
  "success": true,
  "results": [],
  "meta": {
    "rows_read": 0,
    "rows_written": 1,
    "duration": 12
  }
}
POST /v1/search

Performs a hybrid semantic search across a specific table in your database.

Request Body (JSON)

{
  "database_id": "db_123",
  "table": "documents",
  "query": "beautiful weather",
  "limit": 5,
  "filter": {
    "author": { "$eq": "system" }
  }
}

Response (200 OK)

{
  "results": [
    {
      "id": "doc_456",
      "score": 0.92,
      "content": "A beautiful day",
      "metadata": { "author": "system" }
    }
  ]
}