• pfSense Plus 22.05 (AMD64)
• pfSense Plus 22.01 (AMD64)
• pfSense CE 2.6.0 (AMD64)
• pfSense CE 2.5.2 (AMD64)
• pfSense CE 2.5.1 (AMD64)
• pfSense CE 2.5.0 (AMD64)

Uses the same credentials as the pfSense webConfigurator. To authenticate API calls, pass in your username and password using basic authentication. For example:

curl -u admin:pfsense https://pfsense.example.com/api/v1/firewall/rule

Note: in previous releases, local database authentication used the client-id and client-token fields in your request body to authenticate. This functionality still exists but is not recommended. It will be removed in a future release.

Requires a bearer token to be included in the Authorization header of your request. These are time-based tokens that will expire after the configured amount of time. To configure the JWT expiration, navigate to System > API within the webConfigurator and ensure the the Authentication Mode is set to JWT. Then you should have the option to configure the JWT Expiration value. Alternatively, you can use the /api/v1/system/api endpoint to update the jwt_exp value. To receive a JWT, you must make a POST request to the /api/v1/access_token endpoint. This endpoint will always require the use of the Local Database authentication type to receive the JWT.

For example:

curl -u admin:pfsense -X POST https://pfsense.example.com/api/v1/access_token

Once you have your JWT, you can authenticate your API calls by adding it to the request's authorization header. For example:

curl -H "Authorization: Bearer xxxxx.xxxxxx.xxxxxx" -X GET https://pfsense.example.com/api/v1/system/arp

Uses standalone tokens generated via API or webConfigurator. These are better suited to distribute to systems as they are revocable and will only allow API authentication; not webConfigurator or SSH authentication (like the local database credentials). To generate or revoke credentials, navigate to System > API within the webConfigurator and ensure the Authentication Mode is set to API token. Then you should have the options to configure API Token generation, generate new tokens, and revoke existing tokens. After generating a new API token, the actual token will display at the top of the page on the success banner. This token will only be displayed once so ensure it is stored somewhere safe. Alternatively, you can generate new API tokens using the /api/v1/access_token endpoint. This endpoint will always require the use of the Local Database authentication type to receive the API token.

Once you have your API token, you may authenticate your API call by specifying your client-id and client-token within an Authorization header, these values must be separated by a space. For example:

curl -H "Authorization: CLIENT_ID_HERE CLIENT_TOKEN_HERE" -X GET https://pfsense.example.com/api/v1/system/arp

Note: In previous versions of pfSense API, the client-id and client-token were provided via the request payload. This functionality is still supported but is not recommended. It will be removed in a future release.

Parses the request body as a JSON formatted string. This is the recommended content type.

Example:

curl -u admin:pfsense -H "Content-Type: application/json" -d '{"service": "sshd"}' -X POST https://pfsense.example.com/api/v1/services/restart

Parses the request body as URL encoded parameters.

Example:

curl -u admin:pfsense -H "Content-Type: application/x-www-form-urlencoded" -X DELETE "https://pfsense.example.com/api/v1/firewall/alias?id=EXAMPLE_ALIAS"

Note: this content type only has the ability to pass values of string, integer, or boolean data types. Complex data types like arrays and objects cannot be parsed by the API when using this content type. It is recommended to only use this content type when making GET or DELETE requests.

You may find yourself only needing to read objects with specific values set. For example, say an API endpoint normally returns this response without a query:

{
  "status": "ok",
  "code": 200,
  "return": 0,
  "message": "Success",
  "data": [
    {
      "id": 0,
      "name": "Test",
      "type": "type1",
      "extra": {
        "tag": 0
      }
    },
    {
      "id": 1,
      "name": "Other Test",
      "type": "type2",
      "extra": {
        "tag": 100
      }
    },
    {
      "id": 2,
      "name": "Another Test",
      "type": "type1",
      "extra": {
        "tag": 200
      }
    }
  ]
}

If you want the endpoint to only return the objects that have their type value set to type1 you could add {"type": "type1"} to your payload. This returns:

{
  "status": "ok",
  "code": 200,
  "return": 0,
  "message": "Success",
  "data": [
    {
      "id": 0,
      "name": "Test",
      "type": "type1",
      "extra": {
        "tag": 0
      }
    },
    {
      "id": 2,
      "name": "Another Test",
      "type": "type1",
      "extra": {
        "tag": 200
      }
    }
  ]
}

