Sign inStart free
Documentation

API Reference

Call https://webppt.webp.se over HTTPS with Content-Type and api-key headers.

All documentation Open the Dashboard

The WebP Cloud API provides a standardized programmatic interface to access its infrastructure.

To interact with the information available, you can make HTTPS requests to a specific version endpoint URL. The API supports various methods, including GET, POST, PUT, PATCH, and DELETE, which determine how you interact with the data. It's important to note that all endpoints are accessible only through the SSL-enabled HTTPS protocol on port 443.

API base URL

https://webppt.webp.se

All requests must have the following headers:

  • Content-Type: application/json
  • api-key: <Your API Key Here>

User

Get user info

GET /v1/user/info

Example response:

{
    "data": {
        "user_uuid": "76f4a288-ba0a-45d5-b93a-ce3738949934",
        "name": "Nova Kwok",
        "email": "n0vad3v@riseup.net",
        "avatar_url": "https://avatars.githubusercontent.com/u/24852034?v=4",
        "api_key": "dd25162a-xxxx-xxxx-xxxx-86a6727e96a3",
        "daily_quota": 9999988401,
        "daily_quota_limit": 10000000000,
        "permanent_quota": 11998906,
        "user_plan": "personal_plus",
        "balance": 0,
        "address": "THYgQZ5CJT3y3ZJmR2yS34cSh631PNvQ4N",
        "is_checked_in": false,
        "login_by": "github",
        "is_admin": true
    },
    "success": true
}

Get user stats

GET /v1/user/stats

Example response:

{
    "data": {
        "user_uuid": "dc185b97-12af-455b-9337-8356a48bf098",
        "user_total_bytes_sent": 6083487548,
        "user_daily_bytes_sent": [
            {
                "date": "2023-08-18",
                "bytes_sent": 35293558,
                "count": 2009
            },
            {
                "date": "2023-08-19",
                "bytes_sent": 70078770,
                "count": 2146
            },
            {
                "date": "2023-08-20",
                "bytes_sent": 337527554,
                "count": 2649
            },
            {
                "date": "2023-08-21",
                "bytes_sent": 70577230,
                "count": 2050
            },
            {
                "date": "2023-08-22",
                "bytes_sent": 142492032,
                "count": 2028
            },
            {
                "date": "2023-08-23",
                "bytes_sent": 94466746,
                "count": 1905
            },
            {
                "date": "2023-08-24",
                "bytes_sent": 46264580,
                "count": 237
            }
        ]
    },
    "success": true
}

Get user metrics

GET /v1/user/metrics

Example response:

user_bytes_sent_total 197517756
user_daily_quota 649
user_daily_quota_limit 1000
user_permanent_quota 1000

Proxy

Create proxy

POST /v1/proxy

Proxy Region

Currently regions are:

  • Nuremberg (NUE)
  • Helsinki (HEL)
  • Hillsboro,OR (HIO)

Example Payload

{
  "proxy_name": "ECENPAC Proxy",
  "proxy_origin_url": "https://www.ecenpac.com",
  "proxy_region": "NUE"
}

Example response:

{
    "proxy_uuid": "a533df3e-2918-4775-b47b-32b5e0bab296",
    "success": true
}

List all proxies

GET /v1/proxy

Example response:

{
    "data": [
        {
            "proxy_uuid": "d86f08d1-f29c-4889-8063-431e10e74c8e",
            "proxy_name": "Docs",
            "proxy_origin_url": "https://www.ecenpac.com",
            "proxy_proxy_url": "https://ysjbjsw.webp.ee",
            "proxy_ua": "WebP Cloud Services/1.0",
            "proxy_cors_header": "*",
            "proxy_allowed_referer": "*",
            "proxy_quality": 80,
            "proxy_cache_expire": 0,
            "proxy_cache_size": 9210737,
            "proxy_cache_size_limit": 104857600,
            "proxy_adaptive_resize": false,
            "proxy_adaptive_resize_desktop_width": 1600,
            "proxy_adaptive_resize_mobile_width": 800,
            "proxy_enabled": true,
            "proxy_visual_effects": [
                {
                    "item_uuid": "fac3fbbe-3494-4fe1-9393-dedff4720344",
                    "type": "watermark",
                    "watermark": {
                        "name": "bad for json",
                        "text": "We have 一只 憂鬱的臺灣烏龜。こんにちわ，ガッキー！ 조선말 Tiếng",
                        "font": "sans 12",
                        "width": 0.1,
                        "height": 0.1,
                        "offset_x": 0.22,
                        "offset_y": 0.2,
                        "color": "001489ff",
                        "rotate": 0,
                        "fill": ""
                    }
                },
                {
                    "item_uuid": "aden",
                    "type": "filter",
                    "filter": {
                        "name": "aden"
                    }
                }
            ],
            "proxy_created_at": "2023-08-05T15:26:00Z",
            "proxy_enable_extra_params": true,
            "proxy_region": "NUE",
            "proxy_extra_headers": [
                {
                    "key": "Header2",
                    "value": "Value2"
                }
            ]
        }
    ],
    "success": true
}

