Our next-gen architecture is built to help you make sense of your ever-growing data Watch a 4-min demo video!

Back to All Docs

TCO Optimizer API TCO Optimizer API

Last Updated: May. 31, 2022

This guide will help you use our TCO API to define, query, and manage your TCO’s Policy Criteria and Policy Overrides.

For more information about TCO capabilities, see TCO: Optimize your Total Logging Cost of Ownership

[Video Tutorial]

Usage

Please follow these steps to start using the Coralogix TCO API:

First, make sure to select the correct API endpoint for your Account region

Cluster RegionBase API Endpoint
Europe (.com)https://api.coralogix.com/api/v1/external/tco/
US (.us)https://api.coralogix.us/api/v1/external/tco/
India (.in)https://api.app.coralogix.in/api/v1/external/tco/
Sweden (.eu2.)https://api.eu2.coralogix.com/api/v1/external/tco/
Singapore (sg.com)https://api.coralogixsg.com/api/v1/external/tco/

Use the Alerts, Rules, and Tags API Key as the Bearer token.
(Click your account’s icon on the top-right of the Coralogix UI, followed by “Settings”, and “API Access” on the left, [If you have not yet generated the key, please click “GENERATE NEW API KEY”]. Copy the key from here).

The following TCO API calls are supported:

  • Policy Criteria
    • Get all policies
      • URL – Base_API_Endpoint/policies
    • Get policy
      • URL – Base_API_Endpoint/policies/POLICYID
    • Create policy
      • URL – Base_API_Endpoint/policies
    • Update policy
      • URL – Base_API_Endpoint/policies/POLICYID
    • Reorder policies
      • URL – Base_API_Endpoint/policies/reorder
    • Delete policy
      • URL – Base_API_Endpoint/policies/POLICYID
  • Policy Overrides
    • Get override
      • URL – Base_API_Endpoin/overrides/OVERRIDEID
    • Get overrides
      • URL – Base_API_Endpoin/overrides
    • Get overrides with filter
      • URL – Base_API_Endpoint/overrides?subsystemName=subName&applicationName=appName
    • Create override
      • URL – Base_API_Endpoint/overrides
    • Create overrides bulk
      • URL – Base_API_Endpoint/overrides/bulk
    • Update override
      • URL – Base_API_Endpoin/overrides/OVERRIDEID
    • Update overrides bulk
      • URL – Base_API_Endpoint/overrides/bulk
    • Delete override
      • URL – Base_API_Endpoin/overrides/OVERRIDEID
    • Delete overrides bulk
      • URL – Base_API_Endpoint/overrides/bulk

Examples

Note: In the following examples, I am using Europe-based URLs for my requests since my account/team URL ends with .com. If your account/team URL ends with .us or .in you will need to modify the requests endpoints.

Note: The following set of requests contains severities (Policies), severity (Policy overrides) fields that contain numbers. Those numbers symbolize log severity: 1-debug, 2-verbose, 3-info, 4-warning, 5-error, 6-critical.

Policy Criteria

*** Create a new Policy Criterion ***

This example creates a Policy for application names that start with prod (e.g. prod, production, prod-eu) and subsystem names equal to web or mobile. The policy sets the priority for DEBUG, VERBOSE, INFO logs to medium.

Note: applicationName.type/subsystemName.type can be one of the following: “Starts With”, “Is”,  “Is Not”, “Includes”

Request:

curl --location --request POST 'https://api.coralogix.com/api/v1/external/tco/policies' \
--header 'Authorization: Bearer xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx' \
--header 'Content-Type: application/json' \
--data-raw ' {"name": "Policy Creation test","priority": "medium","severities": [1,2,3],"applicationName": {"type": "Starts With","rule": "prod"},"subsystemName": {"type": "Is","rule": ["web","mobile"]}}'

Response:

{
    "name": "Policy Creation test",
    "enabled": true,
    "priority": "medium",
    "order": 1,
    "applicationName": {
        "type": "Starts With",
        "rule": "prod"
    },
    "subsystemName": {
        "type": "Is",
        "rule": [
            "web",
            "mobile"
        ]
    },
    "severities": [
        1,
        2,
        3
    ]
}

Status Codes: 200.

*** Update a Policy Criterion ***

This example updates the name and severity selection for the Policy we created.

Note:

  • applicationName.type/subsystemName.type can be one of the following: “Starts With”, “Is”,  “Is Not”, “Includes”.
  • The body must include the policy name, priority, applicationName, subsystemName, and severities even when updating the name of the policy only.

