Modify Custom Property

Last modified on August 24, 2020

To change the name or possible values of a custom property, send a PATCH request to /properties/{id} where {id} is the property ID.

Request URL

PATCH https://api.alertsite.com/api/v3/properties/{id}

Authentication

The request must include the Authorization header containing a user’s access token:

Authorization: Bearer ACCESS_TOKEN

See Authentication for more information.

Request body

The request body is a JSON object containing the new name or values (or both) for the custom property.

The values list replaces all possible values of a property. This means that to add new values, you must send back the values list containing both the old and new values. Each value is defined by id and name. New values should be sent with id=0.

As an example, consider a property named Environment with three possible values, Production, Staging, and Development. The property data returned by GET /properties/{id} would look like this:

{
  "id": 120,
  "name": "Environment",
  "values": [
    {
      "id": 58,
      "name": "Production"
    },
    {
      "id": 60,
      "name": "Staging"
    },
    {
      "id": 62,
      "name": "Development"
    }
  ]
}

Below are some payload examples for the PATCH request:

Rename the property

Rename all values

Add values

Delete values

Response body

If successful, the operation returns HTTP status 200 with the property ID as a string:

{
  "id": "120"
}

Error responses have a non-200 status code and include the errors list:

{
  "errors": [
    {
      "code": 404,
      "message": "Record not found"
    }
  ]
}

Try it out

Click here to test this operation in AlertSite’s interactive API console.

Code examples

cURL

Rename the property with ID 120:

cURL (Windows)

curl -X PATCH https://api.alertsite.com/api/v3/properties/120
  -H "Authorization: Bearer ACCESS_TOKEN"
  -d "{\"name\": \"env\"}"


Note: New lines are added for readability.
The actual command should be one continuous line.

cURL (bash)

curl -X PATCH https://api.alertsite.com/api/v3/properties/120 \
  -H 'Authorization: Bearer ACCESS_TOKEN' \
  -d '{"name": "env"}'

Python

This code renames the Environment property to env:

Python

# Python 3.5+
import requests  # Requests library http://docs.python-requests.org
import json

baseUrl = 'https://api.alertsite.com/api/v3'
username = 'demo@example.com'  # Replace with your AlertSite login email
password = 'pa55w0rd'          # Replace with your AlertSite password
property_name = 'Environment'
new_name = 'env'

# Log in
payload = {'username': username, 'password': password}
r = requests.post(baseUrl + '/access-tokens', data=json.dumps(payload), headers={'Content-Type': 'application/json'})
token = r.json()['access_token']
headers = {'Authorization': 'Bearer ' + token}

# Get property ID by property name
r = requests.get(baseUrl + '/properties?select=id,name', headers=headers)
for prop in r.json()['results']:
    if prop['name'] == property_name:
        property_id = prop['id']
        break
else:
    print('Property named "{}" was not found.'.format(property_name))
    quit()

# Rename the property
payload = {'name': new_name}
headers = {
    'Authorization': 'Bearer ' + token,
    'Content-Type': 'application/json'
}
r = requests.patch(baseUrl + '/properties/{}'.format(property_id), data=json.dumps(payload), headers=headers)

if r.ok:
    print('Successfully renamed property "{}" (# {}) to "{}".'.format(property_name, property_id, new_name))
else:
    print('Could not rename property "{}". The following error(s) occurred:'.format(property_name), *r.json()['errors'], sep='\n')

See Also

Custom Properties Operations

Highlight search results