Get proxy stats

GET /v1/proxy/<proxy_uuid>/stats

Returns proxy configuration together with usage series. proxy_daily_bytes_sent covers the recent 30 days. proxy_visitor_distribution_7_days and proxy_visitor_distribution_30_days are null when there is no visitor data, and proxy_last_logs is an empty array when there are no recent requests.

Example response:

{
    "data": {
        "proxy_uuid": "36d5c79f-08d9-4605-9231-5c5371a829d5",
        "proxy_name": "Custom domain test proxy",
        "proxy_origin_url": "https://example.com",
        "proxy_proxy_url": "https://e814cdf.webp.li",
        "proxy_ua": "WebP Cloud Services/1.0",
        "proxy_cors_header": "*",
        "proxy_allowed_referer": "*",
        "proxy_quality": 80,
        "proxy_cache_expire": 0,
        "proxy_cache_size": 0,
        "proxy_cache_size_limit": 4194304000,
        "proxy_enabled": true,
        "proxy_operation_on_disabled": "redirect",
        "proxy_created_at": "2026-10-27T08:07:05Z",
        "proxy_enable_extra_params": true,
        "proxy_adaptive_resize": false,
        "proxy_adaptive_resize_desktop_width": 1600,
        "proxy_adaptive_resize_mobile_width": 800,
        "proxy_visual_effects": [],
        "proxy_region": "HIO",
        "proxy_extra_headers": [],
        "proxy_total_requests": 0,
        "proxy_total_bytes_sent": 0,
        "proxy_total_top_requested_path": [],
        "proxy_daily_bytes_sent": [
            {
                "date": "2026-09-28",
                "bytes_sent": 0,
                "count": 0,
                "cache_hit_ratio": 0
            },
            ...
            {
                "date": "2026-10-27",
                "bytes_sent": 0,
                "count": 0,
                "cache_hit_ratio": 0
            }
        ],
        "proxy_visitor_distribution_7_days": null,
        "proxy_visitor_distribution_30_days": null,
        "proxy_last_logs": [],
        "proxy_custom_domain": [
            {
                "custom_domain_uuid": "4c6cce6b-239f-4c55-9add-2075cab8db2c",
                "status": "pending",
                "user_confirmed": false,
                "proxy_proxy_url": "my-webp.your-domain.com",
                "verification_errors": "",
                "ownership_verification_key": "_cf-custom-hostname.my-webp.your-domain.com",
                "ownership_verification_value": "904a80a2-d68c-489d-869a-9fa87804feb3",
                "dcv_delegation_record_key": "_acme-challenge.my-webp.your-domain.com",
                "dcv_delegation_record_value": "wzDIlcHJcM8-IbpZwDS4ZHnU_IOQyPepZm7Q9o-Y6t0",
                "dcv_delegation_record_key_2": "_acme-challenge.my-webp.your-domain.com",
                "dcv_delegation_record_value_2": "zNx0BmIKW1tJ1FElDwIHaCbrU8DdijMsOL6rFIBRnyk"
            }
        ],
        "proxy_mode": ""
    },
    "success": true
}

Get proxy info

GET /v1/proxy/<proxy_uuid>/info

Returns the same proxy object without the usage series. proxy_total_top_requested_path, proxy_daily_bytes_sent, both visitor distributions, and proxy_last_logs are null. proxy_mode is the selected mode, such as consistency.

Example response:

