create-annotation

dci create-annotation [body]

Creates a new annotation.

Pass the request body as name: value arguments or pipe JSON on stdin — see Command structure.

IDs, not names

reports and labels take IDs: get them from dci list-reports and dci list-labels. timestamp is an RFC 3339 date-time and is required.

Examples

# Record what happened on a date so it shows on report charts.
dci create-annotation content: "Moved batch jobs to Spot instances", timestamp: "2026-09-01T00:00:00Z"

# Attach the annotation to specific reports and tag it with labels.
dci create-annotation content: "Reserved Instances renewed", timestamp: "2026-09-01T00:00:00Z", reports: [<report-id>], labels: [<label-id>]

# Create it from a file and capture the new ID.
dci create-annotation --output json < annotation.json | jq -r .id

# annotation.json
{"content": "Moved batch jobs to Spot instances",
 "timestamp": "2026-09-01T00:00:00Z",
 "reports": ["<report-id>"],
 "labels": ["<label-id>"]}

Request

Content-Type: application/json

Field	Type	Required	Description
content	string	yes	The content of the annotation.
timestamp	string (date-time)	yes	The date associated with the annotation.
reports	array of string		List of report IDs associated with the annotation.
labels	array of string		List of label IDs to associate with the annotation. Labels must already exist.

Raw JSON schema

{
  "required": [
    "content",
    "timestamp"
  ],
  "type": "object",
  "description": "Request body to create an annotation.",
  "properties": {
    "content": {
      "type": "string",
      "description": "The content of the annotation."
    },
    "timestamp": {
      "type": "string",
      "format": "date-time",
      "description": "The date associated with the annotation."
    },
    "reports": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "List of report IDs associated with the annotation."
    },
    "labels": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "List of label IDs to associate with the annotation. Labels must already exist."
    }
  }
}

Output

Created - Annotation created successfully.

By default dci renders the result as a table. Use --output json to get the full structure described below — see Output formats.

Field	Type	Description
id	string	The unique identifier of the annotation.
content	string	The content of the annotation.
timestamp	string (date-time)	The date associated with the annotation.
reports	array of string	List of report IDs associated with the annotation.
labels	array of object	List of labels associated with the annotation.
labels[].id	string	The unique identifier of the label.
labels[].name	string	The name of the label.
createTime	string (date-time)	The creation time of the annotation.
updateTime	string (date-time)	The time when the annotation was last updated.

Raw JSON schema

{
  "required": [
    "id",
    "content",
    "timestamp"
  ],
  "type": "object",
  "description": "Summary information about an annotation.",
  "properties": {
    "id": {
      "type": "string",
      "description": "The unique identifier of the annotation."
    },
    "content": {
      "type": "string",
      "description": "The content of the annotation."
    },
    "timestamp": {
      "type": "string",
      "format": "date-time",
      "description": "The date associated with the annotation."
    },
    "reports": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "List of report IDs associated with the annotation."
    },
    "labels": {
      "type": "array",
      "items": {
        "required": [
          "id",
          "name"
        ],
        "type": "object",
        "description": "Metadata for a label.",
        "properties": {
          "id": {
            "type": "string",
            "description": "The unique identifier of the label."
          },
          "name": {
            "type": "string",
            "description": "The name of the label."
          }
        }
      },
      "description": "List of labels associated with the annotation."
    },
    "createTime": {
      "type": "string",
      "format": "date-time",
      "description": "The creation time of the annotation."
    },
    "updateTime": {
      "type": "string",
      "format": "date-time",
      "description": "The time when the annotation was last updated."
    }
  }
}

Errors

On failure, dci prints a single error message — with a hint when one is available — and exits with a typed code your scripts can branch on. See Errors and exit codes for the full contract.

HTTP status to exit code mapping

HTTP status	Exit code	Error code	Meaning
400	30	VALIDATION_ERROR	The arguments or request body were rejected. Review the command's flags and payload.
401	10	AUTHENTICATION_FAILED	Not signed in, or the API token is invalid. Run dci login or check DCI_API_KEY.
403	11	PERMISSION_DENIED	The DoiT user or the active customer context does not have access.
404	20	RESOURCE_NOT_FOUND	The requested resource does not exist. Check the identifier argument.

Related

• get-annotation — Retrieve an annotation
• list-annotations — List annotations
• update-annotation — Update an annotation
• delete-annotation — Delete an annotation
• API reference: POST /analytics/v1/annotations

Aliases: createannotation