Database API

REST endpoints for inserting, querying, updating, and deleting records in JSONB collections.

Base URL & auth

Base URL: https://api.koolbase.com/v1/sdk

Required headers:
  x-api-key: pk_live_your_public_key_here

For authenticated/owner collections also include:
  Authorization: Bearer <session_token>

Endpoints

POST/sdk/db/insertInsert a record into a collection

POST/sdk/db/queryQuery records with filters

GET/sdk/db/records/{id}Get a single record by ID

PATCH/sdk/db/records/{id}Partially update a record

DELETE/sdk/db/records/{id}Delete a record

POST /sdk/db/insert

// Request
{
  "collection": "posts",
  "data": {
    "title": "Hello Koolbase",
    "body": "My first post",
    "published": true
  }
}

// Response 201
{
  "id": "uuid",
  "collection": "posts",
  "data": { "title": "Hello Koolbase", "body": "My first post", "published": true },
  "created_by": "user_uuid_or_null",
  "created_at": "2026-01-01T00:00:00Z",
  "updated_at": "2026-01-01T00:00:00Z"
}

POST /sdk/db/query

// Request
{
  "collection": "posts",
  "filters": { "published": true },
  "limit": 10,
  "offset": 0,
  "order_by": "created_at",
  "descending": true
}

// Response 200
{
  "records": [
    {
      "id": "uuid",
      "collection": "posts",
      "data": { "title": "Hello Koolbase", "published": true },
      "created_by": "user_uuid",
      "created_at": "2026-01-01T00:00:00Z",
      "updated_at": "2026-01-01T00:00:00Z"
    }
  ],
  "total": 42
}

PATCH /sdk/db/records/{id}

// Request
{
  "collection": "posts",
  "data": { "title": "Updated title" }
}

// Response 200 — full updated record
{
  "id": "uuid",
  "collection": "posts",
  "data": { "title": "Updated title", "body": "original body preserved" },
  "created_by": "user_uuid",
  "created_at": "2026-01-01T00:00:00Z",
  "updated_at": "2026-01-02T00:00:00Z"
}

Error codes

401unauthorizedNo session token — required for authenticated/owner collections

403permission_deniedUser does not own the record (owner rule violation)

404collection_not_foundCollection does not exist in this project

404record_not_foundRecord ID does not exist