Presicion Policy API
Use the Precision Policy APIs to retrieve the list of all available Precision filters and policies, activate one or multiple policies, and reorder the policy filters. For each policy, retrieve the name of the policy, the Precision filters and their definitions, and the resources and their shares.
API Access Rate Limit
To know the API access limits, see Conviva API Developer Center.
API Access
To access the API use the client-based credentials, CLIENT_ID and CLIENT_SECRET, generated in Pulse from the API Management page, accessed from the Pulse Settings menu. For more details, see Pulse API Management page.
Note: To call the Precision Policy POST APIs, the API credentials must be created by Precision Admin. Otherwise, the API throws an HTTP 403 Forbidden error. To learn more about Precision Admin, contact Conviva Support (support@conviva.com).
API Endpoints
All Precision API access occurs over the following endpoints:
-
GET: To retrieve a list of Precision policies.
https://api.conviva.com/precision/v1.0/policies
-
POST: To activate one or more backup policies.
https://api.conviva.com/precision/v1.0/policies/activate
-
POST: To reorder the Precision filters.
https://api.conviva.com/precision/v1.0/policies/reorder
Common Use Cases
These use cases show examples of API calls to retrieve Precision data:
Retrieve Precision Policies
GET All Precision Policies
This GET API fetches the list of all Precision policies with details about name of the policies, filters, versions, resources, and shares. Use the is_active flag to determine whether or not a policy is active.
Sample Request
curl --request GET \
--url https://api.conviva.com/precision/v1.0/policies \Sample Response
{
"policies": [
{
"id": 135069,
"index": 1,
"filter_name": "Apple iPhone",
"filter_created": "2022-12-13T12:37:15.000Z",
"filter_text": "(Device Name EQUALS Apple iPhone)",
"versions": [
{
"created": "2022-07-12T06:38:06.000Z",
***"is_active": true,***
"id": 1328,
"name": "Policy11_Edit",
"index": 1,
"shares": [
{
"id": 8205,
"weight": 5000,
"resources": [
2096270876,
2096272047
]
}
]
}
]
}
],
"resources": [
{
"id": 2096270876,
"cdn": "TEST1",
"name": "TestCDN1",
"rules": "http://cdn1.test.com",
"details": "http://cdn1.test.com"
},
{
"id": 2096272047,
"cdn": "TEST2",
"name": "Test - Resource",
"rules": "akamai",
"details": "akamai"
}
],
"can_edit": false
}
GET Active or Inactive Precision Policies
This API fetches the active or inactive Precision policies based on the query parameter of the API call.
-
is_active = true retrieves all active Precision policies.
-
is_active = false retrieves all inactive Precision policies.
Sample Request
curl --request GET \
--url https://api.conviva.com/precision/v1.0/policies?is_active=true \Sample Response
{
"policies": [
{
"id": 135066,
"index": 1,
"filter_name": "Android Phone",
"filter_created": "2019-08-13T12:37:15.000Z",
"filter_text": "(Device Name EQUALS Android Phone)",
"versions": [
{
"created": "2023-09-09T07:37:15.000Z",
"is_active": false,
"id": 1307,
"name": "PolicyFromPortal1703 clone id 1294 clone id 1307_edited",
"shares": [
{
"id": 8332,
"weight": 8000,
"resources": [
2096270876,
2096270878
]
}
],
"index": 1
}
]
},
{
"id": 170757,
"index": 2,
"filter_name": "PolicyFilterTest_revamped",
"filter_created": "2023-02-24T10:51:26.000Z",
"filter_text": "(Country EQUALS United States)",
"versions": [
{
"created": "2023-09-09T08:16:57.000Z",
"is_active": false,
"id": 1306,
"name": "test-policy-one",
"shares": [
{
"id": 8383,
"weight": 5000,
"resources": [
2096270877,
2096270879
]
},
{
"id": 8384,
"weight": 5000,
"resources": [
2096270967
]
}
],
"index": 2
}
]
}
],
"resources": [
{
"id": 2096270876,
"cdn": "TEST1",
"name": "TestCDN1",
"rules": "http://cdn1.test.com",
"details": "http://cdn1.test.com"
},
{
"id": 2096270878,
"cdn": "TEST2",
"name": "Test - Resource",
"rules": "akamai",
"details": "akamai"
},
{
"id": 2096270877,
"cdn": "TEST3",
"name": "Test - Resource2",
"rules": "akamai",
"details": "akamai"
},
{
"id": 2096270879,
"cdn": "TEST4",
"name": "Test - Resource3",
"rules": "akamai",
"details": "akamai"
},
{
"id": 2096270967,
"cdn": "TEST5",
"name": "Test - Resource4",
"rules": "akamai",
"details": "akamai"
}
],
"can_edit": false
}
Activate Precision Policies
This POST API activates one or more inactive Precision policies of different filters on demand (without the need for scheduling) by passing the policy IDs as part of the request body. When activating a backup policy, it sets the is_active flag to true and the active policy is picked up based on the Precision filter reorder index.
Note: At any given point, each Precision filter can have only one active policy, and many inactive or backup policies. Activate the policies for a maximum of ten filters.
Activate Single Precision Policy for a Given Filter
Sample Request
curl --request POST \
--url https://api.conviva.com/precision/v1.0/policies/activate \
--header 'Content-Type: application/json' \
--data '{
"policies": [
1234
]
}Sample Response
{
"status": "success",
"successList": [
1234
],
"errorList": [],
"error": ""
}
Activate Precision Policies for Multiple Filters (one policy from each filter)
Sample Request
curl --request POST \
--url https://api.conviva.com/precision/v1.0/policies/activate \
--header 'Content-Type: application/json' \
--data '{
"policies": [
1234,
4567,
7890
]
}Sample Response
{
"status": "success",
"successList": [
1234,
4567,
7890
],
"errorList": [],
"error": ""
}
Note: Activating more than one backup policy for a filter throws a 400 Bad Request error.
Reorder Precision Filters
With this POST API, reorder the Precision policy filters by providing Precision filter IDs in the request body. Precision filters are then picked up based on their indexed order. For example, in the following request, the Precision filter with ID 106333 is assigned index=1 and takes precedence over the filter with ID 135069 whose index=2.
Note: To reorder the Precision filters, ensure the API request contains all the filter IDs available for the c3 account. Else, the API throws a 400 Bad Request error for incorrect number of filter IDs.
Sample Request
curl --request POST \
--url https://api.conviva.com/precision/v1.0/policies/reorder \
--header 'Content-Type: application/json' \
--data '{
"order": [
106333,
135069
]
}Sample Response
{
"policies": [
{
"id": 106333,
"index": 1,
"filter_name": "Apple iPad",
"filter_created": "2022-08-11T12:37:15.000Z",
"filter_text": "(Device Name EQUALS Apple iPhone)",
"versions": [
{
"created": "2022-12-19T08:59:22.000Z",
"is_active": false,
"id": 1328,
"name": "Policy11_Edit",
"index": 1,
"shares": [
{
"id": 7911,
"weight": 5000,
"resources": [
2096270876,
2096272047
]
},
{
"id": 7912,
"weight": 5000,
"resources": [
2096272047
]
}
]
}
]
},
{
"id": 135069,
"index": 2,
"filter_name": "Apple iPhone",
"filter_created": "2019-08-13T12:37:15.000Z",
"filter_text": "(Device Name EQUALS Apple iPhone)",
"versions": [
{
"created": "2022-12-19T08:59:22.000Z",
"is_active": false,
"id": 1328,
"name": "Policy11_Edit",
"index": 2,
"shares": [
{
"id": 7911,
"weight": 5000,
"resources": [
2096270876,
2096272047
]
},
{
"id": 7912,
"weight": 5000,
"resources": [
2096272047
]
}
]
}
]
}
],
"resources": [
{
"id": 2096270876,
"cdn": "TEST1",
"name": "TestCDN1",
"rules": "http://cdn1.test.com",
"details": "http://cdn1.test.com"
},
{
"id": 2096272047,
"cdn": "TEST2",
"name": "Test - Resource",
"rules": "akamai",
"details": "akamai"
}
],
"can_edit": false
}
}Error Codes
Precision APIs return the following error codes:
| Code | Description | Troubleshooting |
|---|---|---|
| 200 | Successfully retrieved Precision Policies data. | |
| 400 | Error in query parameters. | Verify the filter or Precision policy IDs in the API request. |
| This parameter is currently not supported. | Verify the query parameters provided in the API request. The API supports only is_active as the query parameter. | |
| Bad Request |
Check the API request parameters.
|
|
| 401 | Unauthorized | Check the credentials. |
| 403 | Forbidden | Ensure that the Precision APIs are activated for the c3 account, and have the edit permissions. |
| 429 | Too many requests. | Ensure that the interval between the API calls is more than one minute. |
| 500 | Internal server error. | Try again later. |