Skip to main content

Brown Out

The brownout policy allows performing scheduled downtime on your API. This can be useful for helping notify clients of an impending deprecation or for scheduling maintenance.

This policy uses cron schedules to check if a request should experience a brownout or not. When a request falls into a scheduled brownout an error response will be return. The error response can be customized by setting the problem properties.

For more information using brownouts to alert clients on impending API changes/deprecations see our blog post How to version an API


The configuration shows how to configure the policy in the 'policies.json' document.

"name": "my-brownout-inbound-policy",
"policyType": "brownout-inbound",
"handler": {
"export": "BrownOutInbound",
"module": "$import(@zuplo/runtime)",
"options": {
"cronSchedule": "0 23 * * *",
"problem": {
"detail": "This endpoint is deprecated and will be removed in the next version"
  • name the name of your policy instance. This is used as a reference in your routes.
  • policyType the identifier of the policy. This is used by the Zuplo UI. Value should be brownout-inbound.
  • handler/export The name of the exported type. Value should be BrownOutInbound.
  • handler/module the module containing the policy. Value should be $import(@zuplo/runtime).
  • handler/options The options for this policy:
    • cronSchedule

      The cron schedule for when this policy is enabled. This can be a single cron string or an array of multiple cron strings

    • problem

      The problem that is returned in the response body when this policy is enabled

      • type

        The type of problem

      • title

        The title of problem

      • detail

        The detail of problem

      • status

        Http status code of the problem

Read more about how policies work