REST API

Introduction

The REST API provides a modern, JSON-based interface to WebPal using standard HTTP methods and RESTful conventions. It uses Laravel Sanctum for authentication and is ideal for web and mobile applications.

Base URL

https://YOURSERVER.webpal.net/api

Authentication

Session-Based (Browser)

Login to get a session (cookie-based for browser use):

POST /api/login
Content-Type: application/json

{
    "login": "myuser",
    "password": "mypassword"
}

Response:

{
    "user": {
        "id": 123,
        "name": "John Doe",
        "email": "john@example.com"
    }
}

Token-Based (Programmatic)

Create a personal access token in your account settings and include it as a Bearer token in all requests:

Authorization: Bearer YOUR_TOKEN_HERE

Two-Factor Authentication

If 2FA is enabled for your account:

POST /api/2fa/request-code    — Request a 2FA code
POST /api/2fa/verify-code     — Verify the code

Response Format

All responses are JSON with the following structure:

Success Response

{
    "data": {
        // Response data here
    }
}

Error Response

{
    "message": "Error description",
    "errors": {
        "field": ["Validation error message"]
    }
}

Document Endpoints

Get Document Metadata

GET /api/documents/{id}

Update Document Metadata

PATCH /api/documents/{id}

{
    "title": "Updated Title",
    "comments": "Updated description"
}

Delete Document

DELETE /api/documents/{id}

Upload File

POST /api/documents/upload
Content-Type: multipart/form-data

folder_id: 123
file: [binary file data]
title: "Optional Title"

Download File

GET /api/documents/{id}/download

Get Thumbnail

GET /api/documents/{id}/thumbnail

Get Full Metadata

GET /api/documents/{id}/metadata

Move Document

POST /api/documents/{id}/move

{
    "folder_id": 456
}

Copy Document

POST /api/documents/{id}/copy

{
    "folder_id": 456,
    "name": "Copy of Document"
}

Folder Endpoints

List Folder Contents

GET /api/folders/{id}/contents?page=1&per_page=50

Response:

{
    "data": [
        {
            "id": 123,
            "name": "document.pdf",
            "type": "file",
            "size": 1024000,
            "mime_type": "application/pdf",
            "created_at": "2026-04-01T10:00:00Z",
            "updated_at": "2026-04-15T14:30:00Z"
        }
    ],
    "meta": {
        "current_page": 1,
        "total": 42
    }
}

Search Within Folder

GET /api/folders/{id}/search?q=query&filter=pdf

List Shared Folders

GET /api/folders/shares

User Endpoints (Admin Only)

List Users

GET /api/users?page=1&per_page=20

Create User

POST /api/users

{
    "name": "Jane Smith",
    "email": "jane@example.com",
    "login": "jsmith",
    "password": "secure_password"
}

Get User Details

GET /api/users/{id}

Update User

PATCH /api/users/{id}

{
    "name": "Jane Doe",
    "email": "jane.doe@example.com"
}

Delete User

DELETE /api/users/{id}

Activity Endpoints

Activity Log

GET /api/activity?page=1&per_page=50

Per-Document Activity

GET /api/v2/documents/{id}/activity

Response:

{
    "data": [
        {
            "id": 1001,
            "action": "Uploaded",
            "user": "John Doe",
            "timestamp": "2026-04-15T14:30:00Z",
            "details": "Initial upload"
        }
    ]
}

Share Endpoints

Create Share

POST /api/shares

{
    "document_id": 123,
    "users": ["alice", "bob"],
    "permissions": 529,
    "notify": true
}

Rate Limiting

The REST API enforces rate limiting to prevent abuse:

• Authenticated requests: 60 requests per minute
• Guest requests: 10 requests per minute

Rate limit headers are included in all responses:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 45
X-RateLimit-Reset: 1650000000

HTTP Status Codes

Code	Meaning
200	Success
201	Created
400	Bad Request
401	Unauthorized
403	Forbidden
404	Not Found
422	Validation Error
429	Too Many Requests
500	Server Error