# Annotations

## Create a new annotation

> Creates a new annotation for an attestation value with a human-readable description

```json
{"openapi":"3.0.2","info":{"title":"Enclaive auth-ratls API","version":"0.0.0-0"},"servers":[{"url":"http://localhost:8200","description":"Local development server"}],"paths":{"/v1/auth/ratls/annotations":{"put":{"tags":["Annotations"],"summary":"Create a new annotation","description":"Creates a new annotation for an attestation value with a human-readable description","operationId":"createAnnotation","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AnnotationsCreate_annotationsRequest"}}}},"responses":{"200":{"description":"Annotation created successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AnnotationsCreate_annotationsResponse"}}}},"400":{"description":"Invalid request body"},"405":{"description":"Unsupported operation","content":{"application/json":{"schema":{"type":"object","properties":{"errors":{"type":"array","items":{"type":"string"}}}}}}}}}}},"components":{"schemas":{"AnnotationsCreate_annotationsRequest":{"type":"object","properties":{"created":{"type":"integer","description":"Creation timestamp, set by the plugin","format":"int64"},"key":{"type":"string","description":"Attestation value to annotate"},"value":{"type":"string","description":"Human-readable description for the attestation value"}},"required":["created","key","value"]},"AnnotationsCreate_annotationsResponse":{"type":"object","properties":{"auth":{"type":"object"},"data":{"type":"object","properties":{"created":{"type":"integer","description":"Creation timestamp, set by the plugin","format":"int64"},"key":{"type":"string","description":"Attestation value to annotate"},"value":{"type":"string","description":"Human-readable description for the attestation value"}}}}}}}}
```

## List all annotations

> Retrieves a list of all available annotations in the system

```json
{"openapi":"3.0.2","info":{"title":"Enclaive auth-ratls API","version":"0.0.0-0"},"servers":[{"url":"http://localhost:8200","description":"Local development server"}],"paths":{"/v1/auth/ratls/annotations/":{"get":{"tags":["Annotations"],"summary":"List all annotations","description":"Retrieves a list of all available annotations in the system","operationId":"listAnnotations","parameters":[{"name":"list","description":"Must be set to 'true' to retrieve the list","in":"query","schema":{"type":"string","enum":["true"]},"required":true}],"responses":{"200":{"description":"List of annotations retrieved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AnnotationsList_annotationsResponse"}}}}}}}},"components":{"schemas":{"AnnotationsList_annotationsResponse":{"type":"object","properties":{"request_id":{"type":"string"},"lease_id":{"type":"string"},"renewable":{"type":"boolean"},"lease_duration":{"type":"integer"},"data":{"type":"object","properties":{"keys":{"type":"array","items":{"type":"string"}}}},"wrap_info":{"type":"null"},"warnings":{"type":"null"},"auth":{"type":"null"}}}}}}
```

## Get annotation details

> Retrieves detailed information about a specific annotation

```json
{"openapi":"3.0.2","info":{"title":"Enclaive auth-ratls API","version":"0.0.0-0"},"servers":[{"url":"http://localhost:8200","description":"Local development server"}],"paths":{"/v1/auth/ratls/annotations/{key}":{"get":{"tags":["Annotations"],"summary":"Get annotation details","description":"Retrieves detailed information about a specific annotation","operationId":"getAnnotation","responses":{"200":{"description":"Annotation details retrieved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AnnotationsRead_annotationsKeyResponse"}}}},"400":{"description":"Annotation not found"}}}}},"components":{"schemas":{"AnnotationsRead_annotationsKeyResponse":{"type":"object","properties":{"auth":{"type":"object"},"data":{"type":"object","properties":{"created":{"type":"integer","description":"Creation timestamp, set by the plugin","format":"int64"},"key":{"type":"string","description":"Attestation value to annotate"},"value":{"type":"string","description":"Human-readable description for the attestation value"}}}}}}}}
```

## Delete an annotation

> Removes a specific annotation from the system

```json
{"openapi":"3.0.2","info":{"title":"Enclaive auth-ratls API","version":"0.0.0-0"},"servers":[{"url":"http://localhost:8200","description":"Local development server"}],"paths":{"/v1/auth/ratls/annotations/{key}":{"delete":{"tags":["Annotations"],"summary":"Delete an annotation","description":"Removes a specific annotation from the system","operationId":"deleteAnnotation","responses":{"200":{"description":"Annotation deleted successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AnnotationsDelete_Response"}}}}}}}},"components":{"schemas":{"AnnotationsDelete_Response":{"type":"object","properties":{"request_id":{"type":"string"},"lease_id":{"type":"string"},"renewable":{"type":"boolean"},"lease_duration":{"type":"integer"},"data":{"type":"object"},"wrap_info":{"type":"null"},"warnings":{"type":"null"},"auth":{"type":"null"}}}}}}
```