{
    "data": {
        "proxy_uuid": "36d5c79f-08d9-4605-9231-5c5371a829d5",
        "proxy_name": "Custom domain test proxy",
        "proxy_origin_url": "https://example.com",
        "proxy_proxy_url": "https://e814cdf.webp.li",
        "proxy_ua": "WebP Cloud Services/1.0",
        "proxy_cors_header": "*",
        "proxy_allowed_referer": "*",
        "proxy_quality": 80,
        "proxy_cache_expire": 0,
        "proxy_cache_size": 0,
        "proxy_cache_size_limit": 4194304000,
        "proxy_enabled": true,
        "proxy_operation_on_disabled": "redirect",
        "proxy_created_at": "2026-10-27T08:07:05Z",
        "proxy_enable_extra_params": true,
        "proxy_adaptive_resize": false,
        "proxy_adaptive_resize_desktop_width": 1600,
        "proxy_adaptive_resize_mobile_width": 800,
        "proxy_visual_effects": [],
        "proxy_region": "HIO",
        "proxy_extra_headers": [],
        "proxy_total_requests": 0,
        "proxy_total_bytes_sent": 0,
        "proxy_total_top_requested_path": null,
        "proxy_daily_bytes_sent": null,
        "proxy_visitor_distribution_7_days": null,
        "proxy_visitor_distribution_30_days": null,
        "proxy_last_logs": null,
        "proxy_custom_domain": [
            {
                "custom_domain_uuid": "4c6cce6b-239f-4c55-9add-2075cab8db2c",
                "status": "pending",
                "user_confirmed": false,
                "proxy_proxy_url": "my-webp.your-domain.com",
                "verification_errors": "",
                "ownership_verification_key": "_cf-custom-hostname.my-webp.your-domain.com",
                "ownership_verification_value": "904a80a2-d68c-489d-869a-9fa87804feb3",
                "dcv_delegation_record_key": "_acme-challenge.my-webp.your-domain.com",
                "dcv_delegation_record_value": "wzDIlcHJcM8-IbpZwDS4ZHnU_IOQyPepZm7Q9o-Y6t0",
                "dcv_delegation_record_key_2": "_acme-challenge.my-webp.your-domain.com",
                "dcv_delegation_record_value_2": "zNx0BmIKW1tJ1FElDwIHaCbrU8DdijMsOL6rFIBRnyk"
            }
        ],
        "proxy_mode": "consistency"
    },
    "success": true
}

Get proxy metrics

GET /v1/proxy/<proxy_uuid>/metrics

Example response:

proxy_requests_total{cache_status="all"} 154
proxy_requests_total{cache_status="hit"} 48
proxy_bytes_sent_total 65839252
proxy_cache_size 2956337
proxy_cache_size_limit 3480000

Edit Proxy

PUT /v1/proxy/<proxy_uuid>

Example payload:

{
  "proxy_name": "NovaProxy3",
  "proxy_quality": 90,
  "proxy_enabled": true,
  "proxy_ua": "Custom UA",
  "proxy_cors_header": "*",
  "proxy_allowed_referer": "*",
  "proxy_adaptive_resize": false,
  "proxy_adaptive_resize_desktop_width": 1600,
  "proxy_adaptive_resize_mobile_width": 800,
  "proxy_extra_headers": [
        {
            "key": "Header2",
            "value": "Value2"
        }
    ],
}
  • proxy_ua is User Agent used when WebP Cloud fetch original image from origin server.
  • proxy_cors_header is CORS header used when WebP Cloud renders image. Header name: Access-Control-Allow-Origin
  • proxy_allowed_referer is allowed referer header when WebP Cloud renders image. Setting this other than * will make WebP Cloud check for Referer header, and only allow specified referer to access image. * means allow all referer, to allow multiple domains, use comma serperated hostname, like blog.webp.se,nova.moe,dmesg.app,tuki.moe.
  • proxy_extra_headers is extra headers to be added when WebP Cloud fetch original image from origin server, currently max 5 headers are allowed, the key and value are both string length less than 100, and host, referer, origin header is not allowed.

Example response:

{
    "success": true
}

Delete Proxy

DELETE /v1/proxy/<proxy_uuid>

Example response:

{
    "success": true
}

Purge cache

Purge all cache under given <proxy_uuid>

POST /v1/proxy/<proxy_uuid>/purge_cache

Example response:

{
    "success": true
}

Clear cache

Purge cache under given <proxy_uuid> with path

POST /v1/proxy/<proxy_uuid>/clear_cache

Example Payload

{
  "path": "/post/weekly-recap/2023/28-ordinary-days/spirit-toad.jpg"
}

Example response:

{
    "success": true
}

Create custom domain for Proxy

POST /v1/proxy/<proxy_uuid>/custom_domain

Example Payload

{
  "proxy_proxy_url": "my-webp.your-domain.com"
}

Example response:

{
    "success": true
}

After creation, you can refer to /v1/proxy/<proxy_uuid>/stats API for detailed DNS setup instructions, for example for a proxy located at NUE region:

