---
title: "Create an annotation"
method: POST
path: "/api/v1/annotations"
tags: ["Annotations"]
---

# Create an annotation

`POST /api/v1/annotations`

## Request

- Base URL: `https://numonic.ai`
- URL: `https://numonic.ai/api/v1/annotations`
- Auth: API key in header `x-api-key`

Create a new annotation on a workflow node with content type, visibility, and audit trail.

## Headers

- `X-Tenant-ID` string, uuid, required: Target tenant UUID. Required when API key has access to multiple tenants.

## Request body

- CreateAnnotationRequest
  - `workflow_node_id` string, required: Workflow node ID (hash key) to annotate
  - `content` string, required: Annotation text content
  - `content_type` 'text' | 'markdown' | 'json': Content format type
  - `visibility` 'private' | 'team' | 'public': Visibility level: private (author only), team (tenant), public (all)

## Response `201`

Annotation created

- SuccessMessage
  - `message` string, required: Human-readable success message

## Other responses

- `400`: Validation failed

---

[API](https://skmtc.dev/numonic/apis/numonic-api.md) · [All operations](https://skmtc.dev/numonic/apis/numonic-api/llms.txt) · [OpenAPI document](https://skmtc.dev/numonic/apis/numonic-api/revisions/6c559bef1e35?raw)