Appwrite Firewall (WAF) API

openapi: 3.0.0
info:
  title: Appwrite Waf API
  description: Appwrite backend as a service cuts up to 70% of the time and costs required for building a modern application. We abstract and simplify common development tasks behind a REST APIs, to help you develop your app in a fast and secure way. For full API documentation and tutorials go to [https://appwrite.io/docs](https://appwrite.io/docs)
  version: 2.0.0
  termsOfService: https://appwrite.io/policy/terms
  contact:
    name: Appwrite Team
    url: https://appwrite.io/support
    email: team@appwrite.io
  license:
    name: BSD-3-Clause
    url: https://raw.githubusercontent.com/appwrite/appwrite/master/LICENSE
servers:
- url: https://cloud.appwrite.io/v1
  description: Appwrite Cloud endpoint.
- url: https://{region}.cloud.appwrite.io/v1
  description: Appwrite Cloud regional endpoint. Replace `{region}` with your project region.
  variables:
    region:
      default: fra
      description: Appwrite Cloud region.
tags:
- name: waf
  description: Appwrite waf service.
paths:
  /waf/rules:
    get:
      summary: List WAF rules.
      operationId: wafListRules
      tags:
      - waf
      description: 'List WAF rules for the current project.

        '
      responses:
        '200':
          description: WAF rule list
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/wafRuleList'
      deprecated: false
      x-appwrite:
        group: rules
        demo: waf/list-rules.md
        rate-limit: 0
        rate-time: 3600
        rate-key: url:{url},ip:{ip}
        scope: wafRules.read
        platforms:
        - console
        - server
        packaging: false
        public: true
        auth:
          console:
            Project: []
          server:
            Project: []
            Key: []
      security:
      - Project: []
        Key: []
      parameters:
      - name: queries
        description: Array of query strings generated using the Query class provided by the SDK. [Learn more about queries](https://appwrite.io/docs/queries). Maximum of 100 queries are allowed, each 4096 characters long.
        required: false
        schema:
          type: array
          items:
            type: string
          default: []
        in: query
      - name: search
        description: 'Search term to filter your list results. Max length: 256 chars.'
        required: false
        schema:
          type: string
          example: <SEARCH>
          default: ''
        in: query
      - name: total
        description: When set to false, the total count returned will be 0 and will not be calculated.
        required: false
        schema:
          type: boolean
          example: false
          default: true
        in: query
  /waf/rules/bypass:
    post:
      summary: Create a bypass WAF rule.
      operationId: wafCreateBypassRule
      tags:
      - waf
      description: 'Create a bypass WAF rule. Conditions can match request attributes including `ip` (plain IPs or CIDR blocks like `10.0.0.0/8`), `method`, `path`, `host`, `country`, `continent`, `headers.<name>`, `query.<key>`, `queryKeys`, `userAgent`, `os`, `osVersion`, `browser`, and `browserVersion`. Conditions on `city` and `state` require the premium Geo DB addon.

        '
      responses:
        '201':
          description: WafRuleBypass
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/wafRuleBypass'
      deprecated: false
      x-appwrite:
        group: rules
        demo: waf/create-bypass-rule.md
        rate-limit: 0
        rate-time: 3600
        rate-key: url:{url},ip:{ip}
        scope: wafRules.write
        platforms:
        - console
        - server
        packaging: false
        public: true
        auth:
          console:
            Project: []
          server:
            Project: []
            Key: []
      security:
      - Project: []
        Key: []
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                ruleId:
                  description: Rule ID. Choose a custom ID or pass `ID.unique()` to generate a unique one.
                  type: string
                  example: <RULE_ID>
                  x-appwrite:
                    idGenerator: ID.unique
                resourceType:
                  description: Resource type the rule applies to.
                  type: string
                  example: api
                resourceId:
                  description: Resource identifier. Leave empty for the API resource type.
                  type: string
                  example: <RESOURCE_ID>
                  nullable: true
                name:
                  description: Rule name.
                  type: string
                  example: <NAME>
                description:
                  description: Optional description for the rule.
                  type: string
                  default: ''
                  example: <DESCRIPTION>
                priority:
                  description: Evaluation priority. Lower numbers run earlier.
                  type: integer
                  default: 0
                  example: -100000
                  format: int32
                enabled:
                  description: Set to false to create the rule in a disabled state.
                  type: boolean
                  default: true
                  example: false
                conditions:
                  description: Array of condition strings generated using the WAF Condition builder. Maximum of 100 conditions are allowed, each 4096 characters long.
                  type: string
                  default: []
              required:
              - ruleId
              - resourceType
              - name
  /waf/rules/bypass/{ruleId}:
    patch:
      summary: Update a bypass WAF rule.
      operationId: wafUpdateBypassRule
      tags:
      - waf
      description: 'Update a bypass WAF rule. Conditions can match request attributes including `ip` (plain IPs or CIDR blocks like `10.0.0.0/8`), `method`, `path`, `host`, `country`, `continent`, `headers.<name>`, `query.<key>`, `queryKeys`, `userAgent`, `os`, `osVersion`, `browser`, and `browserVersion`. Conditions on `city` and `state` require the premium Geo DB addon.

        '
      responses:
        '200':
          description: WafRuleBypass
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/wafRuleBypass'
      deprecated: false
      x-appwrite:
        group: rules
        demo: waf/update-bypass-rule.md
        rate-limit: 0
        rate-time: 3600
        rate-key: url:{url},ip:{ip}
        scope: wafRules.write
        platforms:
        - console
        - server
        packaging: false
        public: true
        auth:
          console:
            Project: []
          server:
            Project: []
            Key: []
      security:
      - Project: []
        Key: []
      parameters:
      - name: ruleId
        description: Rule ID.
        required: true
        schema:
          type: string
          example: <RULE_ID>
        in: path
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                resourceType:
                  description: Resource type the rule applies to.
                  type: string
                  example: api
                  nullable: true
                resourceId:
                  description: Resource identifier. Required for functions and sites.
                  type: string
                  example: <RESOURCE_ID>
                  nullable: true
                name:
                  description: Rule name.
                  type: string
                  example: <NAME>
                  nullable: true
                description:
                  description: Optional description for the rule.
                  type: string
                  example: <DESCRIPTION>
                  nullable: true
                priority:
                  description: Evaluation priority. Lower numbers run earlier.
                  type: integer
                  example: -100000
                  format: int32
                  nullable: true
                enabled:
                  description: Set to false to disable the rule.
                  type: boolean
                  example: false
                  nullable: true
                conditions:
                  description: Array of condition strings generated using the WAF Condition builder. Maximum of 100 conditions are allowed, each 4096 characters long.
                  type: string
                  nullable: true
  /waf/rules/challenge:
    post:
      summary: Create a challenge WAF rule.
      operationId: wafCreateChallengeRule
      tags:
      - waf
      description: 'Create a challenge WAF rule. Use `difficulty` (1 easiest to 5 hardest) to tune the client-side proof-of-work cost, and `ttl` to control how long, in seconds, a visitor stays cleared after passing the challenge before being challenged again. Conditions can match request attributes including `ip` (plain IPs or CIDR blocks like `10.0.0.0/8`), `method`, `path`, `host`, `country`, `continent`, `headers.<name>`, `query.<key>`, `queryKeys`, `userAgent`, `os`, `osVersion`, `browser`, and `browserVersion`. Conditions on `city` and `state` require the premium Geo DB addon.

        '
      responses:
        '201':
          description: WafRuleChallenge
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/wafRuleChallenge'
      deprecated: false
      x-appwrite:
        group: rules
        demo: waf/create-challenge-rule.md
        rate-limit: 0
        rate-time: 3600
        rate-key: url:{url},ip:{ip}
        scope: wafRules.write
        platforms:
        - console
        - server
        packaging: false
        public: true
        auth:
          console:
            Project: []
          server:
            Project: []
            Key: []
      security:
      - Project: []
        Key: []
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                ruleId:
                  description: Rule ID. Choose a custom ID or pass `ID.unique()` to generate a unique one.
                  type: string
                  example: <RULE_ID>
                  x-appwrite:
                    idGenerator: ID.unique
                resourceType:
                  description: Resource type the rule applies to.
                  type: string
                  example: api
                resourceId:
                  description: Resource identifier. Required for functions and sites.
                  type: string
                  example: <RESOURCE_ID>
                  nullable: true
                name:
                  description: Rule name.
                  type: string
                  example: <NAME>
                description:
                  description: Optional description for the rule.
                  type: string
                  default: ''
                  example: <DESCRIPTION>
                challengeType:
                  description: Challenge type enforced by the rule.
                  type: string
                  default: compute
                  example: compute
                priority:
                  description: Evaluation priority. Lower numbers run earlier.
                  type: integer
                  default: 0
                  example: -100000
                  format: int32
                enabled:
                  description: Set to false to create the rule in a disabled state.
                  type: boolean
                  default: true
                  example: false
                conditions:
                  description: Array of condition strings generated using the WAF Condition builder. Maximum of 100 conditions are allowed, each 4096 characters long.
                  type: string
                  default: []
                difficulty:
                  description: Challenge difficulty from 1 (easiest) to 5 (hardest). Higher values demand more client-side proof-of-work.
                  type: integer
                  default: 3
                  example: 1
                  format: int32
                ttl:
                  description: How long, in seconds, a visitor stays cleared after passing the challenge before being challenged again.
                  type: integer
                  default: 1800
                  example: 900
                  format: int32
              required:
              - ruleId
              - resourceType
              - name
  /waf/rules/challenge/{ruleId}:
    patch:
      summary: Update a challenge WAF rule.
      operationId: wafUpdateChallengeRule
      tags:
      - waf
      description: 'Update a challenge WAF rule. Use `difficulty` (1 easiest to 5 hardest) to tune the client-side proof-of-work cost, and `ttl` to control how long, in seconds, a visitor stays cleared after passing the challenge before being challenged again. Conditions can match request attributes including `ip` (plain IPs or CIDR blocks like `10.0.0.0/8`), `method`, `path`, `host`, `country`, `continent`, `headers.<name>`, `query.<key>`, `queryKeys`, `userAgent`, `os`, `osVersion`, `browser`, and `browserVersion`. Conditions on `city` and `state` require the premium Geo DB addon.

        '
      responses:
        '200':
          description: WafRuleChallenge
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/wafRuleChallenge'
      deprecated: false
      x-appwrite:
        group: rules
        demo: waf/update-challenge-rule.md
        rate-limit: 0
        rate-time: 3600
        rate-key: url:{url},ip:{ip}
        scope: wafRules.write
        platforms:
        - console
        - server
        packaging: false
        public: true
        auth:
          console:
            Project: []
          server:
            Project: []
            Key: []
      security:
      - Project: []
        Key: []
      parameters:
      - name: ruleId
        description: Rule ID.
        required: true
        schema:
          type: string
          example: <RULE_ID>
        in: path
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                resourceType:
                  description: Resource type the rule applies to.
                  type: string
                  example: api
                  nullable: true
                resourceId:
                  description: Resource identifier. Required for functions and sites.
                  type: string
                  example: <RESOURCE_ID>
                  nullable: true
                name:
                  description: Rule name.
                  type: string
                  example: <NAME>
                  nullable: true
                description:
                  description: Optional description for the rule.
                  type: string
                  example: <DESCRIPTION>
                  nullable: true
                challengeType:
                  description: Challenge type enforced by the rule.
                  type: string
                  example: compute
                  nullable: true
                priority:
                  description: Evaluation priority. Lower numbers run earlier.
                  type: integer
                  example: -100000
                  format: int32
                  nullable: true
                enabled:
                  description: Set to false to disable the rule.
                  type: boolean
                  example: false
                  nullable: true
                conditions:
                  description: Array of condition strings generated using the WAF Condition builder. Maximum of 100 conditions are allowed, each 4096 characters long.
                  type: string
                  nullable: true
                difficulty:
                  description: Challenge difficulty from 1 (easiest) to 5 (hardest). Higher values demand more client-side proof-of-work.
                  type: integer
                  example: 1
                  format: int32
                  nullable: true
                ttl:
                  description: How long, in seconds, a visitor stays cleared after passing the challenge before being challenged again.
                  type: integer
                  example: 900
                  format: int32
                  nullable: true
  /waf/rules/deny:
    post:
      summary: Create a deny WAF rule.
      operationId: wafCreateDenyRule
      tags:
      - waf
      description: 'Create a deny WAF rule. Conditions can match request attributes including `ip` (plain IPs or CIDR blocks like `10.0.0.0/8`), `method`, `path`, `host`, `country`, `continent`, `headers.<name>`, `query.<key>`, `queryKeys`, `userAgent`, `os`, `osVersion`, `browser`, and `browserVersion`. Conditions on `city` and `state` require the premium Geo DB addon.

        '
      responses:
        '201':
          description: WafRuleDeny
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/wafRuleDeny'
      deprecated: false
      x-appwrite:
        group: rules
        demo: waf/create-deny-rule.md
        rate-limit: 0
        rate-time: 3600
        rate-key: url:{url},ip:{ip}
        scope: wafRules.write
        platforms:
        - console
        - server
        packaging: false
        public: true
        auth:
          console:
            Project: []
          server:
            Project: []
            Key: []
      security:
      - Project: []
        Key: []
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                ruleId:
                  description: Rule ID. Choose a custom ID or pass `ID.unique()` to generate a unique one.
                  type: string
                  example: <RULE_ID>
                  x-appwrite:
                    idGenerator: ID.unique
                resourceType:
                  description: Resource type the rule applies to.
                  type: string
                  example: api
                resourceId:
                  description: Resource identifier. Required for functions and sites.
                  type: string
                  example: <RESOURCE_ID>
                  nullable: true
                name:
                  description: Rule name.
                  type: string
                  example: <NAME>
                description:
                  description: Optional description for the rule.
                  type: string
                  default: ''
                  example: <DESCRIPTION>
                priority:
                  description: Evaluation priority. Lower numbers run earlier.
                  type: integer
                  default: 0
                  example: -100000
                  format: int32
                enabled:
                  description: Set to false to create the rule in a disabled state.
                  type: boolean
                  default: true
                  example: false
                conditions:
                  description: Array of condition strings generated using the WAF Condition builder. Maximum of 100 conditions are allowed, each 4096 characters long.
                  type: string
                  default: []
              required:
              - ruleId
              - resourceType
              - name
  /waf/rules/deny/{ruleId}:
    patch:
      summary: Update a deny WAF rule.
      operationId: wafUpdateDenyRule
      tags:
      - waf
      description: 'Update a deny WAF rule. Conditions can match request attributes including `ip` (plain IPs or CIDR blocks like `10.0.0.0/8`), `method`, `path`, `host`, `country`, `continent`, `headers.<name>`, `query.<key>`, `queryKeys`, `userAgent`, `os`, `osVersion`, `browser`, and `browserVersion`. Conditions on `city` and `state` require the premium Geo DB addon.

        '
      responses:
        '200':
          description: WafRuleDeny
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/wafRuleDeny'
      deprecated: false
      x-appwrite:
        group: rules
        demo: waf/update-deny-rule.md
        rate-limit: 0
        rate-time: 3600
        rate-key: url:{url},ip:{ip}
        scope: wafRules.write
        platforms:
        - console
        - server
        packaging: false
        public: true
        auth:
          console:
            Project: []
          server:
            Project: []
            Key: []
      security:
      - Project: []
        Key: []
      parameters:
      - name: ruleId
        description: Rule ID.
        required: true
        schema:
          type: string
          example: <RULE_ID>
        in: path
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                resourceType:
                  description: Resource type the rule applies to.
                  type: string
                  example: api
                  nullable: true
                resourceId:
                  description: Resource identifier. Required for functions and sites.
                  type: string
                  example: <RESOURCE_ID>
                  nullable: true
                name:
                  description: Rule name.
                  type: string
                  example: <NAME>
                  nullable: true
                description:
                  description: Optional description for the rule.
                  type: string
                  example: <DESCRIPTION>
                  nullable: true
                priority:
                  description: Evaluation priority. Lower numbers run earlier.
                  type: integer
                  example: -100000
                  format: int32
                  nullable: true
                enabled:
                  description: Set to false to disable the rule.
                  type: boolean
                  example: false
                  nullable: true
                conditions:
                  description: Array of condition strings generated using the WAF Condition builder. Maximum of 100 conditions are allowed, each 4096 characters long.
                  type: string
                  nullable: true
  /waf/rules/rate-limit:
    post:
      summary: Create a rate-limit WAF rule.
      operationId: wafCreateRateLimitRule
      tags:
      - waf
      description: 'Create a rate limit WAF rule. Use `key` to choose the counter: `ip` limits per client IP, while `userId` limits per authenticated user (requests without an authenticated user skip `userId` rules). Conditions can match request attributes including `ip` (plain IPs or CIDR blocks like `10.0.0.0/8`), `method`, `path`, `host`, `country`, `continent`, `headers.<name>`, `query.<key>`, `queryKeys`, `userAgent`, `os`, `osVersion`, `browser`, and `browserVersion`. Conditions on `city` and `state` require the premium Geo DB addon.

        '
      responses:
        '201':
          description: WafRuleRateLimit
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/wafRuleRateLimit'
      deprecated: false
      x-appwrite:
        group: rules
        demo: waf/create-rate-limit-rule.md
        rate-limit: 0
        rate-time: 3600
        rate-key: url:{url},ip:{ip}
        scope: wafRules.write
        platforms:
        - console
        - server
        packaging: false
        public: true
        auth:
          console:
            Project: []
          server:
            Project: []
            Key: []
      security:
      - Project: []
        Key: []
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                ruleId:
                  description: Rule ID. Choose a custom ID or pass `ID.unique()` to generate a unique one.
                  type: string
                  example: <RULE_ID>
                  x-appwrite:
                    idGenerator: ID.unique
                resourceType:
                  description: Resource type the rule applies to.
                  type: string
                  example: api
                resourceId:
                  description: Resource identifier. Required for functions and sites.
                  type: string
                  example: <RESOURCE_ID>
                  nullable: true
                name:
                  description: Rule name.
                  type: string
                  example: <NAME>
                description:
                  description: Optional description for the rule.
                  type: string
                  default: ''
                  example: <DESCRIPTION>
                limit:
                  description: Maximum number of matching requests allowed in the configured interval.
                  type: integer
                  example: 1
                  format: int32
                interval:
                  description: Interval in seconds used for rate limiting.
                  type: integer
                  example: 1
                  format: int32
                key:
                  description: Rate limit key. Use `ip` to limit per client IP or `userId` to limit per authenticated user. Requests without an authenticated user skip `userId` rules.
                  type: string
                  default: ip
                  example: ip
                strategy:
                  description: Rate limit strategy. `fixedWindow` counts requests in discrete intervals, `slidingWindow` weights the previous interval for smoother limiting, and `tokenBucket` refills allowance continuously to permit short bursts.
                  type: string
                  default: fixedWindow
                  example: fixedWindow
                maxBucketSize:
                  description: Maximum number of tokens the bucket can hold for the `tokenBucket` strategy, controlling how large a burst is allowed. The sustained refill rate is `limit / interval`. Defaults to `limit` when omitted. Ignored by other strategies.
                  type: integer
                  example: 1
                  format: int32
                  nullable: true
                priority:
                  description: Evaluation priority. Lower numbers run earlier.
                  type: integer
                  default: 0
                  example: -100000
                  format: int32
                enabled:
                  description: Set to false to create the rule in a disabled state.
                  type: boolean
                  default: true
                  example: false
                conditions:
                  description: Array of condition strings generated using the WAF Condition builder. Maximum of 100 conditions are allowed, each 4096 characters long.
                  type: string
                  default: []
              required:
              - ruleId
              - resourceType
              - name
              - limit
              - interval
  /waf/rules/rate-limit/{ruleId}:
    patch:
      summary: Update a rate-limit WAF rule.
      operationId: wafUpdateRateLimitRule
      tags:
      - waf
      description: 'Update a rate limit WAF rule. Use `key` to choose the counter: `ip` limits per client IP, while `userId` limits per authenticated user (requests without an authenticated user skip `userId` rules). Conditions can match request attributes including `ip` (plain IPs or CIDR blocks like `10.0.0.0/8`), `method`, `path`, `host`, `country`, `continent`, `headers.<name>`, `query.<key>`, `queryKeys`, `userAgent`, `os`, `osVersion`, `browser`, and `browserVersion`. Conditions on `city` and `state` require the premium Geo DB addon.

        '
      responses:
        '200':
          description: WafRuleRateLimit
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/wafRuleRateLimit'
      deprecated: false
      x-appwrite:
        group: rules
        demo: waf/update-rate-limit-rule.md
        rate-limit: 0
        rate-time: 3600
        rate-key: url:{url},ip:{ip}
        scope: wafRules.write
        platforms:
        - console
        - server
        packaging: false
        public: true
        auth:
          console:
            Project: []
          server:
            Project: []
            Key: []
      security:
      - Project: []
        Key: []
      parameters:
      - name: ruleId
        description: Rule ID.
        required: true
        schema:
          type: string
          example: <RULE_ID>
        in: path
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                resourceType:
                  description: Resource type the rule applies to.
                  type: string
                  example: api
                  nullable: true
                resourceId:
                  description: Resource identifier. Required for functions and sites.
                  type: string
                  example: <RESOURCE_ID>
                  nullable: true
                name:
                  description: Rule name.
                  type: string
                  example: <NAME>
                  nullable: true
                description:
                  description: Optional description for the rule.
                  type: string
                  example: <DESCRIPTION>
                  nullable: true
                limit:
                  description: Maximum number of matching requests allowed in the configured interval.
                  type: integer
                  example: 1
                  format: int32
                  nullable: true
                interval:
                  description: Interval in seconds used for rate limiting.
                  type: integer
                  example: 1
                  format: int32
                  nullable: true
                key:
                  description: Rate limit key. Use `ip` to limit per client IP or `userId` to limit per authenticated user. Requests without an authenticated user skip `userId` rules.
                  type: string
                  example: ip
                  nullable: true
                maxBucketSize:
                  description: Maximum number of tokens the bucket can hold for the `tokenBucket` strategy, controlling how large a burst is allowed. The sustained refill rate is `limit / interval`. Ignored by other strategies. The strategy itself cannot be changed after creation.
                  type: integer
                  example: 1
                  format: int32
                  nullable: true
                priority:
                  description: Evaluation priority. Lower numbers run earlier.
                  type: integer
                  example: -100000
                  format: int32
                  nullable: true
                enabled:
                  description: Set to false to disable the rule.
                  type: boolean
                  example: false
                  nullable: true
                conditions:
                  description: Array of condition strings generated using the WAF Condition builder. Maximum of 100 conditions are allowed, each 4096 characters long.
                  type: string
                  nullable: true
  /waf/rules/redirect:
    post:
      summary: Create a redirect WAF rule.
      operationId: wafCreateRedirectRule
      tags:
      - waf
      description: 'Create a redirect WAF rule. Conditions can match request attributes including `ip` (plain IPs or CIDR blocks like `10.0.0.0/8`), `method`, `path`, `host`, `country`, `continent`, `headers.<name>`, `query.<key>`, `queryKeys`, `userAgent`, `os`, `osVersion`, `browser`, and `

# --- truncated at 32 KB (63 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/appwrite/refs/heads/main/openapi/appwrite-waf-api-openapi.yml