Additionally, if you need to target values that are nested within an array, you can add {"extra__tag": 100} to recursively target the tag value within the extra array. Note the double underscore separating the parent and child keys. This returns:

{
  "status": "ok",
  "code": 200,
  "return": 0,
  "message": "Success",
  "data": [
    {
      "id": 1,
      "name": "Other Test",
      "type": "type2",
      "extra": {
        "tag": 100
      }
    }
  ]
}

Query filters allow you to apply logic to the objects you target. This makes it easy to target data that meets specific criteria:

Starts With

The startswith filter allows you to target objects whose values start with a specific substring. This will work on both string and integer data types. Below is an example response without any queries:

{
  "status": "ok",
  "code": 200,
  "return": 0,
  "message": "Success",
  "data": [
    {
      "id": 0,
      "name": "Test",
      "type": "type1",
      "extra": {
        "tag": 0
      }
    },
    {
      "id": 1,
      "name": "Other Test",
      "type": "type2",
      "extra": {
        "tag": 100
      }
    },
    {
      "id": 2,
      "name": "Another Test",
      "type": "type1",
      "extra": {
        "tag": 200
      }
    }
  ]
}

If you wanted to target objects whose names started with Other, you could use the payload {"name__startswith": "Other"}. This returns:

{
  "status": "ok",
  "code": 200,
  "return": 0,
  "message": "Success",
  "data": [
    {
      "id": 1,
      "name": "Other Test",
      "type": "type2",
      "extra": {
        "tag": 100
      }
    }
  ]
}

Ends With

The endswith filter allows you to target objects whose values end with a specific substring. This will work on both string and integer data types. Below is an example response without any queries:

{
  "status": "ok",
  "code": 200,
  "return": 0,
  "message": "Success",
  "data": [
    {
      "id": 0,
      "name": "Test",
      "type": "type1",
      "extra": {
        "tag": 0
      }
    },
    {
      "id": 1,
      "name": "Other Test",
      "type": "type2",
      "extra": {
        "tag": 100
      }
    },
    {
      "id": 2,
      "name": "Another Test",
      "type": "type1",
      "extra": {
        "tag": 200
      }
    }
  ]
}

If you wanted to target objects whose names ended with er Test, you could use the payload {"name__endswith" "er Test"}. This returns:

{
  "status": "ok",
  "code": 200,
  "return": 0,
  "message": "Success",
  "data": [
    {
      "id": 1,
      "name": "Other Test",
      "type": "type2",
      "extra": {
        "tag": 100
      }
    },
    {
      "id": 2,
      "name": "Another Test",
      "type": "type1",
      "extra": {
        "tag": 200
      }
    }
  ]
}

Contains

The contains filter allows you to target objects whose values contain a specific substring. This will work on both string and integer data types. Below is an example response without any queries:

{
  "status": "ok",
  "code": 200,
  "return": 0,
  "message": "Success",
  "data": [
    {
      "id": 0,
      "name": "Test",
      "type": "type1",
      "extra": {
        "tag": 0
      }
    },
    {
      "id": 1,
      "name": "Other Test",
      "type": "type2",
      "extra": {
        "tag": 100
      }
    },
    {
      "id": 2,
      "name": "Another Test",
      "type": "type1",
      "extra": {
        "tag": 200
      }
    }
  ]
}

If you wanted to target objects whose names contain ther, you could use the payload {"name__contains": "ther"}. This returns:

{
  "status": "ok",
  "code": 200,
  "return": 0,
  "message": "Success",
  "data": [
    {
      "id": 1,
      "name": "Other Test",
      "type": "type2",
      "extra": {
        "tag": 100
      }
    },
    {
      "id": 2,
      "name": "Another Test",
      "type": "type1",
      "extra": {
        "tag": 200
      }
    }
  ]
}

Less Than

The lt filter allows you to target objects whose values are less than a specific number. This will work on both numeric strings and integer data types. Below is an example response without any queries:

{
  "status": "ok",
  "code": 200,
  "return": 0,
  "message": "Success",
  "data": [
    {
      "id": 0,
      "name": "Test",
      "type": "type1",
      "extra": {
        "tag": 0
      }
    },
    {
      "id": 1,
      "name": "Other Test",
      "type": "type2",
      "extra": {
        "tag": 100
      }
    },
    {
      "id": 2,
      "name": "Another Test",
      "type": "type1",
      "extra": {
        "tag": 200
      }
    }
  ]
} 

If you wanted to target objects whose tag is less than 100, you could use the payload {"extra__tag__lt": 100}. This returns:

{
  "status": "ok",
  "code": 200,
  "return": 0,
  "message": "Success",
  "data": [
    {
      "id": 0,
      "name": "Test",
      "type": "type1",
      "extra": {
        "tag": 0
      }
    }
  ]
}

Less Than or Equal To

The lte filter allows you to target objects whose values are less than or equal to a specific number. This will work on both numeric strings and integer data types. Below is an example response without any queries:

{
  "status": "ok",
  "code": 200,
  "return": 0,
  "message": "Success",
  "data": [
    {
      "id": 0,
      "name": "Test",
      "type": "type1",
      "extra": {
        "tag": 0
      }
    },
    {
      "id": 1,
      "name": "Other Test",
      "type": "type2",
      "extra": {
        "tag": 100
      }
    },
    {
      "id": 2,
      "name": "Another Test",
      "type": "type1",
      "extra": {
        "tag": 200
      }
    }
  ]
}

If you wanted to target objects whose tag is less than or equal to 100, you could use the payload {"extra__tag__lte": 100}. This returns:

{
  "status": "ok",
  "code": 200,
  "return": 0,
  "message": "Success",
  "data": [
    {
      "id": 0,
      "name": "Test",
      "type": "type1",
      "extra": {
        "tag": 0
      }
    },
    {
      "id": 1,
      "name": "Other Test",
      "type": "type2",
      "extra": {
        "tag": 100
      }
    }
  ]
}

Greater Than

The gt filter allows you to target objects whose values are greater than a specific number. This will work on both numeric strings and integer data types. Below is an example response without any queries:

{
  "status": "ok",
  "code": 200,
  "return": 0,
  "message": "Success",
  "data": [
    {
      "id": 0,
      "name": "Test",
      "type": "type1",
      "extra": {
        "tag": 0
      }
    },
    {
      "id": 1,
      "name": "Other Test",
      "type": "type2",
      "extra": {
        "tag": 100
      }
    },
    {
      "id": 2,
      "name": "Another Test",
      "type": "type1",
      "extra": {
        "tag": 200
      }
    }
  ]
}

If you wanted to target objects whose tag is greater than 100, you could use the payload {"extra__tag__gt": 100}. This returns:

{
  "status": "ok",
  "code": 200,
  "return": 0,
  "message": "Success",
  "data": [
    {
      "id": 2,
      "name": "Another Test",
      "type": "type1",
      "extra": {
        "tag": 200
      }
    }
  ]
}

Greater Than or Equal To

The lte filter allows you to target objects whose values are greater than or equal to a specific number. This will work on both numeric strings and integer data types. Below is an example response without any queries:

{
  "status": "ok",
  "code": 200,
  "return": 0,
  "message": "Success",
  "data": [
    {
      "id": 0,
      "name": "Test",
      "type": "type1",
      "extra": {
        "tag": 0
      }
    },
    {
      "id": 1,
      "name": "Other Test",
      "type": "type2",
      "extra": {
        "tag": 100
      }
    },
    {
      "id": 2,
      "name": "Another Test",
      "type": "type1",
      "extra": {
        "tag": 200
      }
    }
  ]
}

If you wanted to target objects whose tag is greater than or equal to 100, you could use the payload {"extra__tag__gte": 100}. This returns:

{
  "status": "ok",
  "code": 200,
  "return": 0,
  "message": "Success",
  "data": [
    {
      "id": 1,
      "name": "Other Test",
      "type": "type2",
      "extra": {
        "tag": 100
      }
    },
    {
      "id": 2,
      "name": "Another Test",
      "type": "type1",
      "extra": {
        "tag": 200
      }
    }
  ]
}

You may notice some API endpoints require an object id to update or delete objects. These IDs are not stored values, rather pfSense uses the object's array index value to locate and identify objects. Unless specified otherwise, API endpoints will use the same array index value (as returned in the data response field) to locate objects when updating or deleting. Some important items to note about these IDs:

• pfSense starts arrays with an index of 0. If you use a loop counter to determine the ID of a specific object, you must start that counter at 0.
• These IDs are dynamic. For example, if you have 3 static route objects stored (IDs 0, 1, and 2) and you delete the object with ID 1, pfSense will resort the array so the object with ID 2 will now have an ID of 1.
• API queries will retain the object's ID in the response. In the event that the data response field is no longer a sequential array due to the query, the data field will be represented as an associative array with the array items` key being the objects ID.