This tutorial demonstrates using the TCO Optimizer HTTP API to define, query, and manage your TCO policy overrides for logs.

Go to [this page](https://coralogix.com/docs/developer-portal/apis/tco-controls/tco-tracing-policy-grpc-api/index.md) to learn how to use the **TCO Tracing gPRC API** to define, query, and manage your [TCO policy criteria](https://coralogix.com/docs/user-guides/account-management/tco-optimizer/#policies-and-filters), used both for spans and logs.

## Base URL

Choose the https://api.\[[DOMAIN_VALUE]\]/api/v1/external/tco endpoint that corresponds to your Coralogix [domain](https://coralogix.com/docs/user-guides/account-management/account-settings/coralogix-domain/index.md) using the domain selector at the top of the page.

## Header

| Key           | Value                 |
| ------------- | --------------------- |
| Content-Type  | application/json      |
| Authorization | Bearer `<cx_api_key>` |

### API key

To use the TCO Optimizer API you need to [create](https://coralogix.com/docs/user-guides/account-management/api-keys/api-keys/index.md) a personal or team API key. It’s recommended to use permission presets, as they are automatically updated with all relevant permissions. Alternatively, you can manually add individual permissions.

| Preset      | Action                                                                                                                                                        | Description                                                                                                                                                 |
| ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
| TCOPolicies | `LOGS.TCO:READPOLICIES` `LOGS.TCO:UPDATEPOLICIES` `SPANS.TCO:READPOLICIES` `SPANS.TCO:UPDATEPOLICIES` `METRICS.TCO:READPOLICIES` `METRICS.TCO:UPDATEPOLICIES` | View Logs TCO Policies Manage Logs TCO Policies View Tracing TCO Policies Manage Tracing TCO Policies View Metrics TCO Policies Manage Metrics TCO Policies |

## Usage

### Severity options

| Name     | Value |
| -------- | ----- |
| debug    | 1     |
| verbose  | 2     |
| info     | 3     |
| warning  | 4     |
| error    | 5     |
| critical | 6     |

### Priority options

| Name   | Value  |
| ------ | ------ |
| block  | block  |
| low    | low    |
| medium | medium |
| high   | high   |

## TCO override

Configuring a TCO override replaces the TCO policy for the specified application-subsystem-severity combination, including any associated Archive Retention Tags. In these cases, the Archive Retention Tag is overridden and reverts to the `default` tag.

### Impact

This behavior directly impacts S3 lifecycle policies that depend on retention tags. If the tag is overridden to the `default`, lifecycle policies associated with specific tags, like 'Revenue,' may not be applied as intended, potentially resulting in unintended data deletion.

### Prevention

If you manage S3 Lifecycle Policies based on Archive Retention Tags, review and adjust overrides to prevent unintended data deletion.

**Example**

- TCO override is not in use: Retention Tag = `revenue`, Lifecycle Policy transitions data to Glacier after 30 days and deletes it from Glacier after 1 year.
- TCO override is in use: Retention Tag = `default`, Lifecycle Policy expires data after 60 days (if set to `default`).

## Supported endpoints

### Get all policy overrides

Note

This endpoint returns only policy overrides. If a policy is applied but not explicitly overridden, it will not appear in the response. If no overrides exist, the response will be empty.

**GET** /overrides

**Route example:** https://api.\[[DOMAIN_VALUE]\]/api/v1/external/tco/overrides

**Response example:**

```json
[
    {
        "id": "dd361b69-89c7-11ec-a5ad-0616c20b31c7",
        "name": "default|recommendationservice|INFO",
        "priority": "high",
        "severity": 3,
        "applicationName": "default",
        "subsystemName": "recommendationservice"
    },
    {
        "id": "61d551af-8f96-11ec-8bfb-02dd69f0920d",
        "name": "default|checkoutservice|DEBUG",
        "priority": "high",
        "severity": 1,
        "applicationName": "default",
        "subsystemName": "checkoutservice"
    }
]
```

### Get single policy override by ID

**GET** /overrides/{id}

**Route example:** https://api.\[[DOMAIN_VALUE]\]/api/v1/external/tco/overrides/972f6b98-343c-11ee-ac29-061115d0c307

**Response example:**

```json
{
    "id": "dd361b69-89c7-11ec-a5ad-0616c20b31c7",
    "name": "default|recommendationservice|INFO",
    "priority": "high",
    "severity": 3,
    "applicationName": "default",
    "subsystemName": "recommendationservice"
}
```

### Create single policy override

**POST** /overrides

**Route example:** https://api.\[[DOMAIN_VALUE]\]/api/v1/external/tco/overrides

**Request example:**

```json
{
    "priority": "high",
    "severity": 3,
    "applicationName": "default",
    "subsystemName": "blablabla123"
}
```

**Response example**:

```json
{
    "priority": "high",
    "severity": 3,
    "applicationName": "default",
    "subsystemName": "blablabla123",
    "id": "972f6b98-343c-11ee-ac29-061115d0c307"
}
```

### Create multiple policy overrides

**POST** /overrides/bulk

**Route example:** https://api.\[[DOMAIN_VALUE]\]/api/v1/external/tco/overrides/bulk

**Request example:**

```json
[
    {
        "priority": "high",
        "severity": 3,
        "applicationName": "default",
        "subsystemName": "blablabla1234"
    },
    {
        "priority": "high",
        "severity": 3,
        "applicationName": "default",
        "subsystemName": "blablabla12345"
    }
]
```

**Response example**:

```json
[
    {
        "status": 200,
        "override": {
            "priority": "high",
            "severity": 3,
            "applicationName": "default",
            "subsystemName": "blablabla1234",
            "id": "2c42a7aa-343d-11ee-ac29-061115d0c307"
        }
    },
    {
        "status": 200,
        "override": {
            "priority": "high",
            "severity": 3,
            "applicationName": "default",
            "subsystemName": "blablabla12345",
            "id": "2c53d05f-343d-11ee-ac29-061115d0c307"
        }
    }
]
```

### Update multiple policy overrides

**PUT** /overrides/bulk

**Route example:** https://api.\[[DOMAIN_VALUE]\]/api/v1/external/tco/overrides/bulk

**Request example:**

```json
[
    {
        "id": "2c42a7aa-343d-11ee-ac29-061115d0c307",
        "name": "default|blablabla1234|INFO",
        "priority": "high",
        "severity": 3,
        "applicationName": "default",
        "subsystemName": "blablabla1234"
    },
    {
        "id": "2c53d05f-343d-11ee-ac29-061115d0c307",
        "name": "default|blablabla12345|INFO",
        "priority": "high",
        "severity": 3,
        "applicationName": "default",
        "subsystemName": "blablabla12345"
    }
]
```

**Response example**:

```json
[
    {
        "status": 200,
        "override": {
            "name": "default|blablabla1234|INFO",
            "priority": "high",
            "severity": 3,
            "applicationName": "default",
            "subsystemName": "blablabla1234",
            "id": "2c42a7aa-343d-11ee-ac29-061115d0c307"
        }
    },
    {
        "status": 200,
        "override": {
            "name": "default|blablabla12345|INFO",
            "priority": "high",
            "severity": 3,
            "applicationName": "default",
            "subsystemName": "blablabla12345",
            "id": "2c53d05f-343d-11ee-ac29-061115d0c307"
        }
    }
]
```

### Delete single policy override

**DELETE** /overrides/{id}

**Route example:** https://api.\[[DOMAIN_VALUE]\]/api/v1/external/tco/overrides/2c53d05f-343d-11ee-ac29-061115d0c307

**Response example:**

```json
{
    "id": "2c53d05f-343d-11ee-ac29-061115d0c307"
}
```

### Delete multiple policy overrides

**DELETE** /overrides/bulk

**Route example:** https://api.\[[DOMAIN_VALUE]\]/api/v1/external/tco/overrides/bulk

**Request example:**

```json
[
    {
        "id": "2c42a7aa-343d-11ee-ac29-061115d0c307"
    }
]
```

**Response example**:

```json
[
    {
        "status": 200,
        "override": {
            "id": "2c42a7aa-343d-11ee-ac29-061115d0c307"
        }
    }
]
```

### Get all TCO policies

**GET** /policies

**Route example:** https://api.\[[DOMAIN_VALUE]\]/api/v1/external/tco/policies

**Request example:**

```text
curl --location 'https://api.[[DOMAIN_VALUE]]/api/v1/external/tco/policies' \
--header 'Authorization: Bearer xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx'
```

### Create TCO policy

**POST** /policies

**Route example:** https://api.\[[DOMAIN_VALUE]\]/api/v1/external/tco/policies

**Request example:**

```text
curl --location 'https://api.[[DOMAIN_VALUE]]/api/v1/external/tco/policies' \
--header 'Authorization: Bearer xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx' \
--header 'Content-Type: application/json' \
--data '{
    "name": "Policy block subsystem",
    "priority": "block",
    "severities": [],
    "applicationName": {},
    "subsystemName": {
        "type": "Is",
        "rule": [
            "system_logs",
            "lambda_logs"
        ]
    }
}'
```

### Reorder policies

Sets the order of policies in the provided order. The list must contain the list of all the policies IDs in the expected new order.

**POST** /policies/reorder

**Route example:** https://api.\[[DOMAIN_VALUE]\]/api/v1/external/tco/policies/reorder

**Request example:**

```text
curl --location --request PUT 'https://api.[[DOMAIN_VALUE]]/api/v1/external/tco/policies/reorder' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx' \
--data '[
    "eed91808-1094-4d07-adab-17855b449888",
    "95cfa816-354a-412c-80f5-378ce33a4454"
]'
```

### Delete TCO policy

**DELETE** /policies/{tco_policy_id}

**Route example:** https://api.\[[DOMAIN_VALUE]\]/api/v1/external/tco/policies/90503f12-c291-4bbf-b437-5022f39d258d

**Request example:**

```text
curl --location --request DELETE 'https://api.[[DOMAIN_VALUE]]/api/v1/external/tco/policies/90503f12-c291-4bbf-b437-5022f39d258d' \
--header 'Authorization: Bearer xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx'
```

## Additional resources

|                     |                                                                                                                                                                                                                              |
| ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Documentation       | [TCO Optimizer](https://coralogix.com/docs/user-guides/account-management/tco-optimizer/index.md) [TCO Tracing gPRC API](https://coralogix.com/docs/developer-portal/apis/tco-controls/tco-tracing-policy-grpc-api/index.md) |
| Coralogix Endpoints | [Coralogix Endpoints](https://coralogix.com/docs/integrations/coralogix-endpoints/index.md)                                                                                                                                  |