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

Files & Folders

```bash

On this page
Files List files Upload a file

Files

List files

curl "https://api.wapka.org/v1/files?folderid=0&page=1&limit=20&sort=-created_at" \
  -H "Authorization: Bearer eyJ..."

Query parameters

Parameter Type Description
folderid int Filter by folder ID (0 = root)
search string Search by file name
sort string Sort field (prefix - for descending)
page int Page number
limit int Items per page

Response

{
  "data": [
    {
      "id": 200,
      "name": "photo.jpg",
      "size": 1024000,
      "mime": "image/jpeg",
      "url": "https://yoursite.wapka.site/files/photo.jpg",
      "cdn_url": "https://cdn.wapka.org/files/200/photo.jpg",
      "thumb_url": "https://cdn.wapka.org/thumbs/200/photo.jpg",
      "folder": { "id": 0, "name": "Root" },
      "owner": {
        "id": 36012,
        "username": "johndoe",
        "avatar": "https://img.wapka.org/u/36012.jpg"
      },
      "permissions": { "read": 0, "write": 0 },
      "created_at": "2026-05-23T10:00:00Z"
    }
  ],
  "pagination": { "page": 1, "limit": 20, "totalItems": 15, "totalPages": 1, "hasNext": false, "hasPrev": false },
  "meta": { "requestId": "req_...", "timestamp": "..." }
}

File fields

Field Type Description
id int Unique file ID
name string File name
size int File size in bytes
mime string MIME type
url string Direct site URL
cdn_url string CDN URL (faster delivery)
thumb_url string Thumbnail URL (images only)
folder object Parent folder reference
owner object Uploader reference
permissions object Access permission model
created_at string Upload timestamp

Upload a file

Requires a logged-in token. Use multipart/form-data:

curl -X POST https://api.wapka.org/v1/files/upload \
  -H "Authorization: Bearer eyJ..." \
  -F "file=@/path/to/photo.jpg" \
  -F "folderid=0"

| Field | Required | Type | Description |
|-------|----------|------|-------------|
| `file` | Yes | file | The file to upload |
| `folderid` | No | int | Target folder ID (0 = root) |

Returns `201 Created` with the new file metadata including all URLs.

### Import a file from URL

Download a file from an external URL into your site:

```bash
curl -X POST https://api.wapka.org/v1/files \
  -H "Authorization: Bearer eyJ..." \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/image.png",
    "folderid": 0
  }'
Field Required Type Description
url Yes string External URL to download from
folderid No int Target folder ID

Get a file

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

Rename a file

curl -X PATCH https://api.wapka.org/v1/files/200 \
  -H "Authorization: Bearer eyJ..." \
  -H "Content-Type: application/json" \
  -d '{ "name": "new-name.jpg" }'

Delete a file

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

Returns 204 No Content.

Folders

List folders

curl "https://api.wapka.org/v1/folders?parent=0" \
  -H "Authorization: Bearer eyJ..."

Query parameters

Parameter Type Description
parent int Filter by parent folder ID (0 = root)

Response

{
  "data": [
    {
      "id": 5,
      "name": "Images",
      "file_count": 42,
      "folder_count": 2,
      "parent": { "id": 0, "name": "Root" },
      "owner": {
        "id": 36012,
        "username": "johndoe",
        "avatar": "https://img.wapka.org/u/36012.jpg"
      },
      "created_at": "2025-06-01T00:00:00Z"
    }
  ],
  "meta": { "requestId": "req_...", "timestamp": "..." }
}

Folder fields

Field Type Description
id int Unique folder ID
name string Folder name
file_count int Number of files inside
folder_count int Number of sub-folders
parent object Parent folder reference
owner object Creator reference
created_at string Creation timestamp

Create a folder

curl -X POST https://api.wapka.org/v1/folders \
  -H "Authorization: Bearer eyJ..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Documents",
    "parent": 0
  }'
Field Required Type Description
name Yes string Folder name
parent No int Parent folder ID (0 = root)

Get a folder

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

Rename a folder

curl -X PATCH https://api.wapka.org/v1/folders/5 \
  -H "Authorization: Bearer eyJ..." \
  -H "Content-Type: application/json" \
  -d '{ "name": "Photos" }'

Delete a folder

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

Returns 204 No Content.

Lua API wrapper

-- Files
local files = api.files:list({ folderid = 0, page = 1, limit = 20 })
local file = api.files:get(200)
api.files:rename(200, "new-name.jpg")
api.files:delete(200)

-- Folders
local folders = api.folders:list({ parent = 0 })
local folder = api.folders:get(5)
api.folders:create({ name = "Documents", parent = 0 })
api.folders:rename(5, "Photos")
api.folders:delete(5)

Next: Pages & Codes — read site pages and code blocks.

Previous Messages Next Pages & Codes