Request:

curl --location --request PUT 'https://api.coralogix.com/api/v1/external/tco/policies/POLICYID' \
--header 'Authorization: Bearer xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx' \
--header 'Content-Type: application/json' \
--data-raw ' {"name": "Policy Creation test - updated","priority": "medium","severities": [1,2],"applicationName": {"type": "Starts With","rule": "prod"},"subsystemName": {"type": "Is","rule": ["web","mobile"]}}'

Response:

{
    "name": "Policy Creation test - updated",
    "enabled": true,
    "priority": "medium",
    "order": 1,
    "applicationName": {
        "type": "Starts With",
        "rule": "prod"
    },
    "subsystemName": {
        "type": "Is",
        "rule": [
            "web",
            "mobile"
        ]
    },
    "severities": [
        1,
        2
    ]
}

Status Codes: 200.

*** Reorder Policies ***

This example changes policies’ order.

Note:

  • The body only includes an array with the POLICYIDs. The first element in the array will be set as top policy and so on.

Request:

curl –location –request PUT ‘https://api.coralogix.com/api/v1/external/tco/policies/reorder’ \ –header ‘Authorization: Bearer xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx’ \ –header ‘Content-Type: application/json’ \ –data-raw ‘[“0743219a-fe78-4401-9e1b-97be5cb2cfce”,”677f51f2-c4c7-4088-8ea7-abf3bbcc52a4″]’

Response:

[
    {
        "id": "0743219a-fe78-4401-9e1b-97be5cb2cfce",
        "order": 1
    },
    {
        "id": "677f51f2-c4c7-4088-8ea7-abf3bbcc52a4",
        "order": 2
    }
]

Status Codes: 200.

*** Get Policy ***

This example lists a specific policy.

Request:

curl –location –request GET ‘https://api.coralogix.com/api/v1/external/tco/policies/POLICYID‘ \ –header ‘Authorization: Bearer xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx’ \ –header ‘Content-Type: application/json’ \ –data-raw ”

Response:

{
    "name": "Policy Creation test - updated",
    "enabled": true,
    "priority": "medium",
    "order": 1,
    "subsystemName": {
        "type": "Is",
        "rule": [
            "web",
            "mobile"
        ]
    },
    "severities": [
        1,
        2,
        3
    ],
    "applicationName": {
        "type": "Starts With",
        "rule": "prod"
    }
}

Status Codes: 200.

*** Get Policies ***

This example lists all existing policies.

Request:

curl –location –request GET ‘https://api.coralogix.com/api/v1/external/tco/policies’ \ –header ‘Authorization: Bearer xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx’ \ –header ‘Content-Type: application/json’ \ –data-raw ”

Response:

[
    {
        "name": "Policy Creation test",
        "priority": "medium",
        "order": 1,
        "subsystemName": {
            "type": "Is",
            "rule": [
                "web",
                "mobile"
            ]
        },
        "severities": [
            1,
            2,
            3
        ],
        "applicationName": {
            "type": "Starts With",
            "rule": "prod"
        }
    },
    {
        "name": "Policy Creation test - updated",
        "priority": "medium",
        "order": 2,
        "subsystemName": {
            "type": "Is",
            "rule": [
                "web",
                "mobile"
            ]
        },
        "severities": [
            1,
            2
        ],
        "applicationName": {
            "type": "Starts With",
            "rule": "prod"
        }
    }
]

Status Codes: 200.

*** Delete Policy ***

This example deletes an existing policy.

Request:

curl –location –request DELETE ‘https://api.coralogix.com/api/v1/external/tco/policies/POLICYID‘ \ –header ‘Authorization: Bearer xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx’ \ –header ‘Content-Type: application/json’ \ –data-raw ”

Response:

{
    "message": "deleted policy with id POLICYID",
    "id": "POLICYID"
}

Status Codes: 200.

Policy Overrides

*** Create a new Policy Override ***

This example creates a Policy Override for application name dev and subsystem name metrics DEBUG logs and sets the priority to medium.

Request:

curl –location –request POST ‘https://api.coralogix.com/api/v1/external/tco/overrides’ \ –header ‘Authorization: Bearer xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx’ \ –header ‘Content-Type: application/json’ \ –data-raw ‘{“applicationName”: “dev”,”subsystemName”: “metrics”,”severity”: 1,”priority”: “medium”}’

Response:

