Using the API

Welcome to the Sharemeister API guide. This documentation provides everything you need to programmatically upload screenshots to your On-Premises instance using tools like curl, ShareX, or custom scripts.

Authentication

To authenticate your API requests, you must use a personal API token generated directly in the Sharemeister web interface.

Generating an API Key

1. Log into your Sharemeister Dashboard.
2. Navigate to Settings via the account menu.
3. Scroll down to the API Access section.
4. Click Generate API Key.
5. CRITICAL: Copy the generated token immediately. For security reasons, it will only be displayed once.

Authorization Header

The API uses Bearer Authentication. You must include your token in the Authorization header of every request:

Authorization: Bearer YOUR_PERSONAL_API_TOKEN
Accept: application/json

API Endpoints

All endpoints expect standard HTTPS requests. If you run Sharemeister inside a local container structure (e.g., Podman/Docker behind a reverse proxy), replace the base URL with your specific domain or local IP.

Endpoint Overview

Method	Endpoint	Description	Content-Type
POST	/api/upload	Standard Multi-part Upload	multipart/form-data
POST	/api/upload/raw	Raw Binary Payload Upload	application/octet-stream

Examples

Method A: Multi-part Upload (/api/upload)

This is the standard upload method used by most web forms and HTTP clients. The file must be passed as a form parameter named image.

curl -X POST https://your-sharemeister-domain.com/api/upload \
  -H "Authorization: Bearer 1|abcdefghijklmnopqrstuvwxyz..." \
  -H "Accept: application/json" \
  -F "image=@/path/to/your/screenshot.png"

Method B: Raw Binary Upload (/api/upload/raw)

Ideal for minimal environments, lightweight CLI applications, or advanced ShareX configurations. Send the file content directly inside the request body without any multi-part boundaries.

curl -X POST https://your-sharemeister-domain.com/api/upload/raw \
  -H "Authorization: Bearer 1|abcdefghijklmnopqrstuvwxyz..." \
  -H "Accept: application/json" \
  -H "Content-Type: application/octet-stream" \
  --data-binary "@/path/to/your/screenshot.png"

API Responses

Success

Success Response (201 Created)

If the upload is successful—or if the built-in Duplicate Finder detects that you have already uploaded this exact file previously—the API returns a JSON payload containing the direct public URL.

{
    "success": true,
    "message": "Upload successful",
    "url": "https://your-sharemeister-domain.com/screenshots/user_1/2026/06/aBcDeFgH.webp"
}

Note on Performance: If a duplicate file hash is matched, the API dynamically returns the existing resource link and updates its internal timestamp (updated_at), pushing it to the top of your dashboard library without consuming extra disk I/O or storage.

Error Responses

Storage Limit Reached (403 Forbidden)

{
    "error": "Storage limit reached."
}

File Too Large (422 Unprocessable Entity)

Returned when the physical file size exceeds the strict server-side max_upload_size defined in the application configuration.

{
    "error": "File too large. Max allowed: 10240 KB."
}