List Templates

List Custom Error Templates

GET /v1/templates

List the caller's uploaded custom HTML error pages. Each template is rendered in place of the default Ngris error page when a request hits a matching condition — for example, a custom 403 page when the firewall denies a request, or a custom 502 page when the upstream is unreachable.

Only one template per type can be active at a time per user. Activate via /templates/{uuid}/activate; upload via /templates.

Query params

page int

1-based page number. Omit (or 0) for the legacy bare-array response.

page_size int

Rows per page. Default 15; values above 200 are capped at 200. Ignored when page is omitted.

Response (200 OK)

Two shapes for backward compatibility:

Legacy (no page): bare JSON array of every template; [] when there are none.

Paginated (page ≥ 1): envelope with templates (always a list, [] when empty), total (templates across all pages), page and page_size. Each template:

uuid string (uuid)

The template's public id. Use with delete and activate.

user_uuid string (uuid)?

The user who uploaded the template.

type string

One of: firewall, rate_limit, bad_gateway, service_unavailable, not_found, request_timeout, internal_error, gateway_timeout. Determines which error condition the page replaces.

content string

Raw HTML body of the template. Up to 100 KB.

is_active boolean

true if this template is currently serving the given type for the user.

created_at, updated_at datetime

RFC 3339 UTC.

Deprecated: until the sunset this response also carries the legacy integer id and *_id fields. Don't use them; read uuid and the *_uuid fields.

Errors

401 Unauthorized

Missing or invalid auth.

Request
curl "https://api.ngris.com/v1/templates?page=1&page_size=25" \
  -H "X-API-KEY: <your_api_key>"

Python
from ngris import Ngris

client = Ngris(api_key="<your_api_key>")
result = client._get_raw("/templates", params={"page": 1, "page_size": 25})
for t in result["templates"]:
    active = " (active)" if t["is_active"] else ""
    print(f"{t['type']:<20} {t['uuid']}{active}")

Response — 200 OK (paginated)
{
  "templates": [
    {
      "uuid": "019b0817-a55a-7007-b556-eea4fe532a62",
      "user_uuid": "019a52c2-ca1e-78ba-ab5c-50362cc29134",
      "type": "firewall",
      "content": "<!doctype html><html><body>Blocked.</body></html>",
      "is_active": true,
      "created_at": "2026-04-01T10:00:00Z",
      "updated_at": "2026-04-01T10:00:00Z"
    }
  ],
  "total": 1,
  "page": 1,
  "page_size": 25
}

Was this helpful?

PreviousGenerate Rate Limit (AI) NextUpload Template

On this page

List Custom Error Templates

Was this helpful?