> ## Documentation Index > Fetch the complete documentation index at: https://docs.siftstack.com/llms.txt > Use this file to discover all available pages before exploring further. # annotations > sift/annotations/v1/annotations.proto ## Services *RPC methods exposed by this API.* ### AnnotationService | Method | Request | Response | Description | | :------------------------ | :-------------------------------------------------------------------- | :---------------------------------------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | CreateAnnotation | [CreateAnnotationRequest](#createannotationrequest) | [CreateAnnotationResponse](#createannotationresponse) | Creates an annotation. | | DeleteAnnotation | [DeleteAnnotationRequest](#deleteannotationrequest) | [DeleteAnnotationResponse](#deleteannotationresponse) | Delete Annotation is deprecated. Use ArchiveAnnotation instead. Calling this will archive the annotation, which should be done using the ArchiveAnnotation method or the UpdateAnnotation method with the delete date set to a non-null value. Restoring an annotation can be done using the UnarchiveAnnotation method or by calling UpdateAnnotation with the delete date set to a null value. | | ArchiveAnnotation | [ArchiveAnnotationRequest](#archiveannotationrequest) | [ArchiveAnnotationResponse](#archiveannotationresponse) | Archives an annotation. | | UnarchiveAnnotation | [UnarchiveAnnotationRequest](#unarchiveannotationrequest) | [UnarchiveAnnotationResponse](#unarchiveannotationresponse) | Unarchives an annotation. | | BatchDeleteAnnotations | [BatchDeleteAnnotationsRequest](#batchdeleteannotationsrequest) | [BatchDeleteAnnotationsResponse](#batchdeleteannotationsresponse) | BatchDeleteAnnotations is deprecated. Use BatchArchiveAnnotations instead. BatchDeleteAnnotations will archive the annotations specified in the request. These can be restored by calling UnarchiveAnnotation or UpdateAnnotation with the delete date set to a null value. | | BatchArchiveAnnotations | [BatchArchiveAnnotationsRequest](#batcharchiveannotationsrequest) | [BatchArchiveAnnotationsResponse](#batcharchiveannotationsresponse) | Batch archives annotations. | | BatchUnarchiveAnnotations | [BatchUnarchiveAnnotationsRequest](#batchunarchiveannotationsrequest) | [BatchUnarchiveAnnotationsResponse](#batchunarchiveannotationsresponse) | Batch unarchives annotations. | | ListAnnotations | [ListAnnotationsRequest](#listannotationsrequest) | [ListAnnotationsResponse](#listannotationsresponse) | Retrieves annotations using an optional filter. | | GetAnnotation | [GetAnnotationRequest](#getannotationrequest) | [GetAnnotationResponse](#getannotationresponse) | Retrieves an annotation | | UpdateAnnotation | [UpdateAnnotationRequest](#updateannotationrequest) | [UpdateAnnotationResponse](#updateannotationresponse) | Updates an existing annotation using using the list of fields specified in `update_mask`. | ## Messages *Data models used across requests/responses.* ### Annotation | Field | Type | Label | Description | | :---------------------------------------- | :---------------------------------------------------------------- | :------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------- | | annotation\_id | string | | | | name | string | | | | description | string | | | | start\_time | google.protobuf.Timestamp | | | | end\_time | google.protobuf.Timestamp | | | | created\_by\_user\_id | string | | | | modified\_by\_user\_id | string | | | | created\_date | google.protobuf.Timestamp | | | | modified\_date | google.protobuf.Timestamp | | | | run\_id | string | optional | | | state | [AnnotationState](#annotationstate) | optional | | | organization\_id | string | | | | assigned\_to\_user\_id | string | | | | annotation\_type | [AnnotationType](#annotationtype) | | | | tags | string | repeated | | | legend\_config | string | optional | | | created\_by\_condition\_id | string | optional | | | created\_by\_rule\_condition\_version\_id | string | optional | | | report\_rule\_version\_id | string | optional | | | pending | bool | | An annotation is pending if it is part of an ongoing violation of a rule condition. The `end_time` of a pending annotation might be set, but is not yet finalized. | | assigned\_to\_user | [sift.common.type.v1.User](#sift-common-type-v1-user) | | | | deleted\_date | google.protobuf.Timestamp | | **Deprecated.** | | linked\_channels | [AnnotationLinkedChannel](#annotationlinkedchannel) | repeated | | | asset\_ids | string | repeated | | | metadata | [sift.metadata.v1.MetadataValue](#sift-metadata-v1-metadatavalue) | repeated | | | archived\_date | google.protobuf.Timestamp | | | | is\_archived | bool | | is\_archived is a inferred from when archived\_date is not null | | batched\_triggers | int32 | | | | is\_noisy\_rule | bool | | | ### AnnotationLinkedCalculatedChannel | Field | Type | Label | Description | | :------------------------------- | :----- | :---- | :---------- | | calculated\_channel\_version\_id | string | | | ### AnnotationLinkedChannel | Field | Type | Label | Description | | :------------------------------ | :---------------------------------------------------------------------------------- | :---- | :---------- | | oneof type. channel | [AnnotationLinkedChannelsChannel](#annotationlinkedchannelschannel) | | | | oneof type. bit\_field\_element | [AnnotationLinkedChannelsBitFieldElement](#annotationlinkedchannelsbitfieldelement) | | | | oneof type. calculated\_channel | [AnnotationLinkedCalculatedChannel](#annotationlinkedcalculatedchannel) | | | ### AnnotationLinkedChannelsBitFieldElement | Field | Type | Label | Description | | :--------------- | :----- | :---- | :---------- | | channel\_id | string | | | | bit\_field\_name | string | | | ### AnnotationLinkedChannelsChannel | Field | Type | Label | Description | | :---------- | :----- | :---- | :---------- | | channel\_id | string | | | ### ArchiveAnnotationRequest The request for a call to `AnnotationService_ArchiveAnnotation`. | Field | Type | Label | Description | | :------------- | :----- | :---- | :---------- | | annotation\_id | string | | | ### ArchiveAnnotationResponse The response of a call to `AnnotationService_ArchiveAnnotation`. | Field | Type | Label | Description | | :--------- | :------------------------ | :---- | :---------- | | annotation | [Annotation](#annotation) | | | ### BatchArchiveAnnotationsRequest The request for a call to `AnnotationService_BatchArchiveAnnotations`. | Field | Type | Label | Description | | :-------------- | :----- | :------- | :---------------------------------- | | annotation\_ids | string | repeated | Limit of 1000 annotations per batch | ### BatchArchiveAnnotationsResponse The response of a call to `AnnotationService_BatchArchiveAnnotations`. | Field | Type | Label | Description | | :---------- | :------------------------ | :------- | :---------- | | annotations | [Annotation](#annotation) | repeated | | ### BatchDeleteAnnotationsRequest | Field | Type | Label | Description | | :-------------- | :----- | :------- | :---------------------------------- | | annotation\_ids | string | repeated | Limit of 1000 annotations per batch | ### BatchDeleteAnnotationsResponse *This message has no fields.* ### BatchUnarchiveAnnotationsRequest The request for a call to `AnnotationService_BatchUnarchiveAnnotations`. | Field | Type | Label | Description | | :-------------- | :----- | :------- | :---------------------------------- | | annotation\_ids | string | repeated | Limit of 1000 annotations per batch | ### BatchUnarchiveAnnotationsResponse The response of a call to `AnnotationService_BatchUnarchiveAnnotations`. | Field | Type | Label | Description | | :---------- | :------------------------ | :------- | :---------- | | annotations | [Annotation](#annotation) | repeated | | ### CreateAnnotationRequest The request for a call to `AnnotationService_CreateAnnotation` to create a new annotation. At least 1 asset, tag, or channel must be specified. | Field | Type | Label | Description | | :---------------------------------------- | :---------------------------------------------------------------- | :------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------- | | name | string | | The name assigned to the new annotation. | | description | string | | A short description about the new annotation. | | start\_time | google.protobuf.Timestamp | | When the annotation starts. | | end\_time | google.protobuf.Timestamp | | When the annotation ends. | | assets | string | repeated | The names of the assets to associate with this annotation. | | linked\_channels | [AnnotationLinkedChannel](#annotationlinkedchannel) | repeated | The channels to associate with this annotation. | | tags | string | repeated | The names of the tags to associate with this annotation. | | run\_id | string | optional | The ID of the run that this annotation is associated with. | | assign\_to\_user\_id | string | optional | The ID of the user that this annotation is assigned to. | | organization\_id | string | | The organization associated with this annotation. An organization ID is only required if the user belongs to multiple organizations. | | state | [AnnotationState](#annotationstate) | optional | The state of the annotation. If an annotation has an `annotation_type` of `ANNOTATION_TYPE_PHASE`, then state must be unset, otherwise an error will be returned. | | annotation\_type | [AnnotationType](#annotationtype) | | The type of the annotation. | | created\_by\_condition\_id | string | optional | The ID of the rule condition that created this annotation. | | legend\_config | string | optional | A JSON string containing the axes configuration of the annotation's linked channels. | | created\_by\_rule\_condition\_version\_id | string | optional | The ID of the rule condition version that created this annotation. | | metadata | [sift.metadata.v1.MetadataValue](#sift-metadata-v1-metadatavalue) | repeated | The metadata associated with this annotation. | ### CreateAnnotationResponse The result of a call to `AnnotationService_CreateAnnotation`. | Field | Type | Label | Description | | :--------- | :------------------------ | :---- | :---------- | | annotation | [Annotation](#annotation) | | | ### DeleteAnnotationRequest The request for a call to `AnnotationService_DeleteAnnotation`. | Field | Type | Label | Description | | :------------- | :----- | :---- | :---------- | | annotation\_id | string | | | ### DeleteAnnotationResponse The response of a call to `AnnotationService_DeleteAnnotation`. *This message has no fields.* ### GetAnnotationRequest The request for a call to `AnnotationService_GetAnnotation`. | Field | Type | Label | Description | | :------------- | :----- | :---- | :---------- | | annotation\_id | string | | | ### GetAnnotationResponse The response of a call to `AnnotationService_GetAnnotation`. | Field | Type | Label | Description | | :--------- | :------------------------ | :---- | :---------- | | annotation | [Annotation](#annotation) | | | ### ListAnnotationsRequest The request for a call to `AnnotationService_ListAnnotations` to retrieve annotations. | Field | Type | Label | Description | | :--------------- | :----- | :---- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | page\_size | uint32 | | The maximum number of annotations to return. The service may return fewer than this value. If unspecified, at most 50 annotations will be returned. The maximum value is 1000; values above 1000 will be coerced to 1000. Optional. | | page\_token | string | | A page token, received from a previous `ListAnnotations` call. Provide this to retrieve the subsequent page. When paginating, all other parameters provided to `ListAnnotations` must match the call that provided the page token. Optional. | | filter | string | | A [Common Expression Language (CEL)](https://github.com/google/cel-spec) filter string. Available fields to filter by are `annotation_id`, `start_time`, `end_time`, `created_date`, `modified_date`, `run_id`, `name`, `description`, `state`, `created_by_user_id`, `created_by_rule_condition_version_id`, `rule_id`, `annotation_type`, `tag_name`, `report_id`, `asset_id`, `asset_name`, `pending`, `assignee`, `campaign_reports`, `metadata`, `archived_date`, and `is_archived`. For further information about how to use CELs, please refer to [this guide](https://github.com/google/cel-spec/blob/master/doc/langdef.md#standard-definitions). For more information about the fields used for filtering, please refer to [this definition](/docs/api/grpc/protocol-buffers/annotations#annotation). Optional. | | organization\_id | string | | This field is only required if your user belongs to multiple organizations. | | order\_by | string | | How to order the retrieved annotations. Formatted as a comma-separated string i.e. "FIELD\_NAME\[ desc],...". Available fields to order\_by are `created_date`, `modified_date`, `start_time`, `end_time`, `name`, and `description`. If left empty, items are ordered by `created_date` in descending order (newest-first). For more information about the format of this field, read [this](https://google.aip.dev/132#ordering) Example: "created\_date desc,modified\_date" | ### ListAnnotationsResponse The result of a call to `AnnotationService_ListAnnotations`. | Field | Type | Label | Description | | :---------------- | :------------------------ | :------- | :------------------------------------------------------------------------------------------------ | | annotations | [Annotation](#annotation) | repeated | | | next\_page\_token | string | | Oops, we skipped to index 5! No reason for that; the indices between aren't reserved or anything. | ### UnarchiveAnnotationRequest The request for a call to `AnnotationService_UnarchiveAnnotation`. | Field | Type | Label | Description | | :------------- | :----- | :---- | :---------- | | annotation\_id | string | | | ### UnarchiveAnnotationResponse The response of a call to `AnnotationService_UnarchiveAnnotation`. | Field | Type | Label | Description | | :--------- | :------------------------ | :---- | :---------- | | annotation | [Annotation](#annotation) | | | ### UpdateAnnotationRequest The request for a call to `AnnotationService_UpdateAnnotation` to update an annotation. | Field | Type | Label | Description | | :----------- | :------------------------------------------------------ | :---- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | annotation | [Annotation](#annotation) | | The annotation to update. | | update\_mask | [google.protobuf.FieldMask](#google-protobuf-fieldmask) | | The list of fields to be updated. The fields available to be updated are `name`, `description`, `start_time`, `end_time`, `assigned_to_user_id`, `state`, `tags`, `legend_config`, `linked_channels`, and `metadata`. Important Note: if `tags` is specified in the update mask and `annotation.tags` is an empty list then all associated tags on the annotation will be removed. | ### UpdateAnnotationResponse The response of a call to `AnnotationService_UpdateAnnotation`. | Field | Type | Label | Description | | :--------- | :------------------------ | :---- | :---------- | | annotation | [Annotation](#annotation) | | | ## Enums *Allowed constant values used in message fields.* ### AnnotationState | Name | Number | Description | | :----------------------------- | :----- | :---------- | | ANNOTATION\_STATE\_UNSPECIFIED | 0 | | | ANNOTATION\_STATE\_OPEN | 1 | | | ANNOTATION\_STATE\_FLAGGED | 2 | | | ANNOTATION\_STATE\_RESOLVED | 3 | | ### AnnotationType | Name | Number | Description | | :----------------------------- | :----- | :---------- | | ANNOTATION\_TYPE\_UNSPECIFIED | 0 | | | ANNOTATION\_TYPE\_DATA\_REVIEW | 1 | | | ANNOTATION\_TYPE\_PHASE | 2 | |