Add Website Domain API

Add one website domain to a VIP WebPush application. Deploy the SDK and Service Worker and obtain user permission separately.

Use Basic Auth with the AppKey and MasterSecret in the same data center. The required domain field uses portalweb domain-save validation as its baseline, requires explicit lowercase https://, and accepts lowercase input only. Domains and IPv4 are accepted with or without numeric ports; IPv6 is rejected. The confirmed acceptance rules allow port 65536, so 65535 is not an admission limit; zero and leading-zero ports remain rejected. An optional trailing root slash / is allowed and equivalent to no slash for duplicate checks. Path segments such as /page, queries, fragments, whitespace, localhost (including subdomains and trailing-dot variants), HTTP and wildcards are rejected. IPv4 syntax is checked without filtering address purposes; DNS, reachability and certificates are not checked. Valid input is stored unchanged. request_id is optional and limited to 128 bytes; echo boundaries are described below.

Basic Auth

POST /v4/web/domains

              
              curl -X POST https://webpushapi-sgp.engagelab.com/v4/web/domains \
  -u APP_KEY:MASTER_SECRET \
  -H "Content-Type: application/json" \
  -d '{
    "domain": "https://shop-001.example.com",
    "request_id": "req-001"
  }'

            

HTTP 200:

              
              {
  "request_id": "req-001",
  "domain_id": "wd_<sha256>",
  "domain": "https://shop-001.example.com",
  "integration_status": "pending",
  "config_status": "ready"
}

            

integration_status: pending / integrated. config_status: ready (pending: reserved).

              
              {
  "error": {
    "code": 27601,
    "message": "DOMAIN_ALREADY_EXISTS"
  },
  "request_id": "req-001",
  "domain_id": "wd_<sha256>",
  "domain": "https://shop-001.example.com",
  "integration_status": "pending",
  "config_status": "ready"
}

            

Sequential repeated requests do not consume additional quota. Duplicate comparison ignores case, trailing slashes and the default 443 port. New domains retain the validated lowercase host and submitted port; existing domains retain their stored spelling and integration status. A duplicate returns HTTP 400 with the existing domain information. The API uses the console quota. Send additions sequentially and avoid simultaneous console changes; concurrent writes may overwrite one another. Configuration propagation follows existing console behavior and may be delayed. API operations are recorded in service logs, without a console operation-history entry. Retry the same domain after a timeout or 5xx. Deletion, modification, batch addition and quota purchase are not supported. This API reuses the application QPS quota configured in deviceapi, with the existing system default when no quota is configured. Requests are counted separately by AppKey and API; duplicate calls also consume QPS. When the limit is exceeded, it returns HTTP 400 with code 23010 (Rate limit exceeded for the API). Retry later with backoff.

Request validation, error codes and request_id echo

The request body is limited to 4 KiB. domain must be a non-empty string. A missing, null, empty, numeric, boolean, array or object domain, malformed or multiple JSON values, an oversized body, or request_id longer than 128 bytes returns HTTP 400 / 21003 Invalid request without request_id. A non-empty string that reaches domain-format validation returns HTTP 400 / 27600 INVALID_DOMAIN if its format is invalid.

After request-structure validation succeeds, a valid non-empty request_id is echoed unchanged in subsequent business responses, including 27600, 27601 and rate-limit error 23010. The field is omitted when absent or empty. An invalid Basic authorization header rejected before body parsing also produces no request_id.

Rate limiting uses the application app_qps value, falling back to the business default when missing or zero; there is no universal fixed threshold for all applications. Requests are counted separately by AppKey + /v4/web/domains. Duplicate requests also consume QPS, and rate limiting occurs before duplicate-domain checks. Exceeding the quota returns HTTP 400 / 23010 Rate limit exceeded for the API, not HTTP 429. Retry with backoff.

              
              {"error":{"code":21003,"message":"Invalid request"}}

            

              
              {"request_id":"invalid-domain","error":{"code":27600,"message":"INVALID_DOMAIN"}}

            

              
              {"request_id":"qps-example","error":{"code":23010,"message":"Rate limit exceeded for the API"}}