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",
              "$createdBy": "user_uuid",
              "$createdAt": "2026-01-01T00:00:00Z",
              "$updatedAt": "2026-01-01T00:00:00Z",
              "title": "Hello Koolbase",
              "body": "My first post",
              "published": true
            }

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",
      "$createdBy": "user_uuid",
      "$createdAt": "2026-01-01T00:00:00Z",
      "$updatedAt": "2026-01-01T00:00:00Z",
      "title": "Hello Koolbase",
      "published": true
    }
  ],
  "total": 42
}

PATCH /sdk/db/records/{id}

// Request
{
  "collection": "posts",
  "data": { "title": "Updated title" }
}
// Response 200 — full updated record
{
  "$id": "uuid",
  "$collection": "posts",
  "$createdBy": "user_uuid",
  "$createdAt": "2026-01-01T00:00:00Z",
  "$updatedAt": "2026-01-02T00:00:00Z",
  "title": "Updated title",
  "body": "original body preserved"
}

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