---
updatedAt: 2026-06-12T14:47:10.000Z
agentTools:
  projectIndex: https://docs.formant.io/llms.txt
---

# Get one

Get an existing annotation by annotation ID.
Resource: annotations
Authorized roles: viewer, device

# OpenAPI definition

```json
{
  "components": {
    "schemas": {
      "NotificationMuted": {
        "properties": {
          "start": {
            "format": "date-time",
            "type": "string",
            "description": "Mute start time (inclusive)."
          },
          "end": {
            "format": "date-time",
            "type": "string",
            "description": "Mute end time (exclusive)."
          }
        },
        "type": "object",
        "required": [
          "start",
          "end"
        ],
        "nullable": true
      },
      "FocusedDatapoint": {
        "properties": {
          "streamName": {
            "type": "string"
          },
          "time": {
            "format": "date-time",
            "type": "string"
          }
        },
        "type": "object",
        "required": [
          "streamName",
          "time"
        ]
      },
      "Annotation": {
        "properties": {
          "type": {
            "type": "string",
            "enum": [
              "triggered-event",
              "datapoint-event",
              "device-online",
              "device-offline",
              "intervention-request",
              "intervention-response",
              "teleop-session-record",
              "port-forwarding-session-record",
              "command-request",
              "command-response",
              "command-delivery",
              "custom",
              "comment",
              "system",
              "annotation",
              "task-summary",
              "stateful"
            ]
          },
          "editedAt": {
            "format": "date-time",
            "type": "string",
            "nullable": true,
            "description": "Internal use only, ignore."
          },
          "userId": {
            "format": "uuid",
            "type": "string",
            "nullable": true,
            "description": "User associated with this annotation."
          },
          "annotationTemplateId": {
            "format": "uuid",
            "type": "string",
            "nullable": true,
            "description": "If you want to create this annotation from an existing annotation template, enter its ID here."
          },
          "taggedUsers": {
            "title": "TagSets",
            "description": "A map of tag keys to an array of values",
            "type": "object",
            "additionalProperties": {
              "type": "array",
              "items": {
                "type": "string"
              }
            },
            "nullable": true
          },
          "publishedTo": {},
          "note": {
            "maxLength": 1024,
            "type": "string",
            "nullable": true,
            "description": "Description of this annotation."
          },
          "focusedDataPoints": {
            "items": {
              "$ref": "#/components/schemas/FocusedDatapoint"
            },
            "type": "array",
            "maxItems": 100,
            "minItems": 0,
            "nullable": true
          },
          "id": {
            "format": "uuid",
            "type": "string"
          },
          "createdAt": {
            "format": "date-time",
            "type": "string"
          },
          "updatedAt": {
            "format": "date-time",
            "type": "string"
          },
          "tags": {
            "type": "object",
            "additionalProperties": {
              "type": "string"
            }
          },
          "organizationId": {
            "format": "uuid",
            "type": "string",
            "description": "ID of the organization in which to create this new event."
          },
          "externalId": {
            "type": "string",
            "nullable": true,
            "description": "External ID of this event."
          },
          "time": {
            "format": "date-time",
            "type": "string",
            "description": "Start time of the data range relevant to this event."
          },
          "endTime": {
            "format": "date-time",
            "type": "string",
            "nullable": true,
            "description": "End time of the data range relevant to this event."
          },
          "parentId": {
            "format": "uuid",
            "type": "string",
            "nullable": true,
            "description": "If this custom event is related to another event, you can add the ID of that parent event here."
          },
          "metadata": {
            "type": "object",
            "additionalProperties": {
              "type": "string"
            },
            "description": "User-customizable metadata associated with this event in key-value pair format."
          },
          "message": {
            "maxLength": 1024,
            "type": "string",
            "description": "Message of this event. Must match the `message` field in the Formant UI when configuring a custom event."
          },
          "viewed": {
            "type": "boolean"
          },
          "deviceId": {
            "format": "uuid",
            "type": "string",
            "nullable": true,
            "description": "ID of the device relevant to this event."
          },
          "streamName": {
            "type": "string",
            "nullable": true
          },
          "streamType": {
            "type": "string",
            "enum": [
              "bitset",
              "localization",
              "point cloud",
              "location",
              "file",
              "health",
              "transform tree",
              "battery",
              "video",
              "numeric set",
              "json",
              "image",
              "numeric",
              "text"
            ],
            "nullable": true
          },
          "eventTriggerId": {
            "format": "uuid",
            "type": "string",
            "nullable": true
          },
          "notificationEnabled": {
            "type": "boolean",
            "description": "Set this to `true` to enable notifications for this event."
          },
          "notificationMuted": {
            "$ref": "#/components/schemas/NotificationMuted",
            "nullable": true,
            "description": "Set this to temporarily mute notifications for this event."
          },
          "deletedAt": {
            "nullable": true,
            "format": "date-time",
            "type": "string"
          }
        },
        "type": "object",
        "required": [
          "time"
        ]
      }
    },
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "JWT"
      }
    }
  },
  "info": {
    "title": "Formant admin-api",
    "version": "1.357.8"
  },
  "openapi": "3.0.0",
  "paths": {
    "/annotations/{id}": {
      "get": {
        "operationId": "AnnotationController.getOne",
        "parameters": [
          {
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Annotation"
                }
              }
            },
            "description": ""
          }
        },
        "summary": "Get one",
        "tags": [
          "Annotation"
        ],
        "description": "Get an existing annotation by annotation ID.\nResource: annotations\nAuthorized roles: viewer, device",
        "security": [
          {
            "bearerAuth": []
          }
        ]
      }
    }
  },
  "servers": [
    {
      "url": "https://api.formant.io/v1/admin"
    }
  ]
}
```