...
"proxy_custom_domain": [
    {
        "custom_domain_uuid": "4c6cce6b-239f-4c55-9add-2075cab8db2c",
        "status": "pending",
        "user_confirmed": false,
        "proxy_proxy_url": "my-webp.your-domain.com",
        "verification_errors": "",
        "ownership_verification_key": "_cf-custom-hostname.my-webp.your-domain.com",
        "ownership_verification_value": "904a80a2-d68c-489d-869a-9fa87804feb3",
        "dcv_delegation_record_key": "_acme-challenge.my-webp.your-domain.com",
        "dcv_delegation_record_value": "wzDIlcHJcM8-IbpZwDS4ZHnU_IOQyPepZm7Q9o-Y6t0",
        "dcv_delegation_record_key_2": "_acme-challenge.my-webp.your-domain.com",
        "dcv_delegation_record_value_2": "zNx0BmIKW1tJ1FElDwIHaCbrU8DdijMsOL6rFIBRnyk"
    }
]
...

user_confirmed stays false until you confirm the DNS records. Certificate validation needs both DCV TXT records. They use the same name and different values, from dcv_delegation_record_* and dcv_delegation_record_*_2.

In the example above you should create the following DNS records:

  • CNAME
    • my-webp.your-domain.com
    • to
    • lb.webp.ee (As the region is NUE, read more at Custom Domain)
  • TXT
    • _cf-custom-hostname.my-webp.your-domain.com
    • with value of
    • 904a80a2-d68c-489d-869a-9fa87804feb3
  • TXT
    • _acme-challenge.my-webp.your-domain.com
    • with value of
    • wzDIlcHJcM8-IbpZwDS4ZHnU_IOQyPepZm7Q9o-Y6t0
  • TXT
    • _acme-challenge.my-webp.your-domain.com
    • with value of
    • zNx0BmIKW1tJ1FElDwIHaCbrU8DdijMsOL6rFIBRnyk

Confirm custom domain status

Once successfully added DNS records, you can use this Endpoint to check if confirm that your DNS is setup, then our system will tries to validate your setup.

GET /v1/proxy/<proxy_uuid>/custom_domain

Example response:

{
    "success": true
}

Calling this endpoint sets user_confirmed to true. After confirm, please allow sometime for our side to check, should be within minutes, but can be as long as 24hrs for DNS to propagate, you should refer to /v1/proxy/<proxy_uuid>/stats API for proxy_custom_domain's status, if it's active, you're ready to activate it.

Activate custom domain

Once the proxy_custom_domain is active, you can activate your custom domain using:

GET /v1/proxy/<proxy_uuid>/custom_domain/activate

Example response:

{
    "success": true
}

This endpoint will change your current proxy_proxy_url to your proxy_custom_domain's proxy_proxy_url (your custom domain), and proxy_custom_domain's status will become activated.

Delete custom domain for Proxy

This endpoint will remove your current custom domain and generate a new domain for you proxy.

DELETE /v1/proxy/<proxy_uuid>/custom_domain

Example response:

{
    "success": true
}

Visual Effects

Currently supported visual effects are:

  • watermark
  • filter

Create watermark

POST /v1/visual/watermark

Example Payload

{
  "name": "good",
  "text": "aawae",
  "font": "sans 12",
  "width": 0.1,
  "height": 0.1,
  "offset_x": 0.22,
  "offset_y": 0.2,
  "color": "001489ff",
  "fill": "123456c4"
}
  • name: Just the name of this watermark preset.
  • text: Text to be added on image, need to be encoded in base64 (url-safe).
  • font: Font name, currently we support 11 fonts, see below for details
  • color: Text color, in hex format, w/o transparency
  • width: Relative text width, in percentage from 0 to 1
  • height: Relative text height, in percentage from 0 to 1
  • offset_x: Relative text x position, in percentage from 0 to 1
  • offset_y: Relative text y position, in percentage from 0 to 1
  • fill: Fill text background color, in hex format or empty, empty means no fill

All parameters are required.

Supported font list:

Font NameParameter name (font)
Sanssans 12
RobotoRoboto
Noto SansNoto Sans
Source Han Sans（思源黑体）Source Han Sans HC VF
wqy-zenhei（文泉驿正黑体）WenQuanYi Zen Hei
FZFangSong-Z02（方正仿宋）FZFangSong-Z02
FZHei-B01（方正黑体）FZHei-B01
FZKai-Z03（方正楷体）FZKai-Z03
FZShuSong-Z01（方正书宋）FZShuSong-Z01
Architects DaughterArchitects Daughter
Gloria HallelujahGloria Hallelujah
XiaolaiSC（小赖字体）XiaolaiSC
LXGW WenKai(霞鹜文楷)LXGW WenKai

