# Alert Context Tags

## Overview <a href="#overview" id="overview"></a>

Use these API operations to interact with [alert context tags](https://docs.panther.com/alerts/alert-management#context-tags) in Panther.

To call the API, see the [How to use the Panther REST API](https://docs.panther.com/panther-developer-workflows/api/rest#how-to-use-the-panther-rest-api) instructions—including [directions for how to invoke it directly from this documentation page](https://docs.panther.com/panther-developer-workflows/api/rest#step-3-invoke-the-panther-rest-api).

## Required permissions <a href="#required-permissions" id="required-permissions"></a>

* For `GET` operations, your API token must have the `Read Alerts` permission.
* For `POST`, `DELETE`, and `PATCH` operations, your API token must have the `Manage Alerts` permission.

## Operations

## List all context tags

> Returns all context tags, both managed (system-defined) and custom (user-defined)

```json
{"openapi":"3.0.3","info":{"title":"Panther REST API","version":"1.0"},"tags":[{"name":"contexttag","description":"The context tag API handles all operations for alert context tags"}],"servers":[{"url":"https://{api_host}","variables":{"api_host":{"default":"your-api-host"}}}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","name":"X-API-Key","in":"header"}},"schemas":{"contexttagAPI.ListContextTagsResp":{"type":"object","properties":{"next":{"type":"string","description":"Pagination token for the next page of results"},"results":{"type":"array","items":{"$ref":"#/components/schemas/contexttagAPI.ContextTag"},"description":"The list of context tags"}},"description":"Response for listing context tags","required":["results"]},"contexttagAPI.ContextTag":{"type":"object","properties":{"category":{"type":"string","description":"The category of the tag"},"managed":{"type":"boolean","description":"Whether the tag is managed by Panther"},"tag":{"type":"string","description":"The tag value","pattern":"^[a-z0-9_-]+$","minLength":1,"maxLength":30}},"description":"A context tag that can be applied to alerts","required":["tag","category","managed"]},"contexttagAPI.BadRequestError":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}},"paths":{"/alert-context-tags":{"get":{"tags":["contexttag"],"summary":"List all context tags","description":"Returns all context tags, both managed (system-defined) and custom (user-defined)","operationId":"contexttag#list","parameters":[{"name":"cursor","in":"query","description":"Pagination token from a previous request","allowEmptyValue":true,"schema":{"type":"string","description":"Pagination token from a previous request"}},{"name":"limit","in":"query","description":"Maximum number of results to return","allowEmptyValue":true,"schema":{"type":"integer","description":"Maximum number of results to return","default":2000,"format":"int64","minimum":1,"maximum":2000}},{"name":"managed","in":"query","description":"Filter by tag type: true for managed tags only, false for custom tags only, omit for all tags","allowEmptyValue":true,"schema":{"type":"boolean","description":"Filter by tag type: true for managed tags only, false for custom tags only, omit for all tags"}}],"responses":{"200":{"description":"OK response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/contexttagAPI.ListContextTagsResp"}}}},"400":{"description":"bad_request: Bad Request response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/contexttagAPI.BadRequestError"}}}}}}}}}
```

## Create a custom context tag

> Creates a new custom context tag. Returns 409 Conflict if the tag already exists.

```json
{"openapi":"3.0.3","info":{"title":"Panther REST API","version":"1.0"},"tags":[{"name":"contexttag","description":"The context tag API handles all operations for alert context tags"}],"servers":[{"url":"https://{api_host}","variables":{"api_host":{"default":"your-api-host"}}}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","name":"X-API-Key","in":"header"}},"schemas":{"contexttagAPI.CreateContextTagReq":{"type":"object","properties":{"tag":{"type":"string","description":"The tag value to create","pattern":"^[a-z0-9_-]+$","minLength":1,"maxLength":30}},"description":"Request to create a custom context tag","required":["tag"]},"contexttagAPI.BadRequestError":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]},"contexttagAPI.ExistsError":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}},"paths":{"/alert-context-tags":{"post":{"tags":["contexttag"],"summary":"Create a custom context tag","description":"Creates a new custom context tag. Returns 409 Conflict if the tag already exists.","operationId":"contexttag#create","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contexttagAPI.CreateContextTagReq"}}}},"responses":{"201":{"description":"Created response."},"400":{"description":"bad_request: Bad Request response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/contexttagAPI.BadRequestError"}}}},"409":{"description":"exists: Conflict response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/contexttagAPI.ExistsError"}}}}}}}}}
```

## Delete a custom context tag

> Deletes a custom context tag. Managed tags cannot be deleted.

```json
{"openapi":"3.0.3","info":{"title":"Panther REST API","version":"1.0"},"tags":[{"name":"contexttag","description":"The context tag API handles all operations for alert context tags"}],"servers":[{"url":"https://{api_host}","variables":{"api_host":{"default":"your-api-host"}}}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","name":"X-API-Key","in":"header"}},"schemas":{"contexttagAPI.BadRequestError":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}},"paths":{"/alert-context-tags/{tag}":{"delete":{"tags":["contexttag"],"summary":"Delete a custom context tag","description":"Deletes a custom context tag. Managed tags cannot be deleted.","operationId":"contexttag#delete","parameters":[{"name":"tag","in":"path","description":"The tag value to delete","required":true,"schema":{"type":"string","description":"The tag value to delete","pattern":"^[a-z0-9_-]+$","minLength":1,"maxLength":30}}],"responses":{"204":{"description":"No Content response."},"400":{"description":"bad_request: Bad Request response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/contexttagAPI.BadRequestError"}}}}}}}}}
```

## Rename a custom context tag

> Atomically renames a custom context tag. Returns 404 if the tag doesn't exist, 409 if the target tag already exists.

```json
{"openapi":"3.0.3","info":{"title":"Panther REST API","version":"1.0"},"tags":[{"name":"contexttag","description":"The context tag API handles all operations for alert context tags"}],"servers":[{"url":"https://{api_host}","variables":{"api_host":{"default":"your-api-host"}}}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","name":"X-API-Key","in":"header"}},"schemas":{"contexttagAPI.UpdateContextTagReq":{"type":"object","properties":{"tag":{"type":"string","description":"The new tag value","pattern":"^[a-z0-9_-]+$","minLength":1,"maxLength":30}},"description":"Request to rename a custom context tag","required":["tag"]},"contexttagAPI.BadRequestError":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]},"contexttagAPI.NotFoundError":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]},"contexttagAPI.ExistsError":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}},"paths":{"/alert-context-tags/{tag}":{"patch":{"tags":["contexttag"],"summary":"Rename a custom context tag","description":"Atomically renames a custom context tag. Returns 404 if the tag doesn't exist, 409 if the target tag already exists.","operationId":"contexttag#update","parameters":[{"name":"tag","in":"path","description":"The current tag value to rename","required":true,"schema":{"type":"string","description":"The current tag value to rename","pattern":"^[a-z0-9_-]+$","minLength":1,"maxLength":30}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contexttagAPI.UpdateContextTagReq"}}}},"responses":{"204":{"description":"No Content response."},"400":{"description":"bad_request: Bad Request response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/contexttagAPI.BadRequestError"}}}},"404":{"description":"not_found: Not Found response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/contexttagAPI.NotFoundError"}}}},"409":{"description":"exists: Conflict response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/contexttagAPI.ExistsError"}}}}}}}}}
```