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.
Beginner 2 min read 2026-05-26

API Library Overview

`api.*` is a Lua wrapper around the Wapka HTTP REST API. Same endpoints, same data — but called directly from your Lua script with automatic authentication. ...

On this page
What is the API Library? Key concepts All 60 functions at a glance List vs single return format Common filter pattern Error handling

What is the API Library?

api.* is a Lua wrapper around the Wapka HTTP REST API. Same endpoints, same data — but called directly from your Lua script with automatic authentication. No tokens, no headers, no URL construction.

Under the hood: Every api.users.get(42) is an HTTP call to GET /v1/users/42 with your site's credentials. The api.* wrapper handles auth, parsing, and errors for you.

Key concepts

Concept Description
Site-scoped You can only access data belonging to your site
Auto-authenticated Uses the current visitor's session — no API keys needed
Return format Lists return { items = {...}, total = N }. Single records return the record directly, or nil
Consistent naming Every domain follows the same pattern: get, list, create, update, delete

All 60 functions at a glance

Domain Functions What you can do
api.users (9) get, list, create, update, login, online, me, delete, stats User accounts, auth, profiles
api.sites (3) get, list, current Site info, multi-site dashboards
api.forums (5) get, list, create, rename, delete Discussion boards
api.posts (6) get, list, create, update, delete, restore Blog posts, forum threads
api.messages (7) get, send, chat, conversations, unread, edit, delete Private messaging
api.files (6) get, list, upload, import, rename, delete File management
api.folders (5) get, list, create, rename, delete Folder organization
api.pages (2) get, list Read site pages
api.codes (9) get, list, create, update, delete, copy, move, up, down Code blocks on pages
api.dataset (8) collections, get, find, create, update, delete, restore, purge_collection Your own database

List vs single return format

-- List functions: return { items = {...}, total = N }
local result = api.users.list({ page = 1, limit = 10 })
for _, user in ipairs(result.items) do
    print(user.username)
end
print("Total users: " .. result.total)

-- Single functions: return the record directly (or nil)
local user = api.users.get(42)
if user then
    print(user.username)
end

Common filter pattern

Most list() functions accept a filter table:

api.users.list({
    search = "john",      -- text search
    page = 2,             -- pagination
    limit = 25            -- per page
})

api.posts.list({
    forumid = 5,          -- filter by forum
    status = 1,           -- published only
    order = "id_desc",    -- newest first
    limit = 10
})

Error handling

When a single-record function fails, it returns nil. List functions return empty items:

local user = api.users.get(99999)
if not user then
    return ctx:error("User not found", 404)
end

local result = api.posts.list({ forumid = 99999 })
if result.total == 0 then
    return ctx:render("empty", { message = "No posts in this forum" })
end

Next: api.users — user accounts and authentication.

Next api.users