Beta documentation. This is an early preview — content is still in active development. Feedback helps shape the final release. Share your thoughts or join the discussion.
Intermediate 2 min read 2026-05-26

Dataset API

Dataset is Wapka's built-in NoSQL document database. Collections auto-create on first insert. Documents are schemaless JSON objects.

On this page
Dataset overview Simple query Query parameters Response Document fields Advanced query Query body Query operators Create a document Get a document Update a document Delete a document Restore a document List collections Purge a collection Lua API wrapper

Dataset overview

Dataset is Wapka's built-in NoSQL document database. Collections auto-create on first insert. Documents are schemaless JSON objects.

Simple query

curl "https://api.wapka.org/v1/dataset?name=posts&page=1&limit=20" \
  -H "Authorization: Bearer eyJ..."

Query parameters

Parameter Type Description
name string Collection name (required)
page int Page number
limit int Items per page

Returns all documents in the collection. To filter, use the advanced query endpoint.

Response

{
  "data": [
    {
      "id": 500,
      "name": "posts",
      "data": {
        "title": "Hello World",
        "content": "My first post.",
        "status": "published",
        "created_at": "2026-05-23T10:00:00Z"
      },
      "created_at": "2026-05-23T10:00:00Z",
      "updated_at": "2026-05-23T10:00:00Z"
    }
  ],
  "pagination": { "page": 1, "limit": 20, "totalItems": 142, "totalPages": 8, "hasNext": true, "hasPrev": false },
  "meta": { "requestId": "req_...", "timestamp": "..." }
}

Document fields

Field Type Description
id int Unique document ID
name string Collection name
data object Document data (any JSON)
created_at string Creation timestamp
updated_at string Last update timestamp

Advanced query

Send a JSON body with filter operators for powerful queries:

curl -X POST https://api.wapka.org/v1/dataset/query \
  -H "Authorization: Bearer eyJ..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "posts",
    "filter": {
      "status": "published",
      "views": { "$gte": 100 }
    },
    "sort": { "created_at": -1 },
    "page": 1,
    "limit": 20
  }'

Query body

Field Required Type Description
name Yes string Collection name
filter No object Filter conditions (see operators below)
sort No object Sort field → direction (1 = asc, -1 = desc)
page No int Page number
limit No int Items per page

Query operators

Operator Description Example
$eq Equal (default) { "status": "published" }
$ne Not equal { "status": { "$ne": "draft" } }
$gt Greater than { "views": { "$gt": 100 } }
$gte Greater than or equal { "views": { "$gte": 100 } }
$lt Less than { "age": { "$lt": 18 } }
$lte Less than or equal { "age": { "$lte": 65 } }
$in In array { "role": { "$in": ["admin", "editor"] } }
$nin Not in array { "role": { "$nin": ["banned"] } }
$regex Pattern match { "title": { "$regex": "Hello.*" } }
$exists Field exists { "email": { "$exists": true } }

Multiple filters are AND-ed together. For OR logic, use separate queries.

Create a document

Requires a logged-in token.

curl -X POST https://api.wapka.org/v1/dataset \
  -H "Authorization: Bearer eyJ..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "posts",
    "data": {
      "title": "My Document",
      "content": "Hello World",
      "status": "published"
    }
  }'
Field Required Type Description
name Yes string Collection name (auto-created if new)
data Yes object Document data (any valid JSON)

Returns 201 Created with the new document.

Get a document

curl https://api.wapka.org/v1/dataset/500 \
  -H "Authorization: Bearer eyJ..."

Update a document

Requires a logged-in token.

curl -X PATCH https://api.wapka.org/v1/dataset/500 \
  -H "Authorization: Bearer eyJ..." \
  -H "Content-Type: application/json" \
  -d '{
    "data": {
      "status": "archived",
      "views": 150
    }
  }'
Field Required Type Description
data Yes object Fields to update
replace No bool If true, replace entire document. Default merges.

By default, PATCH merges the new data with the existing document. To fully replace:

{
  "data": { "title": "Only this field remains" },
  "replace": true
}

Delete a document

Requires a logged-in token. Soft-deletes by default.

curl -X DELETE https://api.wapka.org/v1/dataset/500 \
  -H "Authorization: Bearer eyJ..."

Permanently delete:

curl -X DELETE "https://api.wapka.org/v1/dataset/500?permanent=true" \
  -H "Authorization: Bearer eyJ..."

Restore a document

curl -X POST https://api.wapka.org/v1/dataset/500/restore \
  -H "Authorization: Bearer eyJ..."

List collections

curl https://api.wapka.org/v1/dataset/_collections \
  -H "Authorization: Bearer eyJ..."

Returns all collection names for the site.

Purge a collection

Requires admin (level ≥ 8). Permanently deletes all documents in a collection.

curl -X DELETE https://api.wapka.org/v1/dataset/posts/purge \
  -H "Authorization: Bearer eyJ..."

Warning: This action cannot be undone. All documents in the collection are permanently removed.

Lua API wrapper

-- Simple query
local posts = api.dataset:list({ name = "posts", page = 1, limit = 20 })

-- Advanced query
local popular = api.dataset:query({
    name = "posts",
    filter = { status = "published", views = { ["$gte"] = 100 } },
    sort = { created_at = -1 }
})

-- Create
api.dataset:create({
    name = "posts",
    data = { title = "Hello", content = "World" }
})

-- Get
local doc = api.dataset:get(500)

-- Update (merge)
api.dataset:update(500, { data = { status = "archived" } })

-- Update (replace)
api.dataset:update(500, { data = { title = "New" }, replace = true })

-- Soft delete
api.dataset:delete(500)

-- Permanent delete
api.dataset:delete(500, true)

-- Restore
api.dataset:restore(500)

-- List collections
local cols = api.dataset:collections()

-- Purge (admin only)
api.dataset:purgeCollection("posts")

Next: Check the Dataset docs for the Lua dataset() API which runs server-side with no auth overhead.

Previous Pages & Codes