> ## Documentation Index > Fetch the complete documentation index at: https://docs.notifuse.com/llms.txt > Use this file to discover all available pages before exploring further. # Create an annotation > Creates a manual annotation. Requires the web_analytics write permission. `source` is always stored as `manual` and `source_id` is always empty: only the platform writes automatic rows, so there is no way to attach a caller-supplied key to one. **This endpoint is therefore not idempotent** — a retried call (a CI job re-running a deploy marker, for instance) writes a second annotation. De-duplicate on the caller's side, or delete the extra row. Omitted `color` and `timezone` are filled in server-side: the default colour, and the workspace timezone falling back to UTC. ## OpenAPI ````yaml /openapi.json post /api/annotations.create openapi: 3.0.3 info: title: Notifuse API description: API for Notifuse - a transactional email and newsletter management platform version: 1.0.0 contact: name: Notifuse Support url: https://www.notifuse.com/support email: hello@notifuse.com servers: - url: https://{notifuseDomain} description: Customer-specific Notifuse API server variables: notifuseDomain: description: Your unique Notifuse domain default: demo.notifuse.com security: [] paths: /api/annotations.create: post: tags: - Web Analytics summary: Create an annotation description: > Creates a manual annotation. Requires the web_analytics write permission. `source` is always stored as `manual` and `source_id` is always empty: only the platform writes automatic rows, so there is no way to attach a caller-supplied key to one. **This endpoint is therefore not idempotent** — a retried call (a CI job re-running a deploy marker, for instance) writes a second annotation. De-duplicate on the caller's side, or delete the extra row. Omitted `color` and `timezone` are filled in server-side: the default colour, and the workspace timezone falling back to UTC. operationId: createAnnotation requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateAnnotationRequest' responses: '201': description: Annotation created content: application/json: schema: $ref: '#/components/schemas/AnnotationResponse' '400': description: >- Bad request - unparseable body, validation failed, or the instance runs in demo mode, where every mutating endpoint is closed. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: invalidBody: value: error: Invalid request body missingTitle: value: error: 'invalid request: title is required' invalidColor: value: error: 'invalid request: color must be a hex color like #3b82f6' systemSource: value: error: 'invalid request: source must be "manual"' demoMode: value: error: This operation is not allowed in demo mode '401': description: Unauthorized - invalid or missing authentication token content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '403': description: Forbidden - missing required permission content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: >- Insufficient permissions: write access to web analytics required '500': description: Internal server error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: Failed to create annotation security: - BearerAuth: [] components: schemas: CreateAnnotationRequest: type: object required: - workspace_id - annotated_at - title properties: workspace_id: type: string example: ws_1234567890 annotated_at: type: string format: date-time description: The moment to mark, as an RFC3339 instant. example: '2026-08-15T09:00:00Z' timezone: type: string description: >- IANA timezone the moment was entered in, kept for display. Defaults to the workspace timezone, then to UTC. example: Asia/Tokyo title: type: string maxLength: 100 example: Pricing page redesign description: type: string maxLength: 500 example: Rolled out to all visitors after the A/B test. color: type: string pattern: ^#[0-9A-Fa-f]{6}$ default: '#3b82f6' example: '#3b82f6' source: type: string enum: - manual description: >- Only `manual` is accepted. Sending `broadcast` is rejected rather than quietly downgraded: it would be claiming the slot of an automatic row. default: manual AnnotationResponse: type: object properties: annotation: $ref: '#/components/schemas/Annotation' ErrorResponse: type: object properties: error: type: string description: Error message required: - error Annotation: type: object required: - id - annotated_at - timezone - title - color - source - created_at - updated_at properties: id: type: string description: Server-generated identifier (a UUID with its dashes removed). example: 3f2504e04f8911d39a0c0305e82c3301 annotated_at: type: string format: date-time description: The moment the annotation marks, as a real instant. example: '2026-08-15T09:00:00Z' timezone: type: string description: >- IANA timezone the moment was entered in. This is display intent only — annotated_at already fixes the instant, and filtering never uses this field. It is what lets "9am in Tokyo" render back as 9am instead of the reader's local equivalent. example: Asia/Tokyo title: type: string maxLength: 100 description: Counted in characters, not bytes. example: Pricing page redesign description: type: string maxLength: 500 description: Optional longer note. Counted in characters, not bytes. example: Rolled out to all visitors after the A/B test. color: type: string pattern: ^#[0-9A-Fa-f]{6}$ description: Six-digit hex colour used for the marker on the charts. example: '#3b82f6' source: type: string enum: - manual - broadcast description: >- Who wrote the row. `manual` is anything typed by an operator or posted to this API; `broadcast` rows are written automatically when a broadcast starts sending. There is deliberately no API source — see the note on annotations.create. example: manual source_id: type: string description: >- The entity that caused an automatic annotation (a broadcast id today). Always absent on manual rows, and never settable through the API. An annotation outlives the entity it points at: deleting a broadcast leaves its annotation, because the send did happen. example: bcast_1234567890 created_at: type: string format: date-time updated_at: type: string format: date-time securitySchemes: BearerAuth: type: http scheme: bearer description: API token for authentication ````