# circonus_annotation – create an annotation in circonus

- Synopsis

- Requirements

- Parameters

- Notes

- Examples

- Return Values

- Status

## Synopsis

- Create an annotation event with a given category, title and description. Optionally start, end or durations can be provided

## Requirements

The below requirements are needed on the host that executes this module.

- requests (either >= 2.0.0 for Python 3, or >= 1.0.0 for Python 2)

## Parameters

Parameter | Choices/Defaults | Comments
--- | --- | ---
api_key - / required |  | Circonus API key
category - / required |  | Annotation Category
description - / required |  | Description of annotation
duration - | Default: 0 | Duration in seconds of annotation
start - | Default: "I(now)" | Unix timestamp of event start
stop - | Default: "I(now) + I(duration)" | Unix timestamp of event end
title - / required |  | Title of annotation

## Notes

Note

- Check mode isn’t supported.

## Examples

    # Create a simple annotation event with a source, defaults to start and end time of now
    - circonus_annotation:
        api_key: XXXXXXXXXXXXXXXXX
        title: App Config Change
        description: This is a detailed description of the config change
        category: This category groups like annotations
    # Create an annotation with a duration of 5 minutes and a default start time of now
    - circonus_annotation:
        api_key: XXXXXXXXXXXXXXXXX
        title: App Config Change
        description: This is a detailed description of the config change
        category: This category groups like annotations
        duration: 300
    # Create an annotation with a start_time and end_time
    - circonus_annotation:
        api_key: XXXXXXXXXXXXXXXXX
        title: App Config Change
        description: This is a detailed description of the config change
        category: This category groups like annotations
        start_time: 1395940006
        end_time: 1395954407

## Return Values

Common return values are documented here, the following are the fields unique to this module:

Key | Returned | Description
--- | --- | ---
annotation complex | success | details about the created annotation
| _cid string | success | annotation identifier Sample: /annotation/100000
| _created integer | success | creation timestamp Sample: 1502236928
| _last_modified integer | success | last modification timestamp Sample: 1502236928
| _last_modified_by string | success | last modified by Sample: /user/1000
| category string | success | category of the created annotation Sample: alerts
| description string | success | description of the created annotation Sample: Host is down.
| rel_metrics list | success | Array of metrics related to this annotation, each metrics is a string. Sample: ['54321_kbps']
| start integer | success | timestamp, since annotation applies Sample: Host is down.
| stop string | success | timestamp, since annotation ends Sample: Host is down.
| title string | success | title of the created annotation Sample: WARNING

## Status

- This module is not guaranteed to have a backwards compatible interface. [preview]

- This module is maintained by the Ansible Community. [community]

### Authors

- Nick Harring (@NickatEpic)

Hint

If you notice any issues in this documentation, you can edit this document to improve it.