# Target List

A target list is a list of either domains or IPs which can be used as a building block to create rules or prioritize a group of targets. It's very helpful for organizing rule sets on Firewalla.

A given target list is either owned by one Firewalla box or the MSP that manages it. Target Lists that are owned by the MSP can be shared across all Firewallas within the MSP but are only available to MSP users. Target Lists that are owned by a Firewalla box cannot be shared across other Firewalla boxes, but can still be accessed by the MSP.

# Get All Target Lists

This API gets all target lists within the MSP. The target lists that are returned are either managed by the MSP directly (global) or by boxes under the management of the MSP. If no target list is found, an empty array is returned.

GET https://msp_domain/v2/target-lists

Name	Value
Authorization required	Personal access token

Response

200 Success

A JSON array of Target List

[
    {
        "id": "TL-00000000-0000-0000-0000-000000000000",
        "name": "A Simple Target List",
        "owner": "global",
        "targets": [
            "foo.com",
            "bar.net"
        ],
        "category": "edu",
        "notes": "This is a simple target list",
        "lastUpdated": 1664373339.857
    }
]

401 Permission Denied

Examples

// https://github.com/axios/axios
const axios = require("axios");

// Change these variables to what you have
const msp_domain = process.env.msp_domain || "mydomain.firewalla.net";
const token = process.env.token || "your_personal_access_token";

axios({
    method: "get",
    url: `https://${msp_domain}/v2/target-lists`,
    headers: {
        "Authorization": `Token ${token}`
    }
}).then(res => {
    console.log(res.data);
})

curl --request GET  \
--url "https://${msp_domain}/v2/target-lists" \
--header "Authorization: Token ${your_personal_access_token}"

# Get A Target List

This API gets a specific target list within the MSP.

GET https://msp_domain/v2/target-lists/:id

Name	Value
Authorization required	Personal access token

Name	Value
id	target list id

Response

200 Success

A JSON representation of Target List

{
    "id": "TL-00000000-0000-0000-0000-000000000000",
    "name": "A Simple Target List",
    "owner": "global",
    "count": 2,
    "targets": [
        "foo.com",
        "bar.net"
    ],
    "category": "edu",
    "notes": "This is a simple target list",
    "lastUpdated": 1664373339.857
}

401 Permission Denied

Examples

// https://github.com/axios/axios
const axios = require("axios");

// Change these variables to what you have
const msp_domain = process.env.msp_domain || "mydomain.firewalla.net";
const token = process.env.token || "your_personal_access_token";
const id = process.env.id || "TL-00000000-0000-0000-0000-000000000000";

axios({
    method: "get",
    url: `https://${msp_domain}/v2/target-lists/${id}`,
    headers: {
        "Authorization": `Token ${token}`
    }
}).then(res => {
    console.log(res.data);
})

curl --request GET  \
--url "https://${msp_domain}/v2/target-lists/${id}" \
--header "Authorization: Token ${your_personal_access_token}"

# Create A Target List

This API creates a new target list for either the whole MSP or for one box that's under MSP management.

POST https://msp_domain/v2/target-lists

Name	Value
Authorization required	Personal access token

A Target List without id and lastUpdated

{
  "name": "A Simple Target List",
  "targets": ["foo.com", "bar.net"],
  "owner": "global",
  "category": "edu",
  "notes": "This is a simple target list"
}

Response

200 Success

A JSON representation of Target List

{
    "id": "TL-00000000-0000-0000-0000-000000000000",
    "name": "A Simple Target List",
    "owner": "global",
    "targets": [
        "foo.com",
        "bar.net"
    ],
    "category": "edu",
    "notes": "This is a simple target list",
    "lastUpdated": 1664373339.857
}

400 Bad Request

401 Permission Denied

Examples

// https://github.com/axios/axios
const axios = require("axios");

// Change these variables to what you have
const msp_domain = process.env.msp_domain || "mydomain.firewalla.net";
const token = process.env.token || "your_personal_access_token";
const targetList = {
    "name": "A Simple Target List",
    "targets": [ "foo.com", "bar.com" ],
    "category": "edu",
    "notes": "This is a simple target list"
}

axios({
    method: "post",
    url: `https://${msp_domain}/v2/target-lists`,
    headers: {
        "Authorization": `Token ${token}`,
        "Content-Type": "application/json"
    },
    data: targetList
}).then(res => {
    console.log(res.data);
})

curl --request POST  \
--url "https://${msp_domain}/v2/target-lists" \
--header "Authorization: Token ${your_personal_access_token}" \
--header "Content-Type: application/json" \
--data '{
    "name":"A Simple Target List",
    "targets": ["foo.com","bar.net"],
    "category":"edu",
    "notes":"This is a simple target list"
}'

# Update A Target List

This API updates an existing target list. Note that immutable properties should not be supplied in the body and are ignored by the server.

PATCH https://msp_domain/v2/target-lists/:id

Name	Value
Authorization required	Personal access token

Name	Value
id required	target list id

A JSON representation of Target List

{
    "name": "An updated target list",
    "targets": [
        "fu.com",
        "baz.net"
    ],
    "notes": "This is an updated target list"
}

Response

200 Success

A JSON representation of Target List

{
    "id": "TL-00000000-0000-0000-0000-000000000000",
    "name": "An updated target list",
    "owner": "global",
    "targets": [
        "fu.com",
        "baz.net"
    ],
    "category": "edu",
    "notes": "This is an updated target list",
    "lastUpdated": 1664373339.857
}

400 Bad Request

401 Permission Denied

404 Not Found

Examples

// https://github.com/axios/axios
const axios = require("axios");

// Change these variables to what you have
const msp_domain = process.env.msp_domain || "mydomain.firewalla.net";
const token = process.env.token || "your_personal_access_token";
const id = process.env.id || "TL-00000000-0000-0000-0000-000000000000"
const targetList = {
    "name": "An updated target list",
    "targets": [ "fu.com", "baz.net" ],
    "notes": "This is an updated target list"
}

axios({
    method: 'patch',
    url: `https://${msp_domain}/v2/target-lists/${id}`,
    headers: {
        "Authorization": `Token ${token}`,
        "Content-Type": "application/json"
    },
    data: targetList
}).then(res => {
    console.log(res.data);
})

curl --request PATCH  \
--url "https://${msp_domain}/v2/target-lists/${id}" \
--header "Authorization: Token ${your_personal_access_token}" \
--header "Content-Type: application/json" \
--data '{
    "id": "TL-00000000-0000-0000-0000-000000000000",
    "name": "An updated target list",
    "targets": [ "fu.com", "baz.net" ],
    "notes": "This is an updated target list"
}'

# Delete A Target List

This API deletes an existing target list

DELETE https://msp_domain/v2/target-lists/:id

Name	Value
Authorization required	Personal access token

Name	Value
id required	target list id

Response

200 Success

401 Permission Denied

404 Not Found

Examples

// https://github.com/axios/axios
const axios = require("axios");

// Change these three configurations to what you need
const msp_domain = process.env.msp_domain || "mydomain.firewalla.net";
const token = process.env.token || "your_personal_access_token";
const id = process.env.id || "TL-00000000-0000-0000-0000-000000000000"

axios({
    method: "delete",
    url: `https://${msp_domain}/v2/target-lists/${id}`,
    headers: {
        Authorization: `Token ${token}`
    }
}).then(res => {
    console.log(res.data);
})

curl --request DELETE  \
--url "https://${msp_domain}/v2/target-lists/${id}" \
--header "Authorization: Token ${your_personal_access_token}"