{
    "applicationName": "dev",
    "subsystemName": "metrics",
    "severity": 1,
    "priority": "medium"
}

Status Codes: 200.

*** Create a Bulk Policy Override ***

This example creates a Policy Override for application name dev and subsystem name metrics logs and sets the priority for all severities classes to medium.

Request:

curl --location --request POST 'https://api.coralogix.com/api/v1/external/tco/overrides/bulk' \
--header 'Authorization: Bearer xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx' \
--header 'Content-Type: application/json' \
--data-raw '[{"applicationName": "dev","subsystemName": "metrics","severity": 1,"priority": "medium"},{"applicationName": "dev","subsystemName": "metrics","severity": 2,"priority": "medium"},{"applicationName": "dev","subsystemName": "metrics","severity": 3,"priority": "medium"},{"applicationName": "dev","subsystemName": "metrics","severity": 4,"priority": "medium"},{"applicationName": "dev","subsystemName": "metrics","severity": 5,"priority": "medium"},{"applicationName": "dev","subsystemName": "metrics","severity": 6,"priority": "medium"}]'

Response:

[
    {
        "status": 200,
        "override": {
            "applicationName": "dev",
            "subsystemName": "metrics",
            "severity": 1,
            "priority": "medium"
        }
    },
    {
        "status": 200,
        "override": {
            "applicationName": "dev",
            "subsystemName": "metrics",
            "severity": 2,
            "priority": "medium"
        }
    },
    {
        "status": 200,
        "override": {
            "applicationName": "dev",
            "subsystemName": "metrics",
            "severity": 3,
            "priority": "medium"
        }
    },
    {
        "status": 200,
        "override": {
            "applicationName": "dev",
            "subsystemName": "metrics",
            "severity": 4,
            "priority": "medium"
        }
    },
    {
        "status": 200,
        "override": {
            "applicationName": "dev",
            "subsystemName": "metrics",
            "severity": 5,
            "priority": "medium"
        }
    },
    {
        "status": 200,
        "override": {
            "applicationName": "dev",
            "subsystemName": "metrics",
            "severity": 6,
            "priority": "medium"
        }
    }
]

Status Codes: 200.

*** Update a Policy Override ***

This example updates a Policy Override for application name dev and subsystem name metrics DEBUG logs and updates the priority to low.

Request:

curl --location --request PUT 'https://api.coralogix.com/api/v1/external/tco/overrides/OVERRIDEID' \
--header 'Authorization: Bearer xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx' \
--header 'Content-Type: application/json' \
--data-raw '{"priority": "low","severity": 1,"applicationName": "dev","subsystemName": "metrics"}'

Response:

{
    "priority": "low",
    "severity": 1,
    "applicationName": "dev",
    "subsystemName": "metrics"
}

Status Codes: 200.

*** Update a Bulk Policy Override ***

This example updates a Policy Override for application name dev and subsystem name metrics logs and sets the priority for all severities classes to low.

Request:

curl --location --request PUT 'https://api.coralogix.com/api/v1/external/tco/overrides/bulk' \
--header 'Authorization: Bearer xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx' \
--header 'Content-Type: application/json' \
--data-raw '[{"id": "327f8448-05db-11ec-a5ad-0616c20b31c7","applicationName": "dev","subsystemName": "metrics","severity": 1,"priority": "low"},{"id": "3280e53b-05db-11ec-a5ad-0616c20b31c7","applicationName": "dev","subsystemName": "metrics","severity": 2,"priority": "low"},{"id": "3282542c-05db-11ec-a5ad-0616c20b31c7","applicationName": "dev","subsystemName": "metrics","severity": 3,"priority": "low"},{"id": "32864222-05db-11ec-a5ad-0616c20b31c7","applicationName": "dev","subsystemName": "metrics","severity": 4,"priority": "low"},{"id": "3287dab6-05db-11ec-a5ad-0616c20b31c7","applicationName": "dev","subsystemName": "metrics","severity": 5,"priority": "low"},{"id": "32892d2d-05db-11ec-a5ad-0616c20b31c7",applicationName": "dev","subsystemName": "metrics","severity": 6,"priority": "low"}]'

Response:

[
    {
        "status": 200,
        "override": {
            "applicationName": "dev",
            "subsystemName": "metrics",
            "severity": 1,
            "priority": "low"
        }
    },
    {
        "status": 200,
        "override": {
            "applicationName": "dev",
            "subsystemName": "metrics",
            "severity": 2,
            "priority": "low"
        }
    },
    {
        "status": 200,
        "override": {
            "applicationName": "dev",
            "subsystemName": "metrics",
            "severity": 3,
            "priority": "low"
        }
    },
    {
        "status": 200,
        "override": {
            "applicationName": "dev",
            "subsystemName": "metrics",
            "severity": 4,
            "priority": "low"
        }
    },
    {
        "status": 200,
        "override": {
            "applicationName": "dev",
            "subsystemName": "metrics",
            "severity": 5,
            "priority": "low"
        }
    },
    {
        "status": 200,
        "override": {
            "applicationName": "dev",
            "subsystemName": "metrics",
            "severity": 6,
            "priority": "low"
        }
    }
]

Status Codes: 200.

*** Get Policy Override ***

This example lists a specific policy override.

Request:

curl --location --request GET 'https://api.coralogix.com/api/v1/external/tco/overrides/OVERRIDEID' \
--header 'Authorization: Bearer xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx'

Response:

{
    "id": "327f8448-05db-11ec-a5ad-0616c20b31c7",
    "name": "dev|metrics|DEBUG",
    "priority": "low",
    "severity": 1,
    "applicationName": "dev",
    "subsystemName": "metrics"
}

Status Codes: 200.

*** Get Policy Overrides ***

This example lists all existing policy overrides.

Request:

curl --location --request GET 'https://api.coralogix.com/api/v1/external/tco/overrides' \
--header 'Authorization: Bearer xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx'

*** Get Policy Overrides with Filter ***

This example lists all existing policy overrides for application name dev and subsystem name metrics.

Request:

curl --location --request GET 'https://api.coralogix.com/api/v1/external/tco/overrides?subsystemName=metrics&applicationName=dev' \
--header 'Authorization: Bearer xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx'

Response:

[
    {
        "status": 200,
        "override": {
            "applicationName": "dev",
            "subsystemName": "metrics",
            "severity": 1,
            "priority": "low"
        }
    },
    {
        "status": 200,
        "override": {
            "applicationName": "dev",
            "subsystemName": "metrics",
            "severity": 2,
            "priority": "low"
        }
    },
    {
        "status": 200,
        "override": {
            "applicationName": "dev",
            "subsystemName": "metrics",
            "severity": 3,
            "priority": "low"
        }
    },
    {
        "status": 200,
        "override": {
            "applicationName": "dev",
            "subsystemName": "metrics",
            "severity": 4,
            "priority": "low"
        }
    },
    {
        "status": 200,
        "override": {
            "applicationName": "dev",
            "subsystemName": "metrics",
            "severity": 5,
            "priority": "low"
        }
    },
    {
        "status": 200,
        "override": {
            "applicationName": "dev",
            "subsystemName": "metrics",
            "severity": 6,
            "priority": "low"
        }
    }
]

Status Codes: 200.

*** Delete Policy Override ***

This example deletes an existing policy override.

Request:

curl --location --request DELETE 'https://api.coralogix.com/api/v1/external/tco/overrides/OVERRIDEID' \
--header 'Authorization: Bearer xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx' \
--data-raw ''

*** Delete Bulk Policy Override ***

This example deletes an existing bulk policy override.

Request:

curl --location --request DELETE 'https://api.coralogix.com/api/v1/external/tco/overrides/bulk' \
--header 'Authorization: Bearer xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx' \
--header 'Content-Type: application/json' \
--data-raw '[{"id": "327f8448-05db-11ec-a5ad-0616c20b31c7","priority": "low","severity": 1,"applicationName": "dev","subsystemName": "metrics"},{"id": "3280e53b-05db-11ec-a5ad-0616c20b31c7","priority": "low","severity": 2,"applicationName": "dev","subsystemName": "metrics"},{"id": "3282542c-05db-11ec-a5ad-0616c20b31c7","priority": "low","severity": 3,"applicationName": "dev","subsystemName": "metrics"},{"id": "32864222-05db-11ec-a5ad-0616c20b31c7","priority": "low","severity": 4,"applicationName": "dev","subsystemName": "metrics"},{"id": "32892d2d-05db-11ec-a5ad-0616c20b31c7","priority": "low","severity": 6,"applicationName": "dev","subsystemName": "metrics"}]'

That’s it, you are good to go!

For any assistance, or if you would like to receive a ready-to-go postman library containing all these requests, please reach out to Coralogix support ([email protected]) or via Intercom.

On this page