Example response:

{
    "item_uuid": "e8391198-28a9-4a0f-acc8-fd42f3bb0f1e",
    "success": true
}

List Watermark

GET /v1/visual/watermark

Example response:

{
    "data": [
        {
            "item_uuid": "3f36673b-a002-4b84-8533-021969c85ca1",
            "type": "watermark",
            "watermark": {
                "name": "bad for json",
                "text": "New text for json",
                "font": "sans 12",
                "width": 0.1,
                "height": 0.1,
                "offset_x": 0.22,
                "offset_y": 0.2,
                "color": "001489",
                "rotate": 0,
                "fill": ""
            }
        },
        {
            "item_uuid": "fac3fbbe-3494-4fe1-9393-dedff4720344",
            "type": "watermark",
            "watermark": {
                "name": "bad for json",
                "text": "We have 一只 憂鬱的臺灣烏龜。こんにちわ，ガッキー！ 조선말 Tiếng",
                "font": "sans 12",
                "width": 0.1,
                "height": 0.1,
                "offset_x": 0.22,
                "offset_y": 0.2,
                "color": "001489",
                "rotate": 0,
                "fill": ""
            }
        }
    ],
    "success": true
}

Bind watermark to proxy

POST /v1/proxy/:proxy_uuid/visual/watermark

Example Payload

{
  "item_uuids": ["cf4ef256-bf0a-4fc8-a3a8-529f283b0db9"]
}

If you passin item_uuids as empty array, it will remove all watermarks from proxy.

Example response:

{
    "success": true
}

Now you can check for proxy info:

{
    "data": [
        {
            "proxy_uuid": "d86f08d1-f29c-4889-8063-431e10e74c8e",
            "proxy_name": "Docs",
            "proxy_origin_url": "https://docs.webp.se",
            "proxy_proxy_url": "https://830368c.webp.ee",
            "proxy_ua": "WebP Cloud Services/1.0",
            "proxy_quality": 80,
            "proxy_cache_expire": 0,
            "proxy_cache_size": 9210737,
            "proxy_cache_size_limit": 104857600,
            "proxy_enabled": true,
            "proxy_visual_effects": [
                {
                    "item_uuid": "fac3fbbe-3494-4fe1-9393-dedff4720344",
                    "type": "watermark",
                    "watermark": {
                        "name": "bad for json",
                        "text": "We have 一只 憂鬱的臺灣烏龜。こんにちわ，ガッキー！ 조선말 Tiếng",
                        "font": "sans 12",
                        "width": 0.1,
                        "height": 0.1,
                        "offset_x": 0.22,
                        "offset_y": 0.2,
                        "color": "001489",
                        "rotate": 0,
                        "fill": ""
                    }
                },
                {
                    "item_uuid": "aden",
                    "type": "filter",
                    "filter": {
                        "name": "aden"
                    }
                }
            ],
            "proxy_created_at": "2023-08-05T15:26:00Z",
            "proxy_enable_extra_params": true,
            "proxy_region": "NUE"
        }
    ],
    "success": true
}

Bind filter to proxy

POST /v1/proxy/:proxy_uuid/visual/filter

Supported item_uuid are: 1977, aden, brannan, Brooklyn, clarendon, earlybird, gingham, hudson, inkwell, kelvin, lark, lofi, maven, mayfair, moon, nashville, perpetua, reyes, rise, slumber, stinson, toaster, valencia, walden, willow, xpro2

Example Payload

{
  "item_uuids": ["1977"]
}

If you passin item_uuids as empty array, it will remove all filters from proxy.

Example response:

{
    "success": true
}

Delete watermark

Unbound watermark from all applied proxies, and delete watermark

Delete watermark will remove it from all proxies

DELETE /v1/visual/watermark/:watermark_uuid

Example response:

{
    "success": true
}

Update watermark

PUT /v1/visual/watermark/:watermark_uuid

Example Payload

{
  "name": "new name really",
  "text": "aawae",
  "font":"sans 12",
  "width": 0.3,
  "height": 0.3,
  "offset_x": 0.3,
  "offset_y": 0.3,
  "color": "121212",
  "fill": ""
}

Example response:

{
    "success": true
}