openapi: 3.1.0
info:
  title: pfSense REST API (pfSense-pkg-RESTAPI) Authentication Firewall Aliases API
  description: 'Community-maintained REST and GraphQL API package for pfSense CE and

    pfSense Plus that exposes 200+ endpoints under /api/v2 for firewall,

    interface, service, user, and system management. Authentication supports

    HTTP Basic, X-API-Key header, and JWT bearer tokens obtained from

    POST /api/v2/auth/jwt.


    Only a representative subset of the pfSense REST API surface

    (auth, firewall aliases, firewall rules, diagnostics) is modeled here.

    See the documentation linked under externalDocs for the full catalog.

    '
  version: 2.0.0
  contact:
    name: pfSense REST API documentation
    url: https://pfrest.org/
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0
servers:
- url: https://{pfSenseHost}/api/v2
  description: pfSense host running pfSense-pkg-RESTAPI.
  variables:
    pfSenseHost:
      default: pfsense.local
      description: Hostname or IP of the pfSense instance.
security:
- basicAuth: []
- apiKeyAuth: []
- bearerAuth: []
tags:
- name: Firewall Aliases
  description: Manage firewall aliases.
paths:
  /firewall/aliases:
    get:
      tags:
      - Firewall Aliases
      summary: List firewall aliases
      operationId: listFirewallAliases
      parameters:
      - $ref: '#/components/parameters/Limit'
      - $ref: '#/components/parameters/Offset'
      - $ref: '#/components/parameters/SortBy'
      - $ref: '#/components/parameters/SortOrder'
      responses:
        '200':
          description: Array of firewall aliases.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/FirewallAlias'
  /firewall/alias:
    get:
      tags:
      - Firewall Aliases
      summary: Get a single firewall alias
      operationId: getFirewallAlias
      parameters:
      - in: query
        name: id
        required: true
        schema:
          type: integer
      responses:
        '200':
          description: A firewall alias.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/FirewallAlias'
    post:
      tags:
      - Firewall Aliases
      summary: Create a firewall alias
      operationId: createFirewallAlias
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FirewallAlias'
      responses:
        '200':
          description: Firewall alias created.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/FirewallAlias'
    patch:
      tags:
      - Firewall Aliases
      summary: Update a firewall alias
      operationId: patchFirewallAlias
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FirewallAlias'
      responses:
        '200':
          description: Firewall alias updated.
    delete:
      tags:
      - Firewall Aliases
      summary: Delete a firewall alias
      operationId: deleteFirewallAlias
      parameters:
      - in: query
        name: id
        required: true
        schema:
          type: integer
      responses:
        '200':
          description: Firewall alias deleted.
components:
  parameters:
    Limit:
      in: query
      name: limit
      schema:
        type: integer
        default: 0
      description: Maximum number of results.
    SortBy:
      in: query
      name: sort_by
      schema:
        type: string
      description: Field name to sort by.
    Offset:
      in: query
      name: offset
      schema:
        type: integer
        default: 0
      description: Skip the first N results.
    SortOrder:
      in: query
      name: sort_order
      schema:
        type: string
        enum:
        - SORT_ASC
        - SORT_DESC
  schemas:
    FirewallAlias:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string
        type:
          type: string
          enum:
          - host
          - network
          - port
          - url
          - url_ports
          - urltable
          - urltable_ports
        descr:
          type: string
        address:
          type: array
          items:
            type: string
        detail:
          type: array
          items:
            type: string
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
      description: 'HTTP Basic auth with a pfSense local database username and password.

        '
    apiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
      description: 'API key generated through the webConfigurator or API endpoints. Keys

        inherit the permissions of the user that issued them.

        '
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: 'JWT bearer token obtained from POST /api/v2/auth/jwt. Tokens default

        to one hour of validity.

        '
externalDocs:
  description: pfSense-pkg-RESTAPI documentation
  url: https://pfrest.org/