>
    PAN-OS REST API Request and Response Structure
    Focus
    Download PDF
    Focus
    1. Home
    2. Next-Generation Firewall
    3. Get Started with the PAN-OS REST API
    4. PAN-OS REST API Request and Response Structure
    Download PDF
    Next-Generation Firewall

    PAN-OS REST API Request and Response Structure

    Table of Contents

    PAN-OS REST API Request and Response Structure

    The PAN-OS REST API enables you to perform CRUD operations with objects and use them in policy rules. A resource in the PAN-OS REST API is an endpoint that you can configure with parameters. When you make requests with the endpoints, you get responses that contain information. The request and response formats support JSON (default) and XML.
    After you configure the firewalls and Panorama using the REST API, you must use the XML API or the other management interfaces to commit your changes to the running configuration.

    Request Format

    The API request format is constructed as shown in the example below:
    curl -X GET "https://<IP address or FQDN of the firewall or Panorama>/restapi/<PAN-OS version>/<resource URI>?<query parameters>request body"
    • Base path and the resource URI for the endpoint. See Access the PAN-OS REST API for details.
    • Query parameters. Every request includes query parameters that are passed to the API endpoint using query strings. The query parameters are  appended to the URL with a ? that indicates the start of the query string. The query parameters appear after the  ?, the parameter are concatenated with other parameters using the ampersand  & symbol.
      Query Parameters on the firewall
      • name (name) of the resource.
      • location (vsys, predefined, shared, panorama-pushed) of the resource on which you want to perform the operation. A predefined object or rule is built-in to the firewall and you cannot edit, rename or delete predefined objects or policy rules.
      • virtual system (vsys) name for the resource, if location is vsys or panorama-pushed.
      • input format (input-format). JSON is default, or XML. You can specify an input format for HTTP methods that have a request body, such as PUT to update and POST to create a resource.
      • output format (output-format) JSON default, or XML
      Query Parameters on Panorama
      • name (name) of the resource.
      • location (predefined, shared, device-group, panorama-pushed) of the resource on which you want to perform the operation. A predefined object or rule is built-in to Panorama and you cannot edit, rename or delete predefined objects or policy rules.
      • device group (device-group) name of the Panorama device group to which you have assigned the firewalls, if location is device-group.
      • input format (input-format). JSON is default, or XML. You can specify an input format for HTTP methods that have a request body, such as PUT to update and POST to create a resource.
      • output format (output-format) JSON default, or XML
    • Request body. When you create a resource with a POST request or edit a resource with a PUT request, you include a JSON or XML formatted request body in which you specify the properties for the resource you want to create or modify on the endpoint.
    When you make an API request to the firewall or Panorama, the API key is required to authenticate the user who is making the request. You can enter the key with the custom HTTP headerX-PAN-KEY: <key>. Learn about API Authentication and Security and how to Generate an API Key Certificate.

    Success Response Format

    The HTTP response for a successful call has three elements: status, code, and result. The code is a numeric value. Refer to the PAN-OS XML API Error Codes for details on the code included in the HTTP response message. 
    
						{
    "@code": "19",
    "@status": "success",
    "result": {
        "@count": "3",
        "@total-count": "3",
        "entry": [
            {
                "@location": "vsys",
                "@name": "fqdn1",
                "@vsys": "vsys1",
                "fqdn": "www.test.com"
            },
            {
                "@location": "vsys",
                "@name": "Peer1",
                "@vsys": "vsys1",
                "ip-netmask": "172.0.0.1/24"
            },
            {
                "@location": "vsys",
                "@name": "Peer2renamed",
                "@oldname": "Peer2",
                "@vsys": "vsys1",
                "ip-netmask": "200.0.0.1/24"
            }
        ]
    }
}

    Error Response Format

    In addition to the HTTP status code, the error response includes a JSON object or XML with error information. The following is an example of an error response body from a REST API call to get an address. In this example, the request is missing a query parameter: 
    
		{
    "code": 3,
    "details": [
        {
            "@type": "CauseInfo",
            "causes": [
                {
                    "code": 7,
                    "description": "Missing Query Parameter: name",
                    "module": "panui_restapi"
                }
            ]
        }
    ],
    "message": "Missing Query Parameter: name"
}
    The following table describes the error response fields.
    FieldDescription
    codeFeature-specific error code.
    messageHuman-readable message that corresponds to the code
    detailsArray of objects containing detailed data about the error
    details.@typeType of data in details. Currently, the only type available is CauseInfo.
    The details under CauseInfo are for readability and debugging purposes. The value can change between software releases. To avoid your scripts breaking between releases, don’t parse the values in details.causes.
    details.causesArray of objects that convey module-level error data
    details.causes.moduleFeature-specific module that reported the error
    details.causes.codeModule-level error code.
    details.causes.descriptionDetails about the error, from the feature-specific module.

    Error Codes

    The API response XML contains a status field and an error field. These are the available API error codes and names:
    Error Code
    Name
    Description
    400
    Bad request
    A required parameter is missing, an illegal parameter value is used.
    403
    Forbidden
    Authentication or authorization errors including invalid key or insufficient admin access rights. Learn how to Generate an API Key Certificate.
    1
    Unknown command
    The specific config or operational command is not recognized.
    2-5
    Internal errors
    Check with technical support when seeing these errors.
    6
    Bad Xpath
    The xpath specified in one or more attributes of the command is invalid. Check the API browser for proper xpath values.
    7
    Object not present
    Object specified by the xpath is not present. For example, entry[@name='value'] where no object with name 'value' is present.
    8
    Object not unique
    For commands that operate on a single object, the specified object is not unique.
    10
    Reference count not zero
    Object cannot be deleted as there are other objects that refer to it. For example, address object still in use in policy.
    11
    Internal error
    Check with technical support when seeing these errors.
    12
    Invalid object
    Xpath or element values provided are not complete.
    13
    Object not found
    Object presented in the request could not be found.
    14
    Operation not possible
    Operation is allowed but not possible in this case. For example, moving a rule up one position when it is already at the top.
    15
    Operation denied
    Operation is allowed. For example, Admin not allowed to delete own account, Running a command that is not allowed on a passive device.
    16
    Unauthorized
    The API role does not have access rights to run this query.
    17
    Invalid command
    Invalid command or parameters.
    18
    Malformed command
    The XML is malformed.
    19-20
    Success
    Command completed successfully.
    21
    Internal error
    Check with technical support when seeing these errors.
    22
    Session timed out
    The session for this query timed out.

    © 2025 Palo Alto Networks, Inc. All rights reserved.