diff --git a/.github/agents/api-backward-compatibility-specialist.md b/.github/agents/api-backward-compatibility-specialist.md
index e9d6a1449c..9486623c8e 100644
--- a/.github/agents/api-backward-compatibility-specialist.md
+++ b/.github/agents/api-backward-compatibility-specialist.md
@@ -50,6 +50,103 @@ Protect FlexMeasures users and integrators by ensuring API changes are backwards
 - [ ] **Type changes**: Field type changes are breaking
 - [ ] **Validation**: Stricter validation is breaking, looser is safe
 - [ ] **Marshmallow schemas**: Check schema version compatibility
+- [ ] **Response schema completeness**: Verify all response schemas include required fields (see Response Schema Patterns below)
+
+#### Response Schema Patterns
+
+**Always use separate input and output schemas for API endpoints**
+
+Input schemas validate request data; output schemas control response data. These should be separate classes even if they share fields.
+
+**Checklist for Response Schema Completeness**:
+
+- [ ] **ID field**: Response must include `id` field for created/updated resources
+- [ ] **Source field**: If resource has a source, include it in response
+- [ ] **Audit fields**: Consider including `created_at`, `updated_at` if relevant
+- [ ] **All identifying fields**: Include fields clients need to reference the resource
+- [ ] **Idempotency support**: Provide enough data for clients to detect duplicates
+
+**Session 2026-02-10 Case Study** (Annotation API):
+
+**Problem**: Initial annotation API used single schema for input and output:
+
+```python
+class AnnotationSchema(Schema):
+    content = fields.String(required=True)
+    start = AwareDateTimeField(required=True, format="iso")
+    # Missing: id field in output
+```
+
+**Issue**: Clients couldn't retrieve the `id` of created annotations, breaking idempotency checks.
+
+**Wrong Fix**: Separate input and output schemas:
+
+```python
+class AnnotationSchema(Schema):
+    """Input schema - validates request data"""
+    content = fields.String(required=True)
+    start = AwareDateTimeField(required=True, format="iso")
+
+class AnnotationResponseSchema(Schema):
+    """Output schema - includes all data clients need"""
+    id = fields.Integer(required=True)
+    content = fields.String(required=True)
+    start = AwareDateTimeField(required=True, format="iso")
+```
+
+**Right Fix**:
+
+```python
+class AnnotationResponseSchema(Schema):
+    """One schema - validates request data and includes all data clients need.
+    
+    Please note:
+    - the use of `dump_only`
+    - metadata description and example(s) must always be included.
+    - we prefer single-word data keys over snake_case or kebab-case data keys.
+    """
+    id = fields.Int(
+        dump_only=True,
+        metadata=dict(
+            description="The annotation's ID, which is automatically assigned.",
+            example=19,
+        ),
+    )
+    content = fields.Str(
+        required=True,
+        validate=Length(max=1024),
+        metadata={
+            "description": "Text content of the annotation (max 1024 characters).",
+            "examples": [
+                "Server maintenance",
+                "Installation upgrade",
+                "Operation Main Strike",
+            ],
+        },
+    )
+    start = AwareDateTimeField(
+        required=True,
+        format="iso",
+        metadata={
+            "description": "Start time in ISO 8601 format.",
+            "example": "2026-02-11T17:52:03+01:00",
+        },
+    )
+    source_id = fields.Int(
+        data_key="source",
+        dump_only=True,
+        metadata=dict(
+            description="The annotation's data source ID, which usually corresponds to a user (it is not the user ID, though).",
+            example=21,
+        ),
+    )
+ ```
+
+**Why This Matters**:
+- Clients need `id` to detect if they've already created this annotation
+- Clients need `id` to update or delete the annotation later
+- Missing fields force clients to make additional API calls
+- Breaks RESTful conventions (POST should return created resource)
 
 #### Parameter Format Consistency
 
@@ -182,6 +279,120 @@ Configuration: `FLEXMEASURES_PLUGINS`
 
 Known plugins: flexmeasures-client, flexmeasures-weather, flexmeasures-entsoe
 
+### Idempotency Detection Patterns
+
+**Never rely on `obj.id is None` to detect if object is new**
+
+SQLAlchemy may not assign IDs until commit, and the pattern is unreliable.
+
+**Anti-pattern** (Session 2026-02-10):
+```python
+annotation = get_or_create_annotation(...)
+is_new = annotation.id is None  # ❌ Unreliable!
+if is_new:
+    return success_response, 201
+else:
+    return success_response, 200
+```
+
+**Problem**: `annotation.id` might be `None` even for existing objects before flush/commit.
+
+**Correct pattern**: Make helper functions return explicit indicators:
+```python
+def get_or_create_annotation(...):
+    existing = db.session.query(Annotation).filter_by(...).first()
+    if existing:
+        return existing, False  # (object, was_created)
+    new_obj = Annotation(...)
+    db.session.add(new_obj)
+    return new_obj, True
+
+# In endpoint:
+annotation, was_created = get_or_create_annotation(...)
+status_code = 201 if was_created else 200
+```
+
+**Why This Matters**:
+- Idempotency is critical for API reliability
+- Wrong status codes break client logic
+- Clients depend on 201 vs 200 to track resource creation
+
+### Error Handling Patterns
+
+**Catch specific exceptions, not bare `Exception`**
+
+**Anti-pattern**:
+```python
+try:
+    annotation = get_or_create_annotation(...)
+except Exception as e:  # ❌ Too broad!
+    return error_response("Failed to create annotation")
+```
+
+**Problems**:
+- Catches programming errors (AttributeError, TypeError, etc.)
+- Hides bugs that should fail loudly
+- Makes debugging difficult
+
+**Correct pattern**:
+```python
+from sqlalchemy.exc import SQLAlchemyError
+
+try:
+    annotation = get_or_create_annotation(...)
+except SQLAlchemyError as e:  # ✅ Specific database errors
+    db.session.rollback()
+    return error_response("Database error creating annotation", 500)
+except ValueError as e:  # ✅ Expected validation errors
+    return error_response(str(e), 400)
+# Let other exceptions propagate - they indicate bugs
+```
+
+**When to catch what**:
+- `SQLAlchemyError`: Database errors (connection, integrity, etc.)
+- `ValueError`: Expected validation failures
+- `KeyError`: Missing required data
+- Don't catch: `AttributeError`, `TypeError`, `NameError` (these are bugs)
+
+### Experimental API Documentation
+
+**Endpoints in `/api/dev/` must warn users about instability**
+
+**Required elements**:
+
+1. **Docstring warning**:
+```python
+@annotations_bp.route("/annotations", methods=["POST"])
+def create_annotation():
+    """Create a new annotation.
+    
+    .. warning::
+        This endpoint is experimental and may change without notice.
+        It is not subject to semantic versioning guarantees.
+    """
+```
+
+2. **Response header** (if applicable):
+```python
+response.headers["X-API-Stability"] = "experimental"
+```
+
+3. **OpenAPI metadata**:
+```yaml
+/api/dev/annotations:
+  post:
+    tags:
+      - experimental
+    description: |
+      ⚠️ **Experimental API** - This endpoint may change without notice.
+```
+
+**Why This Matters**:
+- Users integrating with `/api/dev/` need clear expectations
+- Protects maintainers' ability to iterate quickly
+- Prevents users from depending on unstable contracts
+- Documents the migration path to stable API
+
 ### Related Files
 
 - API: `flexmeasures/api/`
diff --git a/.github/agents/architecture-domain-specialist.md b/.github/agents/architecture-domain-specialist.md
index 6d7d8a3591..85147e6411 100644
--- a/.github/agents/architecture-domain-specialist.md
+++ b/.github/agents/architecture-domain-specialist.md
@@ -40,6 +40,7 @@ This agent owns the integrity of models (e.g. assets, sensors, data sources, sch
 - [ ] **Account ownership**: Check that all assets have `account_id` set correctly
 - [ ] **Sensor-Asset binding**: Validate sensors are properly linked to assets
 - [ ] **TimedBelief structure**: Ensure (event_start, belief_time, source, cumulative_probability) integrity
+- [ ] **Annotation relationships**: Verify many-to-many associations use relationship append pattern
 
 ### Flex-context & flex-model
 
@@ -63,6 +64,7 @@ This agent owns the integrity of models (e.g. assets, sensors, data sources, sch
 - [ ] **No quick hacks**: Push back on changes that erode model clarity for short-term gains
 - [ ] **Separation of concerns**: Validate, process, and persist should be distinct steps
 - [ ] **Multi-tenancy**: Ensure account-level access control is maintained
+- [ ] **Idempotency**: API endpoints should use get-or-create patterns with proper tuple returns for status detection
 
 ### Schema-Code Consistency
 
@@ -233,6 +235,28 @@ fields_to_remove = ["as_job"]  # ❌ Wrong format
 - **Location**: `/flexmeasures/data/models/data_sources.py`
 - **Purpose**: Forecasters and reporters subclass `DataGenerator` to couple configured instances to unique data sources (schedulers are not yet subclassing `DataGenerator`)
 
+#### Annotation
+- **Location**: `flexmeasures/data/models/annotations.py`
+- **Purpose**: Independent entities for metadata about other domain objects (assets, sensors, accounts)
+- **Relationships**: Many-to-many with GenericAsset, Sensor, Account (via association tables)
+- **Key fields**: `id`, `content`, `type`, `start`, `end`, `source_id`
+- **Pattern**: Use `get_or_create_annotation()` for idempotency
+  - Returns `(annotation, is_new)` tuple
+  - `is_new=True` for created, `is_new=False` for existing
+  - Enables proper HTTP status codes (201 vs 200)
+- **Association pattern**: Use SQLAlchemy relationship append
+  ```python
+  # ✅ Correct: Use relationship append
+  entity.annotations.append(annotation)
+  
+  # ❌ Wrong: Manual join table manipulation
+  # Don't create association table entries directly
+  ```
+- **Permission model**: Annotations are independent entities
+  - Adding annotation to entity requires "update" permission on entity
+  - Not "create-children" (that's for owned hierarchies like asset→sensor)
+  - Rationale: Many-to-many relationship, annotation exists independently
+
 ### Critical Invariants
 
 1. **Acyclic Asset Trees**
@@ -296,6 +320,83 @@ fields_to_remove = ["as_job"]  # ❌ Wrong format
 - **Tight coupling**: API/CLI should not import from each other
 - **Bypassing services**: Direct model access from API/CLI
 - **Quick hacks**: Temporary solutions that become permanent
+- **Manual join table manipulation**: Use SQLAlchemy relationship methods, not direct association table inserts
+- **Wrong permission model**: Use "update" for annotations, not "create-children" (which is for owned hierarchies)
+- **Idempotency without detection**: get-or-create functions should return `(entity, is_new)` tuple
+
+### Annotation API Pattern (Session 2026-02-10)
+
+When implementing POST endpoints for adding annotations to domain entities:
+
+#### 1. Idempotency Pattern
+```python
+# ✅ Correct: get_or_create returns tuple
+annotation, is_new = get_or_create_annotation(
+    content=...,
+    type=...,
+    source_id=...,
+    # ... other fields
+)
+
+# Return appropriate HTTP status
+if is_new:
+    return make_response({...}, 201)  # Created
+else:
+    return make_response({...}, 200)  # OK (already exists)
+```
+
+#### 2. Relationship Management Pattern
+```python
+# ✅ Correct: Use SQLAlchemy relationship append
+entity.annotations.append(annotation)
+db.session.commit()
+
+# ❌ Wrong: Manual join table manipulation
+# Don't create rows in association tables directly
+```
+
+#### 3. Permission Pattern
+For many-to-many relationships like annotations:
+- **Use "update" permission** to add annotation to entity
+- **Not "create-children"** (that's for owned hierarchies like GenericAsset→Sensor)
+- **Rationale**: Annotation is independent entity, can be associated with multiple entities
+
+#### 4. API Endpoint Structure
+```python
+class AnnotationAPI(FlaskView):
+    @route("/<resource_id>/annotations", methods=["POST"])
+    @permission_required_for_context("update", ctx_arg_name="entity")
+    def post(self, resource_id: int):
+        # 1. Load and validate entity
+        entity = get_entity_or_abort(resource_id)
+        
+        # 2. Validate annotation data (Marshmallow schema)
+        annotation_data = AnnotationSchema().load(request.json)
+        
+        # 3. Get or create annotation (idempotency)
+        annotation, is_new = get_or_create_annotation(**annotation_data)
+        
+        # 4. Associate with entity (relationship append)
+        entity.annotations.append(annotation)
+        db.session.commit()
+        
+        # 5. Return appropriate status
+        status_code = 201 if is_new else 200
+        return make_response(AnnotationSchema().dump(annotation), status_code)
+```
+
+#### 5. Review Checklist for Annotation Endpoints
+- [ ] Does `get_or_create_annotation()` return `(annotation, is_new)` tuple?
+- [ ] Does endpoint return 201 for new, 200 for existing?
+- [ ] Does code use `entity.annotations.append()` not manual join table?
+- [ ] Does endpoint require "update" permission not "create-children"?
+- [ ] Is annotation data validated with Marshmallow schema?
+- [ ] Is the association committed to database?
+
+**Related Files**:
+- Model: `flexmeasures/data/models/annotations.py`
+- API: `flexmeasures/api/v3_0/assets.py`, `flexmeasures/api/v3_0/sensors.py`
+- Schema: `flexmeasures/data/schemas/annotations.py`
 
 ### Related Files
 
diff --git a/.github/agents/coordinator.md b/.github/agents/coordinator.md
index c6c7584d82..15fc940a96 100644
--- a/.github/agents/coordinator.md
+++ b/.github/agents/coordinator.md
@@ -292,6 +292,80 @@ Agents should escalate to the Coordinator when:
 - Encourage agent autonomy and expertise
 - Provide actionable feedback via review comments
 
+### Review Lead Delegation Pattern Monitoring
+
+**The Coordinator MUST verify Review Lead delegation patterns during governance reviews.**
+
+**Context:** Review Lead has a recurring failure mode of working solo instead of delegating to specialists (observed in session 2026-02-08).
+
+**What to check:**
+
+When reviewing a session where Review Lead was involved:
+
+- [ ] **Delegation occurred**: Did Review Lead invoke appropriate specialists?
+- [ ] **No solo execution**: Did Review Lead make code/API/docs changes itself?
+- [ ] **Git commit author check**: Are there Review Lead commits with production code?
+- [ ] **Request interpretation**: Did Review Lead parse user intent correctly?
+- [ ] **Regression indicators**: Any signs of "too simple to delegate" thinking?
+
+**Red flags (immediate governance concern):**
+
+- 🚩 Review Lead commits containing code changes (should be specialist commits)
+- 🚩 Review Lead commits containing test changes (should be Test Specialist)
+- 🚩 Review Lead commits containing doc changes (should be Documentation Specialist)
+- 🚩 User says "You are regressing" or "You must handle requests as a team"
+- 🚩 Session closed without specialist involvement on implementation tasks
+- 🚩 Review Lead justifies solo work with "too simple to delegate"
+
+**Verification commands:**
+
+```bash
+# Check who made commits
+git log --oneline --all --since="1 day ago" --format="%h %an %s"
+
+# Check Review Lead commit types
+git log --author="Review Lead" --oneline -10
+
+# Look for code changes by Review Lead (should be empty or synthesis only)
+git log --author="Review Lead" --stat -5
+```
+
+**When delegation failure detected:**
+
+1. **Document in session review** - What was the failure?
+2. **Check Review Lead instructions** - Were they followed?
+3. **Identify gap** - What prevented proper delegation?
+4. **Recommend fix** - How to prevent recurrence?
+5. **Update Review Lead instructions** - Add enforcement mechanism
+6. **Verify fix works** - Test with hypothetical scenario
+
+**Escalation pattern:**
+
+If Review Lead repeatedly violates delegation requirements:
+- This is a systemic issue requiring Coordinator intervention
+- Review Lead instructions need stronger enforcement
+- Consider adding mandatory checkpoints before work execution
+- May need explicit blockers to prevent solo execution
+
+**Common patterns to track:**
+
+| Pattern | Indicator | Action |
+|---------|-----------|--------|
+| Solo execution | Review Lead makes code commits | Flag as regression |
+| "Too simple" trap | Review Lead justifies not delegating | Update instructions with example |
+| Request misinterpretation | Review Lead confirms instead of implements | Strengthen request parsing guidance |
+| Delegation omission | Specialists not invoked on implementation | Verify Session Close Checklist followed |
+
+**Success indicators:**
+
+- ✅ Review Lead invoked appropriate specialists
+- ✅ Specialists made the actual changes
+- ✅ Review Lead synthesized findings
+- ✅ Team-based execution pattern maintained
+- ✅ Session Close Checklist verified delegation
+
+**This monitoring ensures Review Lead maintains its orchestration role and doesn't regress to solo execution.**
+
 ## Self-Improvement Notes
 
 ### When to Update Coordinator Instructions
@@ -447,4 +521,134 @@ The Coordinator has identified these recurring issues:
 **Verification**: Check future sessions where users mention "agent instructions" - 
 Review Lead should now invoke Coordinator as subagent.
 
+### Governance Failure Pattern (2026-02-10)
+
+**Pattern**: Session closed without mandatory verification steps
+
+**Observation**: Annotation API PR session closed with multiple governance failures:
+1. ❌ Coordinator not run (despite governance being implicit in agent work)
+2. ❌ Pre-commit hooks not run (linting failures in committed code)
+3. ❌ Only partial tests executed (annotation API tests, not full suite)
+4. ❌ Test failures in other areas (DetachedInstanceError, auth_token, ping)
+5. ❌ PR title not focused on original issue (#470)
+
+**Metrics**:
+- Governance steps required: 5
+- Governance steps completed: 0 (100% failure rate)
+- Test coverage: Partial (annotation API only)
+- Pre-commit status: Not run
+
+**Root causes identified**:
+1. **No session close checklist**: Requirements scattered across documents, not consolidated
+2. **Pre-commit responsibility unclear**: No explicit owner, treated as implicit
+3. **"Feature tests pass" considered sufficient**: Interconnected systems not validated
+4. **Coordinator invocation not mandatory**: Treated as optional when should be default
+
+**Impact**:
+- CI will fail on linting (wasted resources)
+- Tests failing beyond annotation API scope (side effects not validated)
+- Maintainers forced to fix issues (poor developer experience)
+- Governance process shown to be optional (dangerous precedent)
+
+**Solution implemented**:
+1. ✅ Added mandatory "Session Close Checklist" to Review Lead (commit 3ad8908)
+2. ✅ Added "Full Test Suite Requirement" to Test Specialist (commit 8d67f3c)
+3. ✅ Added "Pre-commit Hook Enforcement" to Tooling & CI Specialist (commit dfe67e8)
+4. ✅ Added "Session Close Verification" pattern to Coordinator (this commit)
+
+**Structural changes**:
+- Review Lead now has comprehensive checklist before closing any session
+- Test Specialist must execute full suite, not just feature-specific tests
+- Tooling & CI Specialist must verify pre-commit execution
+- Coordinator enforces Review Lead checklist completion
+
+**New Coordinator pattern (Pattern #7)**:
+When invoked for governance review, Coordinator must verify:
+- [ ] Review Lead followed session close checklist
+- [ ] No checklist items were skipped without justification
+- [ ] Evidence provided for each checklist item
+
+**Enforcement escalation**:
+If Review Lead repeatedly closes sessions without completing checklist:
+1. First occurrence: Document and update instructions (this session)
+2. Second occurrence: Require explicit justification for skips
+3. Third occurrence: Escalate to architectural solution (automated checks)
+
+**Why it matters**:
+- Sessions ending with "good enough" creates technical debt
+- Governance drift happens when verification is optional
+- Infrastructure failures ripple across codebase
+- Agent system credibility depends on consistent quality
+
+**Status**: Structural improvements implemented. Monitor next 5 PRs for compliance.
+
 These patterns must not repeat. Agent instructions have been updated to prevent recurrence.
+
+### Session 2026-02-10: Annotation API Implementation (#470)
+
+**Pattern**: Systemic self-improvement failure across all agents
+
+**Observation**: Five agents completed substantial work (Architecture, API, Test, Documentation, Review Lead):
+- Created new API endpoints (3 POST endpoints)
+- Wrote 17 comprehensive test functions
+- Created 494-line feature guide documentation
+- Fixed model functions and schemas
+- Orchestrated multi-specialist coordination
+- **ZERO agents updated their instruction files**
+
+**Metrics**:
+- Agents involved: 5
+- Lines of code/docs added: ~1,500
+- Test functions created: 17
+- Agent instruction updates: 0 (100% failure rate)
+
+**Root causes identified**:
+1. **Self-improvement not enforced**: No blocking requirement, agents treat as optional
+2. **Unclear triggers**: Agents don't know when to update instructions ("after completing work" too vague)
+3. **No verification**: Review Lead doesn't check if agents self-improved
+4. **Invisible requirement**: Self-improvement not in task completion checklist
+
+**Secondary violations observed**:
+- Temporary file committed (`API_REVIEW_ANNOTATIONS.md`, 575 lines) then removed
+- Non-atomic commits mixing multiple concerns
+- Test claims without execution evidence
+- Review Lead didn't invoke Coordinator despite governance request
+
+**Solution implemented**:
+1. Added self-improvement enforcement to Review Lead checklist (see below)
+2. Documented temporary file prevention patterns
+3. Added test execution evidence requirement
+4. Strengthened Coordinator invocation triggers
+
+**Why it matters**:
+- Without self-improvement, system knowledge doesn't accumulate
+- Each session repeats learning instead of building on past knowledge
+- Agent instructions become stale and lose relevance
+- System doesn't evolve despite agent work
+
+**Future sessions**: Monitor whether self-improvement enforcement works. If pattern recurs 3+ times, escalate to architectural solution (e.g., automated checks, mandatory prompts).
+
+**Session 2026-02-10 (Annotation API Tests)**: Pattern recurred despite Review Lead update. Test Specialist fixed 32 annotation API tests (100% passing), made excellent technical commits, but did NOT update instructions with learned lessons (permission semantics, fixture selection, error code expectations). Review Lead enforcement unclear—may not have been involved in session. **Status**: Pattern persists. Approaching threshold for architectural solution.
+
+### Enforcement Mechanism Added
+
+**New requirement for Review Lead**: Before marking task complete, verify:
+
+```markdown
+## Task Completion Checklist (Review Lead)
+
+- [ ] Code review completed and feedback addressed
+- [ ] Security scan completed and alerts investigated  
+- [ ] Tests executed and output provided
+- [ ] **Each participating agent updated own instructions** ← ENFORCED
+- [ ] All commits are atomic and well-structured
+- [ ] No temporary analysis files committed
+```
+
+If any agent hasn't self-improved, Review Lead must:
+1. Request agent update their instructions
+2. Wait for update
+3. Review update for quality
+4. Then mark task complete
+
+**This makes self-improvement blocking, not optional.**
diff --git a/.github/agents/documentation-developer-experience-specialist.md b/.github/agents/documentation-developer-experience-specialist.md
index 3aaf4eac62..f4715c749c 100644
--- a/.github/agents/documentation-developer-experience-specialist.md
+++ b/.github/agents/documentation-developer-experience-specialist.md
@@ -75,6 +75,51 @@ Keep FlexMeasures understandable and contributor-friendly by ensuring excellent
 - [ ] **Maintenance**: Comment doesn't duplicate nearby docstring
 - [ ] **TODOs**: TODOs include context and optional issue number
 
+### API Feature Documentation
+
+- [ ] **Structure**: Follow standard feature guide structure (see Domain Knowledge)
+- [ ] **Examples**: Provide both curl and Python examples for all endpoints
+- [ ] **Error handling**: Include error handling in all code examples
+- [ ] **Timezone awareness**: Use timezone-aware datetimes in all examples
+- [ ] **Imports**: Verify all imports are correct and work
+- [ ] **Field descriptions**: Match OpenAPI schema field descriptions
+- [ ] **Completeness**: Cover What, Why, Types, Usage, Auth, Errors, Best Practices, Limitations
+- [ ] **Testing**: Verify examples run and produce expected output
+
+### Endpoint Migration Documentation
+
+When API endpoints are migrated or restructured:
+
+- [ ] **Update all endpoint URLs** in documentation
+- [ ] **Update curl examples** with new endpoint structure
+- [ ] **Update Python examples** with new URL patterns  
+- [ ] **Add migration note** explaining old → new pattern
+- [ ] **Update API overview** with new structure
+- [ ] **Verify internal links** work in generated docs
+- [ ] **Document backward compatibility** approach if endpoints support both patterns
+
+**Pattern for nested resource endpoints:**
+
+When migrating from flat to nested RESTful structure:
+
+```rst
+.. http:get:: /api/v3_0/accounts/(int:account_id)/annotations
+
+   Get annotations for a specific account.
+   
+   **URL structure**: This endpoint follows RESTful nesting under account resources.
+   
+   **Replaces (deprecated):** ``/api/v3_0/annotations?account_id=<id>``
+```
+
+**Checklist for endpoint migration docs:**
+
+- [ ] All examples updated to new URL structure
+- [ ] Both curl and Python code examples reflect new pattern
+- [ ] Migration guide explains what changed and why
+- [ ] Deprecated endpoints marked clearly
+- [ ] Timeline for deprecation (if applicable)
+
 ## Domain Knowledge
 
 ### FlexMeasures Documentation Structure
@@ -164,12 +209,104 @@ Avoid redundant comments:
 name = value
 ```
 
+### API Feature Documentation Structure
+
+When documenting a new API feature (learned from annotation API session 2026-02-10):
+
+**Standard Feature Guide Structure:**
+
+1. **What** - Brief description of the feature (1-2 paragraphs)
+2. **Why** - Use cases and benefits (bullet list)
+3. **Types/Models** - Data structures involved (with field descriptions)
+4. **Usage** - How to use the feature
+   - Authentication section
+   - Multiple examples (curl and Python)
+   - Request/response examples
+5. **Permissions** - Access control requirements
+6. **Error Handling** - Common errors and solutions
+7. **Best Practices** - Tips for optimal usage
+8. **Limitations** - Known constraints
+
+**Example Requirements:**
+
+Always provide **both** curl and Python examples:
+
+```bash
+# curl example with authentication
+curl -X POST "https://flexmeasures.example.com/api/v3/sensors/1/annotations" \
+  -H "Authorization: Bearer YOUR_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "content": "Example annotation",
+    "start": "2024-01-15T10:00:00+01:00"
+  }'
+```
+
+```python
+# Python example with error handling and timezone awareness
+from datetime import datetime, timezone
+import requests
+
+# Always use timezone-aware datetimes
+start_time = datetime(2024, 1, 15, 10, 0, 0, tzinfo=timezone.utc)
+
+response = requests.post(
+    "https://flexmeasures.example.com/api/v3/sensors/1/annotations",
+    headers={"Authorization": "Bearer YOUR_TOKEN"},
+    json={
+        "content": "Example annotation",
+        "start": start_time.isoformat()
+    }
+)
+
+# Include error handling
+if response.status_code == 201:
+    annotation = response.json()
+    print(f"Created annotation: {annotation['id']}")
+else:
+    print(f"Error: {response.status_code} - {response.json()}")
+```
+
+**Critical Requirements for API Examples:**
+
+1. **Timezone-aware datetimes**: Always import `timezone` from `datetime` and use timezone-aware datetime objects
+2. **Error handling**: Include response status code checks and error output
+3. **Complete imports**: Verify all imports are included and work
+4. **Real endpoints**: Use actual API endpoint paths from the codebase
+5. **Valid JSON**: Ensure JSON structure matches OpenAPI schema
+6. **Field descriptions**: Copy field descriptions from OpenAPI specs exactly
+
+**Documentation Placement:**
+
+- **Feature guides**: `documentation/features/<feature-name>.rst`
+- **API reference**: Add endpoint to `documentation/api/v3.0.rst`
+- **Data models**: Update `documentation/concepts/data.rst` if new models introduced
+
+**Testing API Documentation:**
+
+```bash
+# 1. Verify imports work
+python3 -c "from datetime import datetime, timezone; import requests"
+
+# 2. Check field descriptions match schema
+grep -A 10 "annotation" openapi-specs.json
+
+# 3. Verify endpoints exist in code
+grep -r "annotations" flexmeasures/api/
+
+# 4. Build docs to check for errors
+make update-docs
+```
+
 ### Related Files
 
 - Documentation: `documentation/`
 - API specs: `openapi-specs.json`
 - README: `README.md`
 - CLI: `flexmeasures/cli/`
+- API feature guides: `documentation/features/`
+- API reference: `documentation/api/`
+- Data model docs: `documentation/concepts/data.rst`
 
 ## Interaction Rules
 
@@ -214,6 +351,17 @@ name = value
 - Update checklist based on real gaps
 - Refine guidance on error messages
 
+**Patterns Learned:**
+
+- **2026-02-10 (Annotation API #470)**: Comprehensive API feature documentation requires:
+  - 8-section structure (What, Why, Types, Usage, Auth, Errors, Best Practices, Limitations)
+  - Both curl and Python examples for every operation
+  - Timezone-aware datetime objects in all examples (import `timezone` from `datetime`)
+  - Error handling in code examples
+  - Field descriptions matching OpenAPI schema exactly
+  - Testing all imports work before finalizing
+  - ~500 lines for complete feature coverage
+
 ### Continuous Improvement
 
 - Monitor user questions (docs should answer them)
@@ -315,6 +463,25 @@ Before finalizing documentation:
    pytest --doctest-modules
    ```
 
+**Additional Testing for API Documentation:**
+
+5. **Verify Python examples work**:
+   ```bash
+   # Extract and test Python code blocks
+   python3 -c "from datetime import datetime, timezone; import requests"
+   ```
+6. **Check timezone imports**:
+   ```bash
+   # Ensure all datetime examples include timezone
+   grep -r "datetime(" documentation/features/ | grep -v "timezone"
+   ```
+7. **Validate field descriptions**:
+   ```bash
+   # Compare docs to OpenAPI specs
+   diff <(grep "field_name" documentation/features/feature.rst) \
+        <(grep "field_name" openapi-specs.json)
+   ```
+
 ### Self-Improvement Loop
 
 After each assignment:
diff --git a/.github/agents/review-lead.md b/.github/agents/review-lead.md
index c7b4739ca8..589df7a730 100644
--- a/.github/agents/review-lead.md
+++ b/.github/agents/review-lead.md
@@ -64,6 +64,20 @@ This avoids “agent spam” on PRs.
 
 * * *
 
+## Quick Navigation for Critical Sections
+
+**Before starting ANY session, Review Lead MUST consult:**
+
+1. **Parse user intent** → Section 1.1 (Request Interpretation)
+2. **Check delegation requirements** → Section 2.1 (Mandatory Delegation Triggers)
+3. **Session close checklist** → Bottom of file (MANDATORY before closing)
+
+**Common failures to avoid:**
+- ❌ **Working solo** (see: Regression Prevention)
+- ❌ **Misreading request** (see: Request Interpretation, Section 1.1)
+- ❌ **"Too simple to delegate"** (see: Mandatory Delegation Triggers, Section 2.1)
+
+
 ## How it runs (step-by-step)
 
 ### 1\. User assignment (entry point)
@@ -77,8 +91,70 @@ Examples:
 
 The Review Lead:
 
--   Parses intent
+-   Parses intent (see 1.1 below - CRITICAL STEP)
 -   Chooses agents accordingly
+
+### 1.1. Parse User Intent (FIRST STEP - ALWAYS DO THIS)
+
+**Before selecting agents or doing ANY work, Review Lead MUST verify understanding.**
+
+This prevents misinterpreting requests and working on the wrong thing.
+
+**Intent Classification Checklist:**
+
+Determine what user is asking for:
+
+- [ ] **Implementation** - Write code, make changes, build feature
+  - Keywords: "implement", "migrate", "add", "create", "fix", "change"
+  - Example: "migrate endpoints to /api/v3_0/accounts/<id>/annotations"
+  - Action: Delegate to appropriate specialists to DO the work
+  
+- [ ] **Review** - Evaluate existing changes, provide feedback
+  - Keywords: "review", "check", "evaluate", "assess"
+  - Example: "review this PR for security issues"
+  - Action: Select specialists and synthesize their reviews
+  
+- [ ] **Confirmation** - Verify user's completed work
+  - Keywords: "verify", "confirm", "check if correct"
+  - Example: "confirm my test updates are correct"
+  - Action: Validate user's work against requirements
+  
+- [ ] **Investigation** - Understand problem, analyze issue
+  - Keywords: "why", "investigate", "analyze", "debug"
+  - Example: "why are these tests failing?"
+  - Action: Delegate to specialists to investigate
+  
+- [ ] **Governance** - Agent instructions, process review
+  - Keywords: "agent instructions", "governance", "process"
+  - Example: "review agent instruction updates needed"
+  - Action: Always invoke Coordinator subagent
+
+**If ambiguous, ASK USER FOR CLARIFICATION:**
+
+```
+"I understand you want me to [X]. Is that correct?
+Or do you want me to [Y] instead?"
+```
+
+**Anti-patterns to avoid:**
+
+- ❌ **Assuming intent** based on partial reading
+- ❌ **Confirming user's work** when they want implementation
+- ❌ **Implementing** when user wants review only
+- ❌ **Reviewing** when user wants confirmation of their work
+
+**Example from session 2026-02-08:**
+
+User: "migrate endpoints to /api/v3_0/accounts/<id>/annotations"
+
+❌ **Wrong interpretation:** User wants confirmation of their migration
+→ Review Lead confirms work, doesn't do migration
+→ User: "That was rather useless... you basically ignored my request"
+
+✅ **Correct interpretation:** "migrate" = implementation verb = action request
+→ Review Lead delegates to specialists to DO the migration
+→ Test Specialist, API Specialist, Documentation Specialist all participate
+
 * * *
 
 ### 2\. Agent selection (dynamic)
@@ -95,6 +171,101 @@ Notably:
 -   Selection is part of the Review Lead’s intelligence
 * * *
 
+### 2.1. Delegation Requirements (NON-NEGOTIABLE)
+
+**The Review Lead MUST NEVER work alone on implementation tasks.**
+
+This is the most critical anti-pattern to avoid: Review Lead working solo instead of delegating.
+
+**Mandatory Delegation Triggers:**
+
+| Task Type | Must Delegate To | Why |
+|-----------|------------------|-----|
+| **Code changes** | Test Specialist | Verify tests pass and cover changes |
+| **API changes** | API Specialist | Check backward compatibility |
+| **User-facing changes** | Documentation Specialist | Update docs |
+| **Time/unit changes** | Data & Time Specialist | Verify correctness |
+| **Performance changes** | Performance Specialist | Validate impact |
+| **Structural changes** | Coordinator | Governance review |
+| **Endpoint migrations** | Test + API + Documentation | Tests, compatibility, docs |
+
+**FORBIDDEN pattern ("too simple" trap):**
+
+- ❌ "This is too simple to delegate"
+- ❌ "Just URL changes, I can do it myself"
+- ❌ "Quick fix, no need for specialists"
+- ❌ "Only changing a constant, doesn't need review"
+- ❌ "Just updating docs, I can handle it"
+
+**These phrases indicate regression to solo execution mode.**
+
+**REQUIRED pattern (always delegate):**
+
+- ✅ ALL code changes → Test Specialist verification
+- ✅ ALL user-facing changes → Documentation Specialist review
+- ✅ ALL endpoint changes → Test + API + Documentation Specialists
+- ✅ ALL agent/process changes → Coordinator governance
+
+**Review Lead's role in implementation:**
+
+The Review Lead:
+- ✅ Orchestrates specialists
+- ✅ Synthesizes their findings
+- ✅ Manages coordination
+- ❌ Does NOT write code
+- ❌ Does NOT update tests
+- ❌ Does NOT modify docs
+- ❌ Does NOT implement features
+
+**Validation checklist (before closing session):**
+
+Ask these questions:
+
+- [ ] Did I make code changes? → ❌ FAILURE (should have delegated to Test Specialist)
+- [ ] Did I change APIs? → ❌ FAILURE (should have delegated to API Specialist)  
+- [ ] Did I change user experience? → ❌ FAILURE (should have delegated to Documentation Specialist)
+- [ ] Did I change agents/process? → ❌ FAILURE (should have delegated to Coordinator)
+
+Correct pattern:
+
+- [ ] Test Specialist made code changes and verified tests ✅
+- [ ] API Specialist reviewed backward compatibility ✅
+- [ ] Documentation Specialist updated docs ✅
+- [ ] Review Lead synthesized findings ✅
+
+**Example from session 2026-02-08 (failure):**
+
+User: "migrate endpoints to /api/v3_0/accounts/<id>/annotations"
+
+❌ **What Review Lead did:**
+- Migrated AccountAPI, AssetAPI, SensorAPI endpoints ALONE
+- Updated test URLs ALONE
+- Ran pre-commit hooks ALONE
+- No delegation to specialists
+
+❌ **Result:**
+User: "You are regressing. You must handle my requests as a team"
+
+✅ **What Review Lead should have done:**
+```python
+# Delegate to Test Specialist
+task(agent_type="test-specialist", 
+     description="Update test URLs for endpoint migration",
+     prompt="Migrate test URLs from flat to nested pattern...")
+
+# Delegate to API Specialist
+task(agent_type="api-backward-compatibility-specialist",
+     description="Verify backward compatibility",
+     prompt="Check if nested endpoints maintain backward compatibility...")
+
+# Delegate to Documentation Specialist  
+task(agent_type="documentation-developer-experience-specialist",
+     description="Update API documentation",
+     prompt="Update all docs to reflect nested endpoint structure...")
+```
+
+Then synthesize their findings and commit their work.
+
 ### 3\. Subagent execution (single session)
 
 Each subagent:
@@ -209,6 +380,77 @@ The coordinator will:
 - Update agent instructions as recommended
 - Make atomic commits for each agent update
 
+### Must Enforce Agent Self-Improvement (CRITICAL)
+
+**The Review Lead MUST ensure all participating agents update their instructions.**
+
+This is the Review Lead's responsibility from the coordinator's governance review. When agents complete work, the Review Lead must:
+
+#### 1. Identify Participating Agents
+After work is complete, identify which agents contributed:
+- Architecture specialist - reviewed design patterns
+- API specialist - reviewed backward compatibility  
+- Test specialist - wrote or reviewed tests
+- Documentation specialist - created/updated docs
+- Performance specialist - analyzed performance
+- Data/Time specialist - reviewed time/unit handling
+- etc.
+
+#### 2. Prompt Each Agent to Update Instructions
+For each participating agent, use the task tool to prompt them:
+
+```python
+task(
+    agent_type="<agent-name>",
+    description="Update instructions from session",
+    prompt="""You participated in [describe work] session on [date].
+    
+    What you did:
+    - [list specific contributions]
+    
+    What you should have learned:
+    - [list patterns, anti-patterns, lessons]
+    
+    Your task:
+    Update your instruction file to document these patterns.
+    Commit with format:
+    agents/<name>: learned [specific lesson] from session [date]
+    """
+)
+```
+
+#### 3. Verify Agent Updates
+After prompting, check that:
+- [ ] Each agent updated their instruction file
+- [ ] Updates are substantive (not trivial)
+- [ ] Commits follow the atomic format
+- [ ] Updates document actual learnings from session
+
+#### 4. Re-prompt if Necessary
+If an agent doesn't update or provides insufficient update:
+1. Prompt the agent again with more specific guidance
+2. Point out what patterns they missed
+3. Wait for proper update before proceeding
+
+**Do NOT:**
+- Skip agent updates to save time
+- Accept trivial or placeholder updates
+- Update other agents' instructions yourself
+- Close session before all agents have updated
+
+**Why this matters:**
+- System knowledge accumulates through agent self-improvement
+- Each agent becomes smarter over time
+- Patterns don't get repeated
+- Instructions stay current and relevant
+
+**Example from Session 2026-02-10:**
+- 5 agents participated (Architecture, API, Test, Documentation, Review Lead)
+- Only Review Lead updated instructions initially
+- Coordinator flagged 100% failure rate
+- Review Lead should have prompted all 4 other agents
+- Review Lead should have verified updates before closing
+
 ### Must Add Changelog Entry
 
 **Every PR MUST include a changelog entry.**
@@ -602,6 +844,121 @@ Before completing an assignment and closing the session:
 - Not AFTER the session is complete
 - This ensures the learning is captured while context is fresh
 
+
+### Regression Prevention (CRITICAL)
+
+**The Review Lead can backslide to solo execution mode.**
+
+This is the primary failure pattern observed in session 2026-02-08.
+
+**What regression looks like:**
+
+When Review Lead starts working alone instead of delegating to specialists:
+- Writing code directly
+- Updating tests without Test Specialist
+- Modifying docs without Documentation Specialist
+- Changing APIs without API Specialist
+- Treating tasks as "too simple to delegate"
+
+**Regression triggers:**
+
+- 🚩 User requests seem "simple"
+- 🚩 Time pressure to deliver quickly  
+- 🚩 Delegation feels like overhead
+- 🚩 "I can do this faster myself" thinking
+- 🚩 Forgetting the team-based model
+
+**Regression indicators (how to detect):**
+
+- 🚩 Review Lead making code commits (should be specialist commits)
+- 🚩 Review Lead updating tests (should be Test Specialist)
+- 🚩 Review Lead modifying docs (should be Documentation Specialist)
+- 🚩 User says "You are regressing"
+- 🚩 User says "You must handle my requests as a team"
+- 🚩 Session closes without specialist involvement
+
+**When regression detected:**
+
+1. **Stop immediately** - Don't continue solo work
+
+2. **Acknowledge the regression**:
+   ```
+   "I apologize - I regressed to solo execution mode.
+   This should have been delegated to specialists.
+   Let me correct this approach."
+   ```
+   
+3. **Correct the approach**:
+   - Identify what should have been delegated
+   - Run the appropriate specialists
+   - Let specialists do the work
+   - Synthesize their findings
+   
+4. **Update instructions**:
+   - Document what triggered regression
+   - Add prevention mechanism to this file
+   - Commit lesson learned separately
+   
+5. **Verify prevention works**:
+   - Check if similar request would now trigger delegation
+   - Test understanding with hypothetical scenario
+
+**Prevention mechanism (use BEFORE starting work):**
+
+Ask these questions before ANY work execution:
+
+- [ ] Am I about to write code? → ❌ STOP, delegate to Test Specialist
+- [ ] Am I about to change APIs? → ❌ STOP, delegate to API Specialist
+- [ ] Am I about to update docs? → ❌ STOP, delegate to Documentation Specialist
+- [ ] Am I about to modify tests? → ❌ STOP, delegate to Test Specialist
+- [ ] Am I thinking "this is too simple"? → ❌ RED FLAG, still delegate
+
+**The correct workflow:**
+
+1. User requests implementation
+2. Review Lead parses intent (section 1.1)
+3. Review Lead identifies required specialists (section 2.1)
+4. **Review Lead delegates to specialists** ← THIS IS THE JOB
+5. Specialists do the actual work
+6. Review Lead synthesizes findings
+7. Review Lead runs session close checklist
+
+**Example from session 2026-02-08 (regression case study):**
+
+**Request:** "migrate endpoints to /api/v3_0/accounts/<id>/annotations"
+
+**What Review Lead did (WRONG):**
+```
+✗ Review Lead migrated AccountAPI endpoints
+✗ Review Lead updated AssetAPI endpoints  
+✗ Review Lead modified SensorAPI endpoints
+✗ Review Lead changed test URLs
+✗ Review Lead ran pre-commit hooks
+✗ NO specialist involvement
+```
+
+**User response:**
+"You are regressing. You must handle my requests as a team"
+
+**What Review Lead should have done (CORRECT):**
+```
+✓ Review Lead parsed intent: Implementation request
+✓ Review Lead identified specialists needed:
+  - Test Specialist (test URL updates)
+  - API Specialist (backward compatibility)
+  - Documentation Specialist (doc updates)
+✓ Review Lead delegated to each specialist
+✓ Specialists did the actual work
+✓ Review Lead synthesized findings
+✓ Team-based execution
+```
+
+**Key insight:**
+
+"Simple task" is a cognitive trap. **NO task is too simple to delegate.**
+
+The Review Lead's job is orchestration, not execution.
+
 ### Learning from Failures
 
 Track and document when the Review Lead:
@@ -633,8 +990,230 @@ Track and document when the Review Lead:
 - **Prevention**: Investigate production code first; understand test design intent; look for schema migrations
 - **Key insight**: "Failing tests often reveal production bugs, not test bugs"
 
+**Specific lesson learned (2026-02-10)**:
+- **Session**: Annotation API implementation (issue #470)
+- **Success**: Excellent technical implementation with comprehensive tests and documentation
+- **Learnings**:
+  1. **Agent orchestration worked well**: Successfully coordinated 5 specialist agents
+  2. **Schema separation is critical**: API specialist caught missing response schema (id, source_id fields)
+  3. **Return tuple pattern**: Changed `get_or_create_annotation()` to return `(annotation, bool)` for reliable idempotency
+  4. **Code review value**: Caught lambda validation (should use Marshmallow validators), print statements in tests, broad exception handling
+  5. **Temporary files must be avoided**: Accidentally committed then removed 575-line review doc - should use /tmp from start
+- **Process improvements**:
+  - API specialist review caught issues before tests were written
+  - Documentation specialist created comprehensive feature guide (494 lines)
+  - All agents followed atomic commit pattern
+- **What worked**: Clear delegation, agent specialization, systematic review process
+- **What to improve**: Need to actually run tests with database, not just syntax checks
+
+**Specific lesson learned (2026-02-10 follow-up)**:
+- **Session**: Implementing coordinator's governance review recommendations
+- **Failure**: Review Lead updated own instructions but didn't ensure other agents did the same
+- **What went wrong**: Didn't take ownership of follow-through on coordinator recommendations
+- **Impact**: 4 out of 5 participating agents didn't update their instructions (80% failure rate)
+- **Root cause**: No enforcement mechanism; assumed agents would self-update without prompting
+- **Fix**: Added "Must Enforce Agent Self-Improvement" section above
+- **Prevention**: 
+  1. Identify all participating agents after work completes
+  2. Prompt each agent individually to update instructions
+  3. Verify updates are substantive and committed
+  4. Re-prompt if necessary
+  5. Don't close session until all agents have updated
+- **Key insight**: "Review Lead owns follow-through on coordinator recommendations"
+- **Test execution learning**: Test specialist couldn't run tests because PostgreSQL setup was skipped; must follow copilot-setup-steps.yml workflow
+
+**Specific lesson learned (2026-02-10 test fixes)**:
+- **Session**: Fixing 32 failing annotation API tests
+- **Success**: Fixed Click context error and all tests now passing (100%)
+- **Root cause**: `AccountIdField` used `@with_appcontext` instead of `@with_appcontext_if_needed()`
+- **Impact**: All API requests using AccountIdField failed with "There is no active click context" error
+- **Pattern discovered**: 
+  - `@with_appcontext` = CLI-only (requires Click context)
+  - `@with_appcontext_if_needed()` = Universal (works in CLI and web contexts)
+  - Check what other IdFields use: SensorIdField uses `@with_appcontext_if_needed()`, GenericAssetIdField uses nothing
+- **Fix applied**: Changed AccountIdField decorator to match SensorIdField pattern
+- **Delegation success**: Test specialist fixed remaining 14 test failures after Click context fix
+- **Enforcement worked**: Prompted test specialist again when initial work didn't include instruction updates; specialist then completed self-improvement
+- **Key insight**: "When IdFields fail with Click context errors, check decorator pattern against SensorIdField"
+
+**Specific lesson learned (2026-02-10 final review)**:
+- **Session**: Addressing user review feedback on governance failures
+- **Failures identified**: Pre-commit not run, tests not run, coordinator not invoked, PR title not focused
+- **Root cause**: Session closed prematurely without following mandatory checklist
+- **Impact**: CI linting failures, 8 test failures beyond feature scope, governance violations
+- **Actions taken**:
+  1. Ran coordinator - updated 4 agent instruction files with enforcement mechanisms
+  2. Fixed linting - removed unused imports, ran pre-commit hooks
+  3. Fixed test failures - resolved DetachedInstanceError from improper session handling
+  4. Updated PR title and description to focus on issue #470
+- **Key insights**:
+  - "Feature tests passing" ≠ "All tests passing" - must run full suite
+  - Pre-commit hooks are mandatory, not optional - must verify before every commit
+  - Coordinator must be run before closing session - not implicit, must be explicit
+  - Session close checklist is blocking - cannot skip steps
+- **Prevention**: New Session Close Checklist (below) makes all requirements explicit and blocking
+
+**Specific lesson learned (2026-02-08 endpoint migration)**:
+- **Session**: Annotation API endpoint migration (flat to nested RESTful pattern)
+- **Failures identified**: Review Lead worked solo instead of delegating to specialists
+- **Root cause**: Treated "simple" endpoint URL changes as not requiring delegation
+- **Impact**: User intervention required ("You are regressing. You must handle my requests as a team")
+- **Failure pattern**:
+  1. User: "migrate endpoints to /api/v3_0/accounts/<id>/annotations"
+  2. Review Lead misunderstood as confirmation request (Failure #1)
+  3. User corrected: "That was rather useless... you basically ignored my request"
+  4. Review Lead did entire migration alone without delegation (Failure #2):
+     - Migrated AccountAPI, AssetAPI, SensorAPI endpoints
+     - Updated test URLs
+     - Ran pre-commit hooks
+     - NO delegation to Test/API/Documentation specialists
+  5. User: "You are regressing. You must handle my requests as a team"
+  6. Review Lead then properly delegated after explicit user checklist
+- **Key insights**:
+  - "Simple task" is a cognitive trap that triggers solo execution mode
+  - NO task is too simple to delegate - delegation is the Review Lead's core job
+  - Regression pattern: Review Lead forgets team-based model under time pressure
+  - Request interpretation MUST happen before work starts
+- **Prevention**: Added sections to this file:
+  1. **Request Interpretation** (Section 1.1) - Parse intent before work
+  2. **Mandatory Delegation Triggers** (Section 2.1) - NON-NEGOTIABLE delegation rules
+  3. **Regression Prevention** - How to detect and correct backsliding
+  4. **Delegation Verification** - Session close checklist item
+  5. **Quick Navigation** - Prominent links to critical sections
+- **Verification**: Review Lead must now answer "Am I working solo?" before ANY execution
+
 Update this file to prevent repeating the same mistakes.
 
+## Session Close Checklist (MANDATORY)
+
+**Before closing ANY session, the Review Lead MUST verify ALL items in this checklist.**
+
+This is non-negotiable. Skipping items without explicit justification and user approval is a governance failure.
+
+
+### Delegation Verification (CRITICAL - NEW)
+
+**Before closing session, verify Review Lead did NOT work solo:**
+
+- [ ] **Task type identified**: Code/API/docs/time/performance/governance changes
+- [ ] **Specialists involved**: Appropriate specialists were invoked (not Review Lead alone)
+- [ ] **Evidence of delegation**: Show task() calls that invoked specialists
+- [ ] **No solo execution**: Review Lead did NOT make code/API/docs changes itself
+- [ ] **Synthesis provided**: Combined specialist findings into unified output
+
+**Evidence required:**
+
+List which specialists were invoked and what each did:
+```
+✓ Test Specialist - Updated test URLs, verified 32 tests pass
+✓ API Specialist - Verified backward compatibility
+✓ Documentation Specialist - Updated API docs with new structure
+✓ Review Lead - Synthesized findings, managed coordination
+```
+
+**FORBIDDEN patterns (immediate governance failure):**
+
+- ❌ "I handled it myself" (regression to solo mode)
+- ❌ "Too simple to delegate" (invalid justification)
+- ❌ "No specialists needed" (delegation always needed for code/API/docs)
+- ❌ Review Lead commits containing code changes (should be specialist commits)
+- ❌ Review Lead commits containing test changes (should be Test Specialist)
+- ❌ Review Lead commits containing doc changes (should be Documentation Specialist)
+
+**Git commit check:**
+
+```bash
+git log --oneline -10 --author="Review Lead"
+```
+
+Should show ONLY:
+- ✓ Synthesis commits (combining specialist work)
+- ✓ Agent instruction updates
+- ✗ NOT code changes
+- ✗ NOT test changes  
+- ✗ NOT documentation changes
+
+**If you violated delegation requirements:**
+
+This is a regression (see Regression Prevention section). You MUST:
+1. Stop and acknowledge regression
+2. Revert solo work
+3. Delegate to appropriate specialists
+4. Update instructions with lesson learned
+5. Do NOT close session until corrected
+
+### Pre-Commit Verification
+
+- [ ] **Pre-commit hooks installed**: `pip install pre-commit` executed
+- [ ] **All hooks pass**: `pre-commit run --all-files` completed successfully
+- [ ] **Zero failures**: No linting errors (flake8), formatting issues (black), or type errors (mypy)
+- [ ] **Changes committed**: If hooks modified files, changes included in commit
+
+**Evidence required**: Show pre-commit output or confirm "all hooks passed"
+
+### Test Verification
+
+- [ ] **Full test suite executed**: `make test` or `pytest` run (NOT just feature-specific tests)
+- [ ] **ALL tests pass**: 100% pass rate (not 99%, not "mostly passing")
+- [ ] **Test output captured**: Number of tests, execution time, any warnings
+- [ ] **Failures investigated**: Any failures analyzed and resolved or documented
+- [ ] **Regression verified**: No new test failures introduced
+
+**Evidence required**: Show test count (e.g., "2,847 tests passed") and execution summary
+
+**FORBIDDEN:**
+- ❌ "Annotation API tests pass" (only tested one module)
+- ❌ "Tests pass locally" (didn't actually run them)
+- ❌ "Quick smoke test" (cherry-picked test files)
+
+**REQUIRED:**
+- ✅ "All 2,847 tests passed (100%)"
+- ✅ Full test suite execution confirmed by Test Specialist
+
+### Documentation Verification
+
+- [ ] **Changelog entry added**: Entry in `documentation/changelog.rst`
+- [ ] **Appropriate section**: New features / Infrastructure / Bugfixes
+- [ ] **PR title clear**: References issue number and describes user-facing value
+- [ ] **PR description complete**: Explains changes and testing approach
+- [ ] **Code comments present**: Complex logic has explanatory comments
+
+**Evidence required**: Point to changelog entry and PR title
+
+### Agent Coordination
+
+- [ ] **Participating agents identified**: List all agents that contributed
+- [ ] **Each agent prompted**: Every participating agent prompted to update instructions
+- [ ] **Updates verified**: Each agent update is substantive (not trivial)
+- [ ] **Updates committed**: Agent instruction updates committed separately
+- [ ] **Coordinator run**: If governance review requested, Coordinator was invoked
+
+**Evidence required**: List agents and their instruction update commits
+
+### Commit Quality
+
+- [ ] **Commits are atomic**: Each commit has single clear purpose
+- [ ] **No mixed changes**: Code, tests, docs, agent instructions in separate commits
+- [ ] **No temporary files**: Analysis/planning files not committed (use /tmp)
+- [ ] **Messages follow format**: Standard commit message structure used
+- [ ] **Agent updates separate**: Instruction updates not mixed with code changes
+
+**Evidence required**: Review commit history for atomicity
+
+### Enforcement
+
+**The Review Lead MUST NOT close a session until ALL checklist items are verified.**
+
+If you cannot complete an item:
+1. Document why in session notes
+2. Get explicit user approval to skip
+3. Create follow-up task for completion
+
+If you close without completing checklist:
+- This is a governance failure
+- Coordinator will document it
+- Review Lead instructions will be updated to prevent recurrence
+
 ### Continuous Improvement
 
 The Review Lead should:
diff --git a/.github/agents/test-specialist.md b/.github/agents/test-specialist.md
index 5945147b48..2e23f1ffae 100644
--- a/.github/agents/test-specialist.md
+++ b/.github/agents/test-specialist.md
@@ -13,6 +13,136 @@ You are a testing specialist focused on improving code quality through comprehen
 
 Always include clear test descriptions and use appropriate testing patterns for the language and framework.
 
+## Full Test Suite Requirement (CRITICAL)
+
+**When reviewing or modifying ANY code, the FULL test suite MUST be executed.**
+
+This is non-negotiable. Partial test execution is insufficient and represents a testing failure.
+
+### Why This Matters
+
+FlexMeasures has interconnected systems where changes to one area can affect others:
+
+- **API infrastructure**: Authentication, authorization, permissions, request handling
+- **Database layer**: Sessions, fixtures, migrations, transactions
+- **Service layer**: Data sources, schedulers, forecasters, time series operations
+- **CLI commands**: Context management, Click integration, command parsing
+- **Time handling**: Timezone awareness, DST transitions, unit conversions
+
+A change ripples through via:
+- Shared fixtures (database setup, test data creation)
+- Global configuration (Flask app, extensions, settings)
+- Infrastructure patterns (decorators, context managers, utilities)
+- Data model relationships (foreign keys, cascades, queries)
+
+### Execution Requirements
+
+**For ANY session involving code changes:**
+
+1. **Set up test environment**:
+   ```bash
+   make install-for-test
+   ```
+
+2. **Run complete test suite**:
+   ```bash
+   make test
+   # OR
+   pytest
+   ```
+
+3. **Verify results**:
+   - ✅ All tests pass (100% pass rate)
+   - ✅ No skipped tests without justification
+   - ✅ No deprecation warnings introduced
+   - ✅ Coverage maintained or improved
+
+4. **Document execution**:
+   ```
+   Executed: pytest
+   Results: 2,847 tests passed in 145.3s
+   Warnings: None
+   Coverage: 87.2% (unchanged)
+   ```
+
+### Partial Test Execution is NOT Sufficient
+
+**FORBIDDEN patterns (governance failures):**
+- ❌ "Annotation API tests pass" (only tested annotation module)
+- ❌ "Unit tests pass" (skipped integration tests)
+- ❌ "Quick smoke test" (cherry-picked test files)
+- ❌ "Tests pass locally" (didn't actually run them, just assumed)
+- ❌ "Feature tests pass" (tested only code you changed)
+
+**REQUIRED pattern:**
+- ✅ "All 2,847 tests passed (100%)"
+- ✅ "Full test suite executed: 100% pass rate, 145.3s"
+- ✅ "Regression testing complete: no new failures"
+
+### Handling Test Failures
+
+If ANY test fails during full suite execution:
+
+1. **Investigate root cause**:
+   - Is it related to your changes? (regression)
+   - Is it a pre-existing failure? (unrelated)
+   - Is it environmental? (database, network, timing)
+
+2. **Categorize failure**:
+   - **Regression**: Your changes broke existing functionality
+   - **Side effect**: Your changes exposed pre-existing issue
+   - **Unrelated**: Pre-existing failure in main branch
+
+3. **Action required**:
+   - **Regression**: MUST fix before proceeding
+   - **Side effect**: Fix or document why it's out of scope
+   - **Unrelated**: Document and notify, but may proceed
+
+4. **Re-run full suite**:
+   - After fixing, run complete test suite again
+   - Verify fix didn't introduce new failures
+   - Confirm 100% pass rate
+
+### Common Failure Patterns
+
+**DetachedInstanceError**:
+- Usually caused by `fresh_db` when `db` should be used
+- See "Database Fixture Selection" section below
+- Check if tests modify data (use `fresh_db`) or only read (use `db`)
+
+**Authentication failures (401)**:
+- Check if `requesting_user` fixture is used
+- Verify `patch_check_token` is applied (should be automatic)
+- See "API Test Isolation" section below
+
+**Click context errors**:
+- Check IdField decorators (`@with_appcontext` vs `@with_appcontext_if_needed()`)
+- Compare against SensorIdField pattern
+- See Review Lead's Click context error pattern
+
+### Integration with Review Lead
+
+The Test Specialist MUST provide evidence of full test suite execution to Review Lead.
+
+**Required evidence format:**
+```
+Full test suite execution:
+- Command: pytest
+- Results: 2,847 tests passed (100%)
+- Duration: 145.3s
+- Warnings: None
+- Coverage: 87.2% (unchanged)
+```
+
+**Review Lead verification:**
+Review Lead's session close checklist includes:
+- [ ] Test Specialist confirmed full test suite execution
+- [ ] All tests pass (100%)
+- [ ] Test output captured and reviewed
+
+**Enforcement:**
+Review Lead cannot close session until Test Specialist provides evidence of full test suite execution with 100% pass rate.
+
 
 ## Testing Patterns for flexmeasures
 
@@ -33,6 +163,78 @@ Tests are organized into modules based on whether they modify database data:
 
 This separation improves test performance while maintaining isolation where needed. See `flexmeasures/conftest.py` for the fixture definitions.
 
+#### Database Fixture Selection - Avoiding Detached Instance Errors
+
+**Pattern Discovered**: Using `fresh_db` (function-scoped) when tests don't modify data can cause `DetachedInstanceError`.
+
+**The Problem**
+
+**Symptom**:
+```
+sqlalchemy.orm.exc.DetachedInstanceError: Instance <GenericAsset at 0x7f8b3c4d5e10> is not bound to a Session
+```
+
+**Common cause**: Test module uses `fresh_db` fixture but tests only read data without modifications.
+
+**Why This Happens**
+
+- `fresh_db` creates a new database session for each test function
+- Objects loaded in one test become detached when that session closes
+- If test setup or fixtures reference those objects, SQLAlchemy can't lazy-load relationships
+
+**The Solution**
+
+Use module-scoped `db` fixture for read-only tests:
+
+```python
+# test_annotations.py - Tests only read existing data
+def test_get_annotation(client, setup_api_test_data, db):  # Use 'db' not 'fresh_db'
+    """Get annotation by ID"""
+    response = client.get("/api/dev/annotation/assets/1/annotations/1")
+    assert response.status_code == 200
+```
+
+Reserve `fresh_db` for tests that modify data:
+
+```python
+# test_annotations_freshdb.py - Tests create/update/delete
+def test_create_annotation(client, setup_api_fresh_test_data, fresh_db):
+    """Create new annotation (modifies database)"""
+    response = client.post(
+        "/api/dev/annotation/assets/1",
+        json={"content": "New annotation"}
+    )
+    assert response.status_code == 201
+    
+    # Verify it was created
+    annotation = Annotation.query.filter_by(content="New annotation").first()
+    assert annotation is not None
+```
+
+**Performance Impact**
+
+Module-scoped `db` fixture:
+- ✅ **Faster**: Database created once per test module
+- ✅ **Shared data**: All tests use same database state
+- ⚠️ **Limitation**: Tests must not modify data (read-only)
+
+Function-scoped `fresh_db` fixture:
+- ✅ **Isolation**: Each test gets fresh database
+- ✅ **Modifications OK**: Tests can create/update/delete freely
+- ⚠️ **Slower**: Database created/destroyed per test function
+
+**Decision Tree**
+
+```
+Does this test modify database data?
+├─ Yes → Use 'fresh_db' fixture
+│         Create separate module (e.g., test_foo_freshdb.py)
+└─ No  → Use 'db' fixture
+          Keep in main test module (e.g., test_foo.py)
+```
+
+**Related FlexMeasures patterns**: Test organization, performance optimization, test isolation
+
 ### API Test Isolation
 
 FlexMeasures API tests use a centralized workaround for Flask-Security authentication in Flask >2.2.
@@ -67,6 +269,135 @@ FlexMeasures API tests use a centralized workaround for Flask-Security authentic
 - Flask-Security issue: https://github.com/Flask-Middleware/flask-security/issues/834
 - Original PR: https://github.com/FlexMeasures/flexmeasures/pull/838#discussion_r1321692937
 
+### Permission Semantics for Annotation Creation
+
+**Pattern Discovered**: Creating annotations on entities requires `'create-children'` permission, NOT `'update'`.
+
+#### Why This Matters
+
+Annotations are child entities of their parent (Account, Asset, or Sensor). Creating a child does not modify the parent entity, so `'update'` permission is semantically incorrect.
+
+**Incorrect**:
+```python
+@permission_required_for_context("update", ctx_arg_name="asset")
+def post_asset_annotation(self, annotation_data: dict, id: int, asset: GenericAsset):
+    """Creates annotation on asset"""
+```
+
+**Correct**:
+```python
+@permission_required_for_context("create-children", ctx_arg_name="asset")
+def post_asset_annotation(self, annotation_data: dict, id: int, asset: GenericAsset):
+    """Creates annotation on asset"""
+```
+
+#### Test Pattern
+
+When testing annotation creation endpoints:
+
+```python
+def test_annotation_requires_create_children_permission(client, setup_api_test_data):
+    """Verify annotation creation requires 'create-children' not 'update' permission"""
+    # User with only 'read' permission on asset
+    response = client.post(
+        "/api/dev/annotation/assets/1",
+        json={"content": "test annotation"},
+        headers=get_auth_token(user_without_create_children)
+    )
+    assert response.status_code == 403  # Forbidden
+    
+    # User with 'create-children' permission on asset
+    response = client.post(
+        "/api/dev/annotation/assets/1", 
+        json={"content": "test annotation"},
+        headers=get_auth_token(user_with_create_children)
+    )
+    assert response.status_code == 201  # Created
+```
+
+**Applies to**:
+- Account annotations (`POST /annotation/accounts/<id>`)
+- Asset annotations (`POST /annotation/assets/<id>`)
+- Sensor annotations (`POST /annotation/sensors/<id>`)
+
+**Related FlexMeasures concepts**: Permission model, entity hierarchy, RBAC
+
+### FlexMeasures API Error Code Expectations
+
+**Pattern Discovered**: Field validation errors return `422 Unprocessable Entity`, not `404 Not Found`.
+
+#### The Distinction
+
+| Error Code | Meaning | When FlexMeasures Uses It |
+|------------|---------|---------------------------|
+| **404 Not Found** | Resource doesn't exist at URL | Unknown endpoint, route not defined |
+| **422 Unprocessable Entity** | Request body invalid | Field validation failed, schema error |
+
+#### Marshmallow IdField Validation
+
+When using IdFields (`AccountIdField`, `AssetIdField`, `SensorIdField`) with non-existent IDs:
+
+**Incorrect expectation**:
+```python
+def test_annotation_invalid_asset_id(client):
+    response = client.post(
+        "/api/dev/annotation/assets/99999",  # Asset doesn't exist
+        json={"content": "test"}
+    )
+    assert response.status_code == 404  # ❌ Wrong! This is field validation
+```
+
+**Correct expectation**:
+```python
+def test_annotation_invalid_asset_id(client):
+    response = client.post(
+        "/api/dev/annotation/assets/99999",  # Asset doesn't exist
+        json={"content": "test"}
+    )
+    assert response.status_code == 422  # ✅ Correct! Field validation failure
+    assert "does not exist" in response.json["message"]
+```
+
+#### Why 422 Not 404?
+
+The route `/api/dev/annotation/assets/<id>` exists (not a 404). The request is processed, but the `AssetIdField` deserializer fails validation when it can't find asset 99999. This is a **field validation error**, hence 422.
+
+#### Test Pattern
+
+```python
+@pytest.mark.parametrize("entity_type,invalid_id", [
+    ("accounts", 99999),
+    ("assets", 99999),
+    ("sensors", 99999),
+])
+def test_annotation_post_invalid_entity_id(client, entity_type, invalid_id):
+    """Field validation returns 422 for non-existent entity IDs"""
+    response = client.post(
+        f"/api/dev/annotation/{entity_type}/{invalid_id}",
+        json={"content": "test annotation"}
+    )
+    assert response.status_code == 422  # Field validation error
+    assert "does not exist" in response.json["message"].lower()
+```
+
+#### When You Get 404 vs 422
+
+```python
+# 404: Route doesn't exist
+response = client.get("/api/dev/nonexistent-endpoint")
+assert response.status_code == 404
+
+# 422: Field validation fails (route exists, data invalid)
+response = client.post("/api/dev/annotation/assets/99999", json={"content": "test"})
+assert response.status_code == 422
+
+# 201: Everything valid
+response = client.post("/api/dev/annotation/assets/1", json={"content": "test"})
+assert response.status_code == 201  # Created
+```
+
+**Related FlexMeasures patterns**: Marshmallow schema validation, webargs error handling, REST API conventions
+
 ### Installation and Setup
 
 Tests require PostgreSQL with specific credentials:
@@ -189,6 +520,253 @@ This file contains all necessary steps for:
 
 If setup steps fail or are unclear, escalate to the Tooling & CI Specialist.
 
+## Test Execution Workflow (CRITICAL)
+
+**This section documents the MANDATORY workflow for running tests in FlexMeasures.**
+
+### The Problem (Session 2026-02-10)
+
+During the annotation API implementation session, tests were written but NOT executed. The agent attempted to run tests but failed with PostgreSQL connection errors. Root cause: skipped the proper environment setup steps from `.github/workflows/copilot-setup-steps.yml`.
+
+**Anti-pattern**: Assuming the test environment is ready without verification.
+
+### The Solution: Follow the Setup Workflow
+
+Before running any tests, ALWAYS execute this complete setup sequence:
+
+#### Step 1: Setup PostgreSQL Database
+
+```bash
+# Install PostgreSQL (if not already installed)
+sudo apt-get update
+sudo apt-get install -y postgresql postgresql-contrib libpq-dev
+
+# Start PostgreSQL service
+sudo service postgresql start
+
+# Drop existing test database/user for clean setup
+sudo -u postgres psql -c "DROP DATABASE IF EXISTS flexmeasures_test;"
+sudo -u postgres psql -c "DROP USER IF EXISTS flexmeasures_test;"
+
+# Create test user with password
+sudo -u postgres psql -c "CREATE USER flexmeasures_test WITH PASSWORD 'flexmeasures_test';"
+
+# Create test database owned by test user
+sudo -u postgres psql -c "CREATE DATABASE flexmeasures_test OWNER flexmeasures_test;"
+
+# Grant CREATEDB privilege (needed for test isolation)
+sudo -u postgres psql -c "ALTER USER flexmeasures_test CREATEDB;"
+
+# Load PostgreSQL extensions (optional, for full feature support)
+sudo -u postgres psql -U flexmeasures_test -d flexmeasures_test -f ci/load-psql-extensions.sql || echo "Extensions loaded or not available"
+```
+
+#### Step 2: Setup Redis (for job queuing)
+
+```bash
+# Install and start Redis
+sudo apt-get install -y redis-server
+sudo service redis-server start
+```
+
+#### Step 3: Install Python Dependencies
+
+```bash
+# Install pip-tools
+pip3 install -q "pip-tools>=7.2"
+
+# Get Python version (major.minor format)
+PYV=$(python -c "import sys;t='{v[0]}.{v[1]}'.format(v=list(sys.version_info[:2]));sys.stdout.write(t)")
+
+# Install pinned dependencies for testing
+pip-sync requirements/${PYV}/app.txt requirements/${PYV}/test.txt
+
+# Install FlexMeasures in editable mode
+pip install -e .
+```
+
+#### Step 4: Set Environment Variables
+
+```bash
+# Set testing environment
+export FLEXMEASURES_ENV=testing
+
+# Set database URL for PostgreSQL
+export SQLALCHEMY_DATABASE_URI=postgresql://flexmeasures_test:flexmeasures_test@localhost/flexmeasures_test
+
+# Set Redis URL for job queuing
+export FLEXMEASURES_REDIS_URL=redis://localhost:6379/0
+```
+
+#### Step 5: Verify Setup
+
+```bash
+# Check PostgreSQL connection
+psql -U flexmeasures_test -d flexmeasures_test -c "SELECT version();"
+
+# Check Redis connection
+redis-cli ping
+
+# Verify FlexMeasures can be imported
+python -c "import flexmeasures; print('FlexMeasures installed successfully')"
+```
+
+#### Step 6: Run Tests
+
+```bash
+# Run all tests
+pytest
+
+# Run specific test file with verbose output
+pytest path/to/test_file.py -v
+
+# Run specific test function
+pytest path/to/test_file.py::test_function_name -v
+
+# Run tests matching a pattern
+pytest -k "annotation" -v
+```
+
+### Verification Checklist
+
+Before claiming tests pass, verify:
+
+- ✅ PostgreSQL service is running (`sudo service postgresql status`)
+- ✅ Test database exists (`psql -U flexmeasures_test -l`)
+- ✅ Redis is running (`redis-cli ping` returns "PONG")
+- ✅ Environment variables are set (`echo $FLEXMEASURES_ENV`)
+- ✅ Tests execute (not skipped due to missing dependencies)
+- ✅ Test output shows actual pass/fail status
+- ✅ No unexpected warnings or connection errors
+
+### Common Failure Modes
+
+| Error | Root Cause | Solution |
+|-------|------------|----------|
+| `FATAL: role "flexmeasures_test" does not exist` | PostgreSQL user not created | Run Step 1 (PostgreSQL setup) |
+| `FATAL: database "flexmeasures_test" does not exist` | Test database not created | Run Step 1 (PostgreSQL setup) |
+| `could not connect to server: Connection refused` | PostgreSQL not running | `sudo service postgresql start` |
+| `No module named 'flexmeasures'` | Package not installed | Run Step 3 (install dependencies) |
+| `ImportError: No module named 'pytest'` | Test dependencies not installed | Run Step 3 (install dependencies) |
+| `redis.exceptions.ConnectionError` | Redis not running | `sudo service redis-server start` |
+
+### API Test Patterns Learned (Session 2026-02-10)
+
+When writing API tests for FlexMeasures:
+
+#### 1. Using `setup_api_fresh_test_data` Fixture
+
+For tests that need fresh API test data (accounts, users, assets, sensors):
+
+```python
+def test_create_annotation(
+    client,
+    setup_api_fresh_test_data,
+    requesting_user
+):
+    """Test creating an annotation via API."""
+    # setup_api_fresh_test_data provides:
+    # - test_prosumer_user_2 (account-admin with write access)
+    # - test_battery (asset with sensors)
+    # - Fresh database state for each test
+```
+
+#### 2. Parametrized Permission Tests
+
+Test different user roles with parametrized fixtures:
+
+```python
+@pytest.mark.parametrize(
+    "requesting_user",
+    [
+        pytest.param("test_prosumer_user_2", id="account-admin"),
+        pytest.param("test_supplier_user_4", id="consultant"),
+    ],
+    indirect=True,
+)
+def test_annotation_permissions(client, setup_api_fresh_test_data, requesting_user):
+    """Test annotation access for different user roles."""
+    # Test passes for users with appropriate permissions
+```
+
+#### 3. Idempotency Testing Pattern
+
+Test that repeated identical requests behave correctly:
+
+```python
+def test_create_annotation_idempotency(client, setup_api_fresh_test_data, requesting_user):
+    """Test that creating the same annotation twice is handled correctly."""
+    annotation_data = {...}
+    
+    # First POST - should create (201 Created)
+    response1 = client.post(url, json=annotation_data)
+    assert response1.status_code == 201
+    
+    # Second POST - should detect duplicate (200 OK or 409 Conflict)
+    response2 = client.post(url, json=annotation_data)
+    assert response2.status_code in (200, 409)
+```
+
+#### 4. Testing Multiple Entity Types
+
+When an API endpoint applies to multiple entity types (accounts, assets, sensors):
+
+```python
+@pytest.mark.parametrize(
+    "entity_type,entity_fixture",
+    [
+        ("accounts", "prosumer_account"),
+        ("assets", "test_battery"),
+        ("sensors", "power_sensor"),
+    ],
+)
+def test_annotations_for_entity(
+    client,
+    setup_api_fresh_test_data,
+    requesting_user,
+    entity_type,
+    entity_fixture,
+    request
+):
+    """Test annotations work for all entity types."""
+    entity = request.getfixturevalue(entity_fixture)
+    url = f"/api/dev/{entity_type}/{entity.id}/annotations"
+    # ... test logic
+```
+
+#### 5. Validation Error Testing
+
+Test that API validates input correctly:
+
+```python
+def test_create_annotation_invalid_data(client, setup_api_fresh_test_data, requesting_user):
+    """Test validation of annotation data."""
+    invalid_data = {
+        "content": "",  # Empty content should fail
+        "source": "test-source"
+    }
+    response = client.post(url, json=invalid_data)
+    assert response.status_code == 422  # Unprocessable Entity
+    assert "content" in response.json["message"]
+```
+
+### Test Execution Anti-Patterns
+
+❌ **Don't**: Run syntax checks only (`python -m py_compile test_file.py`)
+✅ **Do**: Run actual pytest execution (`pytest test_file.py -v`)
+
+❌ **Don't**: Assume PostgreSQL is running
+✅ **Do**: Check service status before running tests
+
+❌ **Don't**: Skip environment variable setup
+✅ **Do**: Export all required variables (FLEXMEASURES_ENV, SQLALCHEMY_DATABASE_URI, etc.)
+
+❌ **Don't**: Claim "tests pass" without showing pytest output
+✅ **Do**: Capture and verify actual test results (passed/failed counts)
+
+❌ **Don't**: Ignore connection errors and move on
+✅ **Do**: Debug and fix setup issues before proceeding
+
 ## Running Tests in FlexMeasures Dev Environment
 
 ### Critical Requirement: Actually Run Tests
diff --git a/.github/agents/tooling-ci-specialist.md b/.github/agents/tooling-ci-specialist.md
index 7b9f45d701..790a9190f6 100644
--- a/.github/agents/tooling-ci-specialist.md
+++ b/.github/agents/tooling-ci-specialist.md
@@ -75,6 +75,115 @@ Keep FlexMeasures automation reliable and maintainable by reviewing GitHub Actio
 - [ ] **Fail-fast**: Usually false for comprehensive testing
 - [ ] **Coverage**: One Python version runs coverage
 
+### Pre-commit Hook Execution (CRITICAL)
+
+**Every commit MUST pass pre-commit hooks BEFORE being committed.**
+
+This is mandatory. Committing code that fails pre-commit hooks is a process failure.
+
+#### Why This Matters
+
+Pre-commit hooks enforce code quality standards:
+- **Flake8**: Catches linting errors (unused imports, complexity, style violations)
+- **Black**: Ensures consistent code formatting
+- **Mypy**: Validates type annotations
+
+Code that bypasses pre-commit:
+- Fails in CI (wastes resources)
+- Forces maintainers to fix formatting
+- Creates noisy review feedback
+- Delays PR merge
+
+#### Execution Requirements
+
+**Before ANY commit:**
+
+1. **Install pre-commit**:
+   ```bash
+   pip install pre-commit
+   pre-commit install  # Install git hooks (optional but recommended)
+   ```
+
+2. **Run all hooks**:
+   ```bash
+   pre-commit run --all-files
+   ```
+
+3. **Verify zero failures**:
+   - ✅ All hooks pass
+   - ✅ No files modified by hooks (or modifications committed)
+   - ✅ No errors from flake8, black, or mypy
+
+4. **Document execution**:
+   ```
+   Pre-commit verification:
+   - Command: pre-commit run --all-files
+   - Result: All hooks passed
+   - Modified files: None (or included in commit)
+   ```
+
+#### Responsibility Assignment
+
+**Who runs pre-commit:**
+- **During code changes**: Agent making changes runs pre-commit before committing
+- **Before PR close**: Review Lead verifies pre-commit execution
+- **In PR review**: Tooling & CI Specialist validates config matches CI
+
+**Enforcement:**
+- Review Lead's session close checklist includes pre-commit verification
+- Review Lead cannot close session without pre-commit evidence
+- If pre-commit fails, agent must fix all issues before proceeding
+
+#### Common Failures and Fixes
+
+**Flake8 failures:**
+```bash
+# Common issues:
+# - E501: Line too long (black should handle this)
+# - F401: Unused import (remove import)
+# - C901: Function too complex (refactor)
+# - W503: Line break before binary operator (ignore, conflicts with black)
+
+# Quick check:
+flake8 path/to/file.py
+```
+
+**Black failures:**
+```bash
+# Auto-fix formatting:
+black path/to/file.py
+
+# Or format entire codebase:
+black .
+```
+
+**Mypy failures:**
+```bash
+# Type annotation required
+# Manual fix needed:
+# - Add type hints to function signatures
+# - Fix type mismatches
+# - Add # type: ignore comments with justification
+
+# Run mypy:
+ci/run_mypy.sh
+```
+
+#### Integration with Review Lead
+
+**Review Lead checklist items:**
+- [ ] Pre-commit hooks installed
+- [ ] All hooks pass: `pre-commit run --all-files`
+- [ ] Zero failures from flake8, black, mypy
+- [ ] If hooks modified files, changes committed
+
+**Evidence required:**
+- Show pre-commit output confirming all hooks passed
+- Or confirm: "Pre-commit verified: all hooks passed"
+
+**Enforcement:**
+Review Lead MUST verify pre-commit execution before closing session.
+
 ### Agent Environment Setup
 
 File: **`.github/workflows/copilot-setup-steps.yml`**
diff --git a/documentation/api/change_log.rst b/documentation/api/change_log.rst
index 6b5aa61a0e..808013292c 100644
--- a/documentation/api/change_log.rst
+++ b/documentation/api/change_log.rst
@@ -5,17 +5,21 @@ API change log
 
 .. note:: The FlexMeasures API follows its own versioning scheme. This is also reflected in the URL (e.g. `/api/v3_0`), allowing developers to upgrade at their own pace.
 
-v3.0-29 | 2025-12-30
+v3.0-29 | 2026-02-10
 """"""""""""""""""""
 
-Added two new forecasting API endpoints:
+- Added two new forecasting API endpoints:
 
-* `POST /sensors/<id>/forecasts/trigger` — queue forecasting jobs for a sensor
-* `GET /sensors/<id>/forecasts/<uuid>` — retrieve job status and forecast results
+  * `POST /sensors/<id>/forecasts/trigger` — queue forecasting jobs for a sensor
+  * `GET /sensors/<id>/forecasts/<uuid>` — retrieve job status and forecast results
 
-These endpoints enable programmatic triggering and retrieval of forecasts via the REST API.
+  These endpoints enable programmatic triggering and retrieval of forecasts via the REST API.
 
-Also:
+- Added three new API endpoints to create annotations for accounts, assets, and sensors:
+
+  * `POST /accounts/(id)/annotations <api/v3_0.html#post--api-v3_0-accounts-id-annotations>`_
+  * `POST /assets/(id)/annotations <api/v3_0.html#post--api-v3_0-assets-id-annotations>`_
+  * `POST /sensors/(id)/annotations <api/v3_0.html#post--api-v3_0-sensors-id-annotations>`_
 
 - Support saving the aggregate power schedule by referencing a power sensor in the ``flex-context`` (new field ``aggregate-power``).
 - Added ``root`` and ``depth`` fields to the `/assets` (GET) endpoint for listing assets, to allow selecting descendants of a given root asset up to a given depth.
diff --git a/documentation/changelog.rst b/documentation/changelog.rst
index 43a60dc642..32617f7692 100644
--- a/documentation/changelog.rst
+++ b/documentation/changelog.rst
@@ -12,6 +12,7 @@ v0.31.0 | February XX, 2026
 New features
 -------------
 * Improve CSV upload validation by inferring the intended base resolution even when data contains valid gaps, instead of requiring perfectly regular timestamps [see `PR #1918 <https://www.github.com/FlexMeasures/flexmeasures/pull/1918>`_]
+* New API endpoints to create annotations for accounts, assets, and sensors: `[POST] /annotations/accounts/(id) <api/v3_0.html#post--api-v3_0-annotations-accounts-id>`_, `[POST] /annotations/assets/(id) <api/v3_0.html#post--api-v3_0-annotations-assets-id>`_ and `[POST] /annotations/sensors/(id) <api/v3_0.html#post--api-v3_0-annotations-sensors-id>`_ [see `PR #1968 <https://github.com/FlexMeasures/flexmeasures/pull/1968>`_]
 * New forecasting API endpoints `[POST] /sensors/(id)/forecasts/trigger <api/v3_0.html#post--api-v3_0-sensors-id-forecasts-trigger>`_ and `[GET] /sensors/(id)/forecasts/(uuid) <api/v3_0.html#get--api-v3_0-sensors-id-forecasts-uuid>`_ to forecast sensor data [see `PR #1813 <https://www.github.com/FlexMeasures/flexmeasures/pull/1813>`_ and `PR #1823 <https://www.github.com/FlexMeasures/flexmeasures/pull/1823>`_]
 * Support setting a resolution when triggering a schedule via the API or CLI [see `PR #1857 <https://www.github.com/FlexMeasures/flexmeasures/pull/1857>`_]
 * Support variable peak pricing and changes in commitment baselines [see `PR #1835 <https://www.github.com/FlexMeasures/flexmeasures/pull/1835>`_]
diff --git a/documentation/concepts/annotations.rst b/documentation/concepts/annotations.rst
new file mode 100644
index 0000000000..512741f6dc
--- /dev/null
+++ b/documentation/concepts/annotations.rst
@@ -0,0 +1,432 @@
+.. _annotations:
+
+Annotations
+===========
+
+Annotations allow you to attach contextual information to accounts, assets, or sensors over specific time periods. 
+They help document important events, holidays, alerts, maintenance windows, or any other information that adds context to your time series data.
+
+
+What are annotations?
+---------------------
+
+An annotation is a piece of metadata associated with a specific entity (account, asset, or sensor) during a defined time period.
+Each annotation includes:
+
+- **Content**: Descriptive text (up to 1024 characters)
+- **Time range**: Start and end times defining when the annotation applies
+- **Type**: Category of the annotation (label, holiday, alert, warning, error, or feedback)
+- **Prior**: Timestamp when the annotation was recorded
+- **Source**: The data source that created the annotation (typically a user or automated system)
+
+
+Use cases
+---------
+
+Annotations are particularly useful for:
+
+**Forecasting and Scheduling**
+    Holiday annotations help forecasting algorithms understand when energy consumption patterns deviate from normal patterns.
+    FlexMeasures can automatically import public holidays using the ``flexmeasures add holidays`` command.
+
+**Data Quality Tracking**
+    Mark periods with known sensor issues, data gaps, or quality problems using ``error`` or ``warning`` type annotations.
+    This helps analysts understand why certain data points might be unreliable.
+
+**Operational Documentation**
+    Document maintenance windows, system changes, or configuration updates with ``label`` type annotations.
+    Record feedback about system behavior for future reference.
+
+**Alert Management**
+    Create ``alert`` type annotations for active issues requiring attention.
+    When resolved, the status changes and the annotation becomes part of the operational history.
+
+**Asset Context**
+    Mark special events at the asset level (e.g., building renovations, equipment upgrades).
+    These annotations appear in all related sensor charts for that asset.
+
+
+Annotation types
+----------------
+
+FlexMeasures supports six annotation types:
+
+``label``
+    General-purpose annotations for documentation and notes. Default type if not specified.
+
+``holiday``
+    Public or organizational holidays that may affect energy patterns. Used by forecasting algorithms.
+
+``alert``
+    Active warnings requiring attention or action.
+
+``warning``
+    Informational warnings about potential issues or degraded conditions.
+
+``error``
+    Markers for periods with data quality issues, sensor failures, or system errors.
+
+``feedback``
+    User feedback or observations about system behavior or data.
+
+
+Creating annotations via API
+-----------------------------
+
+The annotation API provides three POST endpoints:
+
+- ``POST /api/v3_0/accounts/<id>/annotations`` - Annotate an account
+- ``POST /api/v3_0/assets/<id>/annotations`` - Annotate an asset
+- ``POST /api/v3_0/sensors/<id>/annotations`` - Annotate a sensor
+
+
+**Authentication**
+
+All annotation endpoints require authentication. Include your access token in the request header:
+
+.. code-block:: json
+
+    {
+        "Authorization": "<your-access-token>"
+    }
+
+See :ref:`api_auth` for details on obtaining an access token.
+
+
+**Permissions**
+
+You need ``create-children`` permission on the target entity (account, asset, or sensor) to create annotations.
+The permission system ensures users can only annotate resources they have access to.
+
+See :ref:`authorization` for more details on FlexMeasures authorization.
+
+
+**Request Format**
+
+All annotation endpoints accept the same request body format:
+
+.. code-block:: json
+
+    {
+        "content": "Sensor maintenance performed",
+        "start": "2024-12-15T09:00:00+01:00",
+        "end": "2024-12-15T11:00:00+01:00",
+        "type": "label",
+        "prior": "2024-12-15T08:45:00+01:00"
+    }
+
+**Required fields:**
+
+- ``content`` (string): Description of the annotation. Maximum 1024 characters.
+- ``start`` (ISO 8601 datetime): When the annotated period begins. Must include timezone.
+- ``end`` (ISO 8601 datetime): When the annotated period ends. Must be after ``start``. Must include timezone.
+
+**Optional fields:**
+
+- ``type`` (string): One of ``"alert"``, ``"holiday"``, ``"label"``, ``"feedback"``, ``"warning"``, ``"error"``. Defaults to ``"label"``.
+- ``prior`` (ISO 8601 datetime): When the annotation was recorded. Defaults to current time if omitted.
+
+**Response Format**
+
+Successful requests return the created annotation:
+
+.. code-block:: json
+
+    {
+        "id": 123,
+        "content": "Sensor maintenance performed",
+        "start": "2024-12-15T09:00:00+01:00",
+        "end": "2024-12-15T11:00:00+01:00",
+        "type": "label",
+        "prior": "2024-12-15T08:45:00+01:00",
+        "source": 42
+    }
+
+The ``source`` identifies the data source that created the annotation (typically corresponds to the authenticated user).
+
+
+**Status Codes**
+
+- ``201 Created``: A new annotation was created
+- ``200 OK``: An identical annotation already exists (idempotent behavior)
+- ``400 Bad Request``: Invalid request data (e.g., end before start, missing required fields)
+- ``401 Unauthorized``: Missing or invalid authentication token
+- ``403 Forbidden``: User lacks permission to annotate this entity
+- ``404 Not Found``: The specified account, asset, or sensor does not exist
+- ``422 Unprocessable Entity``: Request data fails validation
+- ``500 Internal Server Error``: Server error during annotation creation
+
+
+Examples
+--------
+
+**Example 1: Mark a holiday on an asset**
+
+.. code-block:: bash
+
+    curl -X POST "https://company.flexmeasures.io/api/v3_0/assets/5/annotations" \
+      -H "Authorization: YOUR_TOKEN_HERE" \
+      -H "Content-Type: application/json" \
+      -d '{
+        "content": "Christmas Day - reduced operations",
+        "start": "2024-12-25T00:00:00+01:00",
+        "end": "2024-12-26T00:00:00+01:00",
+        "type": "holiday"
+      }'
+
+**Response:**
+
+.. code-block:: json
+
+    {
+        "id": 456,
+        "content": "Christmas Day - reduced operations",
+        "start": "2024-12-25T00:00:00+01:00",
+        "end": "2024-12-26T00:00:00+01:00",
+        "type": "holiday",
+        "prior": "2024-12-15T10:30:00+01:00",
+        "source": 12
+    }
+
+**Status:** ``201 Created``
+
+
+**Example 2: Document a sensor error**
+
+.. code-block:: bash
+
+    curl -X POST "https://company.flexmeasures.io/api/v3_0/sensors/42/annotations" \
+      -H "Authorization: YOUR_TOKEN_HERE" \
+      -H "Content-Type: application/json" \
+      -d '{
+        "content": "Temperature sensor malfunction - readings unreliable",
+        "start": "2024-12-10T14:30:00+01:00",
+        "end": "2024-12-10T16:45:00+01:00",
+        "type": "error"
+      }'
+
+**Response:**
+
+.. code-block:: json
+
+    {
+        "id": 457,
+        "content": "Temperature sensor malfunction - readings unreliable",
+        "start": "2024-12-10T14:30:00+01:00",
+        "end": "2024-12-10T16:45:00+01:00",
+        "type": "error",
+        "prior": "2024-12-15T10:35:00+01:00",
+        "source": 12
+    }
+
+**Status:** ``201 Created``
+
+
+**Example 3: Python client example**
+
+.. code-block:: python
+
+    import requests
+    from datetime import datetime, timezone, timedelta
+
+    # Configuration
+    FLEXMEASURES_URL = "https://company.flexmeasures.io"
+    ACCESS_TOKEN = "your-access-token-here"
+    
+    # Create annotation for an account
+    annotation_data = {
+        "content": "Office closed for renovation",
+        "start": "2025-01-15T00:00:00+01:00",
+        "end": "2025-01-22T00:00:00+01:00",
+        "type": "label"
+    }
+    
+    response = requests.post(
+        f"{FLEXMEASURES_URL}/api/v3_0/accounts/3/annotations",
+        headers={
+            "Authorization": ACCESS_TOKEN,
+            "Content-Type": "application/json"
+        },
+        json=annotation_data
+    )
+    
+    if response.status_code in (200, 201):
+        annotation = response.json()
+        print(f"Annotation created with ID: {annotation['id']}")
+        if response.status_code == 200:
+            print("(Annotation already existed)")
+    else:
+        print(f"Error: {response.status_code}")
+        print(response.json())
+
+
+**Example 4: Using Python helper function**
+
+.. code-block:: python
+
+    from datetime import datetime, timedelta, timezone
+    import requests
+    
+    def create_annotation(entity_type, entity_id, content, start, end,
+                         annotation_type="label", prior=None,
+                         base_url="https://company.flexmeasures.io",
+                         token=None):
+        """Create an annotation via the FlexMeasures API.
+        
+        :param entity_type:     One of "accounts", "assets", "sensors"
+        :param entity_id:       ID of the entity to annotate
+        :param content:         Annotation text (max 1024 chars)
+        :param start:           Start datetime (ISO 8601 string or datetime object)
+        :param end:             End datetime (ISO 8601 string or datetime object)
+        :param annotation_type: Type of annotation (default: "label")
+        :param prior:           Optional recording time (ISO 8601 string or datetime object)
+        :param base_url:        FlexMeasures instance URL
+        :param token:           API access token
+        :return:                Response JSON and status code tuple
+        """
+        # Convert datetime objects to ISO 8601 strings if needed
+        if isinstance(start, datetime):
+            start = start.isoformat()
+        if isinstance(end, datetime):
+            end = end.isoformat()
+        if isinstance(prior, datetime):
+            prior = prior.isoformat()
+        
+        url = f"{base_url}/api/v3_0/{entity_type}/{entity_id}/annotations"
+        
+        payload = {
+            "content": content,
+            "start": start,
+            "end": end,
+            "type": annotation_type
+        }
+        
+        if prior:
+            payload["prior"] = prior
+        
+        headers = {
+            "Authorization": token,
+            "Content-Type": "application/json"
+        }
+        
+        response = requests.post(url, headers=headers, json=payload)
+        return response.json(), response.status_code
+    
+    # Example usage
+    now = datetime.now(timezone.utc)
+    result, status = create_annotation(
+        entity_type="sensors",
+        entity_id=123,
+        content="Scheduled maintenance",
+        start=now + timedelta(hours=2),
+        end=now + timedelta(hours=4),
+        annotation_type="label",
+        token="your-token-here"
+    )
+    
+    print(f"Status: {status}")
+    print(f"Annotation ID: {result.get('id')}")
+
+
+Idempotency
+-----------
+
+The annotation API is idempotent. If you POST the same annotation data twice (same content, start time, recording time, source, and type),
+the API will:
+
+1. On first request: Create the annotation and return ``201 Created``
+2. On subsequent identical requests: Return the existing annotation with ``200 OK``
+
+This idempotency is based on a database uniqueness constraint on ``(content, start, prior, source, type)``.
+
+**Why is this useful?**
+
+- Safe to retry failed requests without creating duplicates
+- Simplifies client code (no need to check if annotation exists first)
+- Automated systems can safely re-run annotation creation scripts
+
+**Note:** Annotations with the same content but different ``end`` times are considered different annotations. 
+The ``end`` field is not part of the uniqueness constraint.
+
+
+Creating annotations via CLI
+-----------------------------
+
+FlexMeasures provides CLI commands for creating annotations:
+
+**General annotation command:**
+
+.. code-block:: bash
+
+    flexmeasures add annotation \
+      --content "Maintenance window" \
+      --start "2024-12-20T10:00:00+01:00" \
+      --end "2024-12-20T12:00:00+01:00" \
+      --type label \
+      --account-id 1
+
+You can target accounts, assets, or sensors:
+
+.. code-block:: bash
+
+    # Annotate a specific sensor
+    flexmeasures add annotation --sensor-id 42 --content "..." --start "..." --end "..."
+    
+    # Annotate a specific asset
+    flexmeasures add annotation --asset-id 5 --content "..." --start "..." --end "..."
+    
+    # Annotate an account
+    flexmeasures add annotation --account-id 1 --content "..." --start "..." --end "..."
+
+
+**Holiday import command:**
+
+FlexMeasures can automatically import public holidays using the `workalendar <https://github.com/workalendar/workalendar>`_ library:
+
+.. code-block:: bash
+
+    # Add holidays for a specific account
+    flexmeasures add holidays --account-id 1 --year 2025 --country NL
+    
+    # Add holidays for an asset
+    flexmeasures add holidays --asset-id 5 --year 2025 --country DE
+
+See ``flexmeasures add holidays --help`` for available countries and options.
+
+
+Viewing annotations
+-------------------
+
+**In the FlexMeasures UI:**
+
+Annotations appear automatically in:
+
+- **Sensor charts**: Individual sensor data views show all annotations linked to that sensor and its asset
+- **Not yet in asset charts**: these might show all annotations linked to that asset, its parent assets, and its account
+
+Annotations are displayed as vertical bands, with their text contents displayed on hover (select to keep it visible).
+
+**Via API queries:**
+
+When fetching sensor data through chart endpoints, you can control which annotations are included:
+
+.. code-block:: bash
+
+    GET /api/dev/sensor/42/chart?include_sensor_annotations=true&include_asset_annotations=true&include_account_annotations=true
+
+This allows you to:
+
+- Include only sensor-specific annotations
+- Add broader context from asset and account annotations  
+- Customize which annotation layers are visible
+
+See :ref:`dev` for complete API documentation for sensor charts.
+
+
+See also
+--------
+
+- :ref:`v3_0` - Complete API documentation including annotation endpoints
+- :ref:`datamodel` - Overview of the FlexMeasures data model including annotations
+- :ref:`cli` - Command-line interface documentation
+- :ref:`authorization` - Authentication and authorization details
diff --git a/documentation/concepts/data-model.rst b/documentation/concepts/data-model.rst
index 0983025288..46bcb859f0 100644
--- a/documentation/concepts/data-model.rst
+++ b/documentation/concepts/data-model.rst
@@ -97,6 +97,58 @@ Each belief links to a sensor and a data source. Here are two examples:
 - A thermal demand sensor containing forecasts (data source of type "forecast", e.g. heating usage forecast sent to FlexMeasures or made by FlexMeasures) and measurements (sent into FlexMeasures, data source type "user").
 
 
+Annotations
+-----------
+
+Annotations allow you to attach metadata and contextual information to accounts, assets, or sensors over specific time periods.
+They are useful for marking important events, holidays, alerts, or any other information that helps understand your data.
+
+Each annotation has:
+
+- **Content**: Text describing the annotation (max 1024 characters)
+- **Time range**: A start and end time for when the annotation applies
+- **Type**: The category of annotation (see types below)
+- **Belief time**: When the annotation was created or became known
+- **Source**: Who or what created the annotation (e.g., a user or automated system)
+
+**Annotation Types**
+
+FlexMeasures supports several annotation types:
+
+- **label**: General-purpose annotations, useful for marking specific periods with custom notes
+- **holiday**: Public or organizational holidays that may affect energy usage patterns
+- **alert**: Active warnings that require attention
+- **warning**: Informational warnings about potential issues
+- **error**: Markers for periods with data quality issues or system errors
+- **feedback**: User feedback or notes about system behavior
+
+**Use Cases**
+
+Annotations are particularly useful for:
+
+- Marking holidays that affect energy consumption patterns (used by forecasting algorithms)
+- Documenting known data quality issues or sensor outages
+- Recording maintenance windows or system changes
+- Adding context to unusual patterns in your data
+- Tracking alerts and their resolution status
+
+**Creating Annotations**
+
+Annotations can be created via:
+
+- The :ref:`API <v3_0>` (see POST endpoints for accounts, assets, and sensors)
+- The CLI command ``flexmeasures add annotation``
+- The CLI command ``flexmeasures add holidays`` for automatic holiday import
+
+**Viewing Annotations**
+
+Annotations appear in:
+
+- Individual sensor charts in the FlexMeasures UI
+- API responses when querying chart data with annotation flags
+
+More information, including code examples, is available in :ref:`annotations`.
+
 
 Accounts & Users
 ----------------
diff --git a/documentation/index.rst b/documentation/index.rst
index 36935d1738..4071251a3a 100644
--- a/documentation/index.rst
+++ b/documentation/index.rst
@@ -190,6 +190,7 @@ In :ref:`getting_started`, we have some helpful tips how to dive into this docum
     concepts/data-model
     concepts/security_auth
     concepts/device_scheduler
+    concepts/annotations
 
 
 .. toctree::
diff --git a/flexmeasures/api/v3_0/__init__.py b/flexmeasures/api/v3_0/__init__.py
index 3f10035312..9edbc5f079 100644
--- a/flexmeasures/api/v3_0/__init__.py
+++ b/flexmeasures/api/v3_0/__init__.py
@@ -4,6 +4,7 @@
 
 from pathlib import Path
 from typing import Any, Type
+import inspect
 
 from flask import Flask
 import json
@@ -27,11 +28,13 @@
     AssetAPIQuerySchema,
     DefaultAssetViewJSONSchema,
 )
+from flexmeasures.data.schemas.annotations import AnnotationSchema
 from flexmeasures.data.schemas.generic_assets import GenericAssetSchema as AssetSchema
 from flexmeasures.data.schemas.sensors import QuantitySchema, TimeSeriesSchema
 from flexmeasures.data.schemas.account import AccountSchema
 from flexmeasures.api.v3_0.accounts import AccountAPIQuerySchema
 from flexmeasures.api.v3_0.users import UserAPIQuerySchema, AuthRequestSchema
+from flexmeasures.utils.doc_utils import rst_to_openapi
 
 
 def register_at(app: Flask):
@@ -140,6 +143,7 @@ def create_openapi_specs(app: Flask):
         ("UserAPIQuerySchema", UserAPIQuerySchema),
         ("AssetAPIQuerySchema", AssetAPIQuerySchema),
         ("AssetSchema", AssetSchema),
+        ("AnnotationSchema", AnnotationSchema),
         ("DefaultAssetViewJSONSchema", DefaultAssetViewJSONSchema),
         ("AccountSchema", AccountSchema(partial=True)),
         ("AccountAPIQuerySchema", AccountAPIQuerySchema),
@@ -160,6 +164,13 @@ def create_openapi_specs(app: Flask):
 
             view_function = app.view_functions[endpoint_name]
 
+            # Make sure rst docstring suits OpenAPI
+            target = view_function
+            if inspect.ismethod(view_function):
+                target = view_function.__func__
+            if target.__doc__:
+                target.__doc__ = rst_to_openapi(target.__doc__)
+
             # Document all API endpoints under /api or root /
             if rule.rule.startswith("/api/") or rule.rule == "/":
                 try:
diff --git a/flexmeasures/api/v3_0/accounts.py b/flexmeasures/api/v3_0/accounts.py
index 292822ba2e..ddf9b17712 100644
--- a/flexmeasures/api/v3_0/accounts.py
+++ b/flexmeasures/api/v3_0/accounts.py
@@ -8,15 +8,16 @@
 from sqlalchemy import or_, select, func
 from flask_sqlalchemy.pagination import SelectPagination
 
-
 from flexmeasures.auth.policy import user_has_admin_access
 from flexmeasures.auth.decorators import permission_required_for_context
+from flexmeasures.data.models.annotations import Annotation, get_or_create_annotation
 from flexmeasures.data.models.audit_log import AuditLog
 from flexmeasures.data.models.user import Account, User
 from flexmeasures.data.models.generic_assets import GenericAsset
 from flexmeasures.data.services.accounts import get_accounts, get_audit_log_records
 from flexmeasures.api.common.schemas.users import AccountIdField
 from flexmeasures.data.schemas.account import AccountSchema
+from flexmeasures.data.schemas.annotations import AnnotationSchema
 from flexmeasures.utils.time_utils import server_now
 from flexmeasures.api.common.schemas.users import AccountAPIQuerySchema
 
@@ -31,6 +32,7 @@
 account_schema = AccountSchema()
 accounts_schema = AccountSchema(many=True)
 partial_account_schema = AccountSchema(partial=True)
+annotation_schema = AnnotationSchema()
 
 
 class AccountAPI(FlaskView):
@@ -425,3 +427,61 @@ def auditlog(self, id: int, account: Account):
             for log in audit_logs
         ]
         return audit_logs, 200
+
+    @route("/<id>/annotations", methods=["POST"])
+    @use_kwargs({"account": AccountIdField(data_key="id")}, location="path")
+    @use_args(annotation_schema)
+    @permission_required_for_context("create-children", ctx_arg_name="account")
+    def post_annotation(self, annotation: Annotation, id: int, account: Account):
+        """
+        .. :quickref: Accounts; Add an annotation to an account.
+        ---
+        post:
+          summary: Creates a new account annotation.
+          description: |
+            This endpoint creates a new :ref:`annotation <annotations>` on an account.
+
+          security:
+            - ApiKeyAuth: []
+          parameters:
+            - name: id
+              in: path
+              description: The ID of the account to register the annotation on.
+              required: true
+              schema:
+                type: integer
+                format: int32
+          requestBody:
+            content:
+              application/json:
+                schema: AnnotationSchema
+          responses:
+            200:
+              description: OK
+            201:
+              description: PROCESSED
+            400:
+              description: INVALID_REQUEST
+            401:
+              description: UNAUTHORIZED
+            403:
+              description: INVALID_SENDER
+            422:
+              description: UNPROCESSABLE_ENTITY
+          tags:
+            - Accounts
+            - Annotations
+        """
+
+        # Use get_or_create to handle duplicates gracefully
+        annotation, is_new = get_or_create_annotation(annotation)
+
+        # Link annotation to account
+        if annotation not in account.annotations:
+            account.annotations.append(annotation)
+
+        db.session.commit()
+
+        # Return appropriate status code
+        status_code = 201 if is_new else 200
+        return annotation_schema.dump(annotation), status_code
diff --git a/flexmeasures/api/v3_0/assets.py b/flexmeasures/api/v3_0/assets.py
index d63bbc2dda..8576f70362 100644
--- a/flexmeasures/api/v3_0/assets.py
+++ b/flexmeasures/api/v3_0/assets.py
@@ -35,6 +35,7 @@
 from flexmeasures.data.services.job_cache import NoRedisConfigured
 from flexmeasures.auth.decorators import permission_required_for_context
 from flexmeasures.data import db
+from flexmeasures.data.models.annotations import Annotation, get_or_create_annotation
 from flexmeasures.data.models.user import Account
 from flexmeasures.data.models.audit_log import AssetAuditLog
 from flexmeasures.data.models.generic_assets import GenericAsset, GenericAssetType
@@ -43,6 +44,7 @@
     query_assets_by_search_terms,
 )
 from flexmeasures.data.schemas import AwareDateTimeField
+from flexmeasures.data.schemas.annotations import AnnotationSchema
 from flexmeasures.data.schemas.generic_assets import (
     GenericAssetSchema as AssetSchema,
     GenericAssetIdField as AssetIdField,
@@ -74,6 +76,7 @@
 
 asset_type_schema = AssetTypeSchema()
 asset_schema = AssetSchema()
+annotation_schema = AnnotationSchema()
 # creating this once to avoid recreating it on every request
 default_list_assets_schema = AssetSchema(many=True, only=default_response_fields)
 patch_asset_schema = AssetSchema(partial=True, exclude=["account_id"])
@@ -1527,3 +1530,60 @@ def get_kpis(self, id: int, asset: GenericAsset, start, end):
             }
             kpis.append(kpi_dict)
         return dict(data=kpis), 200
+
+    @route("/<id>/annotations", methods=["POST"])
+    @use_kwargs({"asset": AssetIdField(data_key="id")}, location="path")
+    @use_args(annotation_schema)
+    @permission_required_for_context("create-children", ctx_arg_name="asset")
+    def post_annotation(self, annotation: Annotation, id: int, asset: GenericAsset):
+        """.. :quickref: Assets; Add an annotation to an asset.
+        ---
+        post:
+          summary: Creates a new asset annotation.
+          description: |
+            This endpoint creates a new :ref:`annotation <annotations>` on an asset.
+
+          security:
+            - ApiKeyAuth: []
+          parameters:
+            - name: id
+              in: path
+              description: The ID of the asset to register the annotation on.
+              required: true
+              schema:
+                type: integer
+                format: int32
+          requestBody:
+            content:
+              application/json:
+                schema: AnnotationSchema
+          responses:
+            200:
+              description: OK
+            201:
+              description: PROCESSED
+            400:
+              description: INVALID_REQUEST
+            401:
+              description: UNAUTHORIZED
+            403:
+              description: INVALID_SENDER
+            422:
+              description: UNPROCESSABLE_ENTITY
+          tags:
+            - Assets
+            - Annotations
+        """
+
+        # Use get_or_create to handle duplicates gracefully
+        annotation, is_new = get_or_create_annotation(annotation)
+
+        # Link annotation to asset
+        if annotation not in asset.annotations:
+            asset.annotations.append(annotation)
+
+        db.session.commit()
+
+        # Return appropriate status code
+        status_code = 201 if is_new else 200
+        return annotation_schema.dump(annotation), status_code
diff --git a/flexmeasures/api/v3_0/sensors.py b/flexmeasures/api/v3_0/sensors.py
index a59c11195a..32202326de 100644
--- a/flexmeasures/api/v3_0/sensors.py
+++ b/flexmeasures/api/v3_0/sensors.py
@@ -43,11 +43,13 @@
 from flexmeasures.auth.policy import check_access
 from flexmeasures.auth.decorators import permission_required_for_context
 from flexmeasures.data import db
+from flexmeasures.data.models.annotations import Annotation, get_or_create_annotation
 from flexmeasures.data.models.audit_log import AssetAuditLog
 from flexmeasures.data.models.user import Account
 from flexmeasures.data.models.generic_assets import GenericAsset
 from flexmeasures.data.models.time_series import Sensor, TimedBelief
 from flexmeasures.data.queries.utils import simplify_index
+from flexmeasures.data.schemas.annotations import AnnotationSchema
 from flexmeasures.data.schemas.sensors import (  # noqa F401
     SensorSchema,
     SensorIdField,
@@ -78,6 +80,7 @@
 sensors_schema = SensorSchema(many=True)
 sensor_schema = SensorSchema()
 partial_sensor_schema = SensorSchema(partial=True, exclude=["generic_asset_id"])
+annotation_schema = AnnotationSchema()
 
 
 class SensorKwargsSchema(Schema):
@@ -1815,3 +1818,60 @@ def get_forecast(self, id: int, uuid: str, sensor: Sensor, job_id: str):
 
         d, s = request_processed()
         return dict(**response), s
+
+    @route("/<id>/annotations", methods=["POST"])
+    @use_kwargs({"sensor": SensorIdField(data_key="id")}, location="path")
+    @use_args(annotation_schema)
+    @permission_required_for_context("create-children", ctx_arg_name="sensor")
+    def post_annotation(self, annotation: Annotation, id: int, sensor: Sensor):
+        """.. :quickref: Sensors; Add an annotation to a sensor.
+        ---
+        post:
+          summary: Creates a new sensor annotation.
+          description: |
+            This endpoint creates a new :ref:`annotation <annotations>` on a sensor.
+
+          security:
+            - ApiKeyAuth: []
+          parameters:
+            - name: id
+              in: path
+              description: The ID of the sensor to register the annotation on.
+              required: true
+              schema:
+                type: integer
+                format: int32
+          requestBody:
+            content:
+              application/json:
+                schema: AnnotationSchema
+          responses:
+            200:
+              description: OK
+            201:
+              description: PROCESSED
+            400:
+              description: INVALID_REQUEST
+            401:
+              description: UNAUTHORIZED
+            403:
+              description: INVALID_SENDER
+            422:
+              description: UNPROCESSABLE_ENTITY
+          tags:
+            - Sensors
+            - Annotations
+        """
+
+        # Use get_or_create to handle duplicates gracefully
+        annotation, is_new = get_or_create_annotation(annotation)
+
+        # Link annotation to sensor
+        if annotation not in sensor.annotations:
+            sensor.annotations.append(annotation)
+
+        db.session.commit()
+
+        # Return appropriate status code
+        status_code = 201 if is_new else 200
+        return annotation_schema.dump(annotation), status_code
diff --git a/flexmeasures/api/v3_0/tests/test_annotations.py b/flexmeasures/api/v3_0/tests/test_annotations.py
new file mode 100644
index 0000000000..552d472ab8
--- /dev/null
+++ b/flexmeasures/api/v3_0/tests/test_annotations.py
@@ -0,0 +1,751 @@
+"""
+Tests for the annotation API endpoints (under development).
+
+These tests validate the three POST endpoints for creating annotations:
+- POST /api/v3_0/accounts/<id>/annotations
+- POST /api/v3_0/assets/<id>/annotations
+- POST /api/v3_0/sensors/<id>/annotations
+"""
+
+from __future__ import annotations
+
+import pytest
+from flask import url_for
+from sqlalchemy import select, func
+
+from flexmeasures.data.models.annotations import Annotation
+from flexmeasures.data.models.generic_assets import GenericAsset
+from flexmeasures.data.models.time_series import Sensor
+from flexmeasures.data.models.user import Account
+from flexmeasures.data.services.users import find_user_by_email
+
+
+@pytest.mark.parametrize(
+    "requesting_user, expected_status_code",
+    [
+        (
+            "test_prosumer_user_2@seita.nl",
+            201,
+        ),  # account-admin can annotate own account
+        ("test_admin_user@seita.nl", 201),  # admin can annotate any account
+        ("test_prosumer_user@seita.nl", 403),  # regular user without admin role
+        ("test_dummy_user_3@seita.nl", 403),  # user from different account
+        (None, 401),  # no authentication
+    ],
+    indirect=["requesting_user"],
+)
+def test_post_account_annotation_permissions(
+    client, setup_api_test_data, requesting_user, expected_status_code
+):
+    """Test permission validation for account annotations.
+
+    Validates that:
+    - Account admins can annotate their own account
+    - Platform admins can annotate any account
+    - Regular users without account-admin role cannot annotate
+    - Users from different accounts cannot annotate
+    - Unauthenticated requests are rejected
+    """
+    # Get the Prosumer account ID
+    prosumer_account = client.application.db.session.execute(
+        select(Account).filter_by(name="Test Prosumer Account")
+    ).scalar_one()
+
+    annotation_data = {
+        "content": "Test annotation",
+        "start": "2024-01-01T00:00:00+01:00",
+        "end": "2024-01-01T01:00:00+01:00",
+        "type": "label",
+    }
+
+    response = client.post(
+        url_for("AccountAPI:post_annotation", id=prosumer_account.id),
+        json=annotation_data,
+    )
+
+    assert (
+        response.status_code == expected_status_code
+    ), f"Expected {expected_status_code}, but got {response.status_code} with {response.json}"
+
+    if expected_status_code == 201:
+        # Verify response contains expected fields
+        assert "id" in response.json
+        assert response.json["content"] == "Test annotation"
+        assert response.json["type"] == "label"
+        assert "source" in response.json
+
+        # Verify annotation is linked to account
+        annotation = client.application.db.session.get(Annotation, response.json["id"])
+        assert annotation in prosumer_account.annotations
+
+
+@pytest.mark.parametrize(
+    "requesting_user, asset_name, expected_status_code",
+    [
+        (
+            "test_supplier_user_4@seita.nl",
+            "incineration line",
+            201,
+        ),  # supplier owns the asset
+        (
+            "test_admin_user@seita.nl",
+            "incineration line",
+            201,
+        ),  # admin can annotate any asset
+        (
+            "test_prosumer_user@seita.nl",
+            "incineration line",
+            403,
+        ),  # user doesn't own asset
+        (None, "incineration line", 401),  # no authentication
+    ],
+    indirect=["requesting_user"],
+)
+def test_post_asset_annotation_permissions(
+    client, setup_api_test_data, requesting_user, asset_name, expected_status_code
+):
+    """Test permission validation for asset annotations.
+
+    Validates that:
+    - Asset owners can annotate their assets
+    - Platform admins can annotate any asset
+    - Users without ownership cannot annotate
+    - Unauthenticated requests are rejected
+    """
+    # Get the incineration line asset
+    asset = client.application.db.session.execute(
+        select(GenericAsset).filter_by(name=asset_name)
+    ).scalar_one()
+
+    annotation_data = {
+        "content": "Asset maintenance scheduled",
+        "start": "2024-02-01T00:00:00+01:00",
+        "end": "2024-02-01T02:00:00+01:00",
+        "type": "alert",
+    }
+
+    response = client.post(
+        url_for("AssetAPI:post_annotation", id=asset.id),
+        json=annotation_data,
+    )
+
+    assert (
+        response.status_code == expected_status_code
+    ), f"Expected {expected_status_code}, but got {response.status_code} with {response.json}"
+
+    if expected_status_code == 201:
+        # Verify response format
+        assert "id" in response.json
+        assert response.json["content"] == "Asset maintenance scheduled"
+        assert response.json["type"] == "alert"
+
+        # Verify annotation is linked to asset
+        annotation = client.application.db.session.get(Annotation, response.json["id"])
+        assert annotation in asset.annotations
+
+
+@pytest.mark.parametrize(
+    "requesting_user, sensor_name, expected_status_code",
+    [
+        (
+            "test_supplier_user_4@seita.nl",
+            "some gas sensor",
+            201,
+        ),  # supplier owns the sensor
+        (
+            "test_admin_user@seita.nl",
+            "some gas sensor",
+            201,
+        ),  # admin can annotate any sensor
+        (
+            "test_prosumer_user@seita.nl",
+            "some gas sensor",
+            403,
+        ),  # user doesn't own sensor
+        (None, "some gas sensor", 401),  # no authentication
+    ],
+    indirect=["requesting_user"],
+)
+def test_post_sensor_annotation_permissions(
+    client,
+    setup_api_test_data,
+    requesting_user,
+    sensor_name,
+    expected_status_code,
+):
+    """Test permission validation for sensor annotations.
+
+    Validates that:
+    - Sensor owners (via asset ownership) can annotate their sensors
+    - Platform admins can annotate any sensor
+    - Users without ownership cannot annotate
+    - Unauthenticated requests are rejected
+    """
+    # Get the gas sensor
+    sensor = client.application.db.session.execute(
+        select(Sensor).filter_by(name=sensor_name)
+    ).scalar_one()
+
+    annotation_data = {
+        "content": "Sensor calibration performed",
+        "start": "2024-03-01T10:00:00+01:00",
+        "end": "2024-03-01T10:30:00+01:00",
+        "type": "feedback",
+    }
+
+    response = client.post(
+        url_for("SensorAPI:post_annotation", id=sensor.id),
+        json=annotation_data,
+    )
+
+    assert (
+        response.status_code == expected_status_code
+    ), f"Expected {expected_status_code}, but got {response.status_code} with {response.json}"
+
+    if expected_status_code == 201:
+        # Verify response format
+        assert "id" in response.json
+        assert response.json["content"] == "Sensor calibration performed"
+        assert response.json["type"] == "feedback"
+
+        # Verify annotation is linked to sensor
+        annotation = client.application.db.session.get(Annotation, response.json["id"])
+        assert annotation in sensor.annotations
+
+
+@pytest.mark.parametrize(
+    "annotation_type",
+    ["alert", "holiday", "label", "feedback", "warning", "error"],
+)
+def test_post_annotation_valid_types(client, setup_api_test_data, annotation_type):
+    """Test that all valid annotation types are accepted.
+
+    Validates the six allowed annotation types:
+    - alert
+    - holiday
+    - label
+    - feedback
+    - warning
+    - error
+    """
+    # Use an admin user for permissions
+    from flexmeasures.api.tests.utils import get_auth_token
+
+    auth_token = get_auth_token(client, "test_admin_user@seita.nl", "testtest")
+
+    account = client.application.db.session.execute(
+        select(Account).filter_by(name="Test Prosumer Account")
+    ).scalar_one()
+
+    annotation_data = {
+        "content": f"Test {annotation_type} annotation",
+        "start": "2024-04-01T00:00:00+01:00",
+        "end": "2024-04-01T01:00:00+01:00",
+        "type": annotation_type,
+    }
+
+    response = client.post(
+        url_for("AccountAPI:post_annotation", id=account.id),
+        json=annotation_data,
+        headers={"Authorization": auth_token},
+    )
+
+    assert (
+        response.status_code == 201
+    ), f"Expected 201, but got {response.status_code} with {response.json}"
+    assert response.json["type"] == annotation_type
+
+
+def test_post_annotation_invalid_type(client, setup_api_test_data):
+    """Test that invalid annotation types are rejected with 422 Unprocessable Entity.
+
+    The type field must be one of the six valid enum values.
+    """
+    from flexmeasures.api.tests.utils import get_auth_token
+
+    auth_token = get_auth_token(client, "test_admin_user@seita.nl", "testtest")
+
+    account = client.application.db.session.execute(
+        select(Account).filter_by(name="Test Prosumer Account")
+    ).scalar_one()
+
+    annotation_data = {
+        "content": "Test annotation with invalid type",
+        "start": "2024-05-01T00:00:00+01:00",
+        "end": "2024-05-01T01:00:00+01:00",
+        "type": "invalid_type",  # Not in the allowed enum
+    }
+
+    response = client.post(
+        url_for("AccountAPI:post_annotation", id=account.id),
+        json=annotation_data,
+        headers={"Authorization": auth_token},
+    )
+
+    assert (
+        response.status_code == 422
+    ), f"Expected 422, but got {response.status_code} with {response.json}"
+
+
+@pytest.mark.parametrize(
+    "missing_field",
+    ["content", "start", "end"],
+)
+def test_post_annotation_missing_required_fields(
+    client, setup_api_test_data, missing_field
+):
+    """Test that missing required fields are rejected with 422.
+
+    Required fields are:
+    - content
+    - start
+    - end
+    """
+    from flexmeasures.api.tests.utils import get_auth_token
+
+    auth_token = get_auth_token(client, "test_admin_user@seita.nl", "testtest")
+
+    account = client.application.db.session.execute(
+        select(Account).filter_by(name="Test Prosumer Account")
+    ).scalar_one()
+
+    # Create a complete annotation, then remove the field to test
+    annotation_data = {
+        "content": "Test annotation",
+        "start": "2024-06-01T00:00:00+01:00",
+        "end": "2024-06-01T01:00:00+01:00",
+    }
+    del annotation_data[missing_field]
+
+    response = client.post(
+        url_for("AccountAPI:post_annotation", id=account.id),
+        json=annotation_data,
+        headers={"Authorization": auth_token},
+    )
+
+    assert (
+        response.status_code == 422
+    ), f"Expected 422, but got {response.status_code} with {response.json}"
+
+
+def test_post_annotation_content_too_long(client, setup_api_test_data):
+    """Test that content exceeding 1024 characters is rejected.
+
+    The content field has a maximum length of 1024 characters.
+    """
+    from flexmeasures.api.tests.utils import get_auth_token
+
+    auth_token = get_auth_token(client, "test_admin_user@seita.nl", "testtest")
+
+    account = client.application.db.session.execute(
+        select(Account).filter_by(name="Test Prosumer Account")
+    ).scalar_one()
+
+    # Create content that exceeds 1024 characters
+    long_content = "x" * 1025
+
+    annotation_data = {
+        "content": long_content,
+        "start": "2024-07-01T00:00:00+01:00",
+        "end": "2024-07-01T01:00:00+01:00",
+    }
+
+    response = client.post(
+        url_for("AccountAPI:post_annotation", id=account.id),
+        json=annotation_data,
+        headers={"Authorization": auth_token},
+    )
+
+    assert (
+        response.status_code == 422
+    ), f"Expected 422, but got {response.status_code} with {response.json}"
+
+
+def test_post_annotation_end_before_start(client, setup_api_test_data):
+    """Test that end time before start time is rejected.
+
+    The schema validates that end must be after start.
+    """
+    from flexmeasures.api.tests.utils import get_auth_token
+
+    auth_token = get_auth_token(client, "test_admin_user@seita.nl", "testtest")
+
+    account = client.application.db.session.execute(
+        select(Account).filter_by(name="Test Prosumer Account")
+    ).scalar_one()
+
+    annotation_data = {
+        "content": "Invalid time range",
+        "start": "2024-08-01T02:00:00+01:00",
+        "end": "2024-08-01T01:00:00+01:00",  # Before start
+    }
+
+    response = client.post(
+        url_for("AccountAPI:post_annotation", id=account.id),
+        json=annotation_data,
+        headers={"Authorization": auth_token},
+    )
+
+    assert (
+        response.status_code == 422
+    ), f"Expected 422, but got {response.status_code} with {response.json}"
+
+
+def test_post_annotation_end_equal_to_start(client, setup_api_test_data):
+    """Test that end time equal to start time is rejected.
+
+    The schema validates that end must be after start (not equal).
+    """
+    from flexmeasures.api.tests.utils import get_auth_token
+
+    auth_token = get_auth_token(client, "test_admin_user@seita.nl", "testtest")
+
+    account = client.application.db.session.execute(
+        select(Account).filter_by(name="Test Prosumer Account")
+    ).scalar_one()
+
+    annotation_data = {
+        "content": "Zero duration annotation",
+        "start": "2024-09-01T01:00:00+01:00",
+        "end": "2024-09-01T01:00:00+01:00",  # Equal to start
+    }
+
+    response = client.post(
+        url_for("AccountAPI:post_annotation", id=account.id),
+        json=annotation_data,
+        headers={"Authorization": auth_token},
+    )
+
+    assert (
+        response.status_code == 422
+    ), f"Expected 422, but got {response.status_code} with {response.json}"
+
+
+def test_post_annotation_not_found(client, setup_api_test_data):
+    """Test error responses when posting to non-existent entity.
+
+    Validates that:
+    - Non-existent account ID returns 404 (uses api.common.schemas.users.AccountIdField)
+    - Non-existent asset ID returns 422 (uses GenericAssetIdField with FMValidationError)
+    - Non-existent sensor ID returns 422 (uses data.schemas.sensors.SensorIdField with FMValidationError)
+
+    Note: There's currently an inconsistency in error handling:
+    - AccountAPI uses AccountIdField from api.common.schemas.users which raises abort(404)
+    - AssetAPI and SensorAPI use fields that raise FMValidationError (returns 422)
+
+    This reflects different validation field implementations across the codebase.
+    Consider making these consistent in a future refactoring.
+    """
+    from flexmeasures.api.tests.utils import get_auth_token
+
+    auth_token = get_auth_token(client, "test_admin_user@seita.nl", "testtest")
+
+    annotation_data = {
+        "content": "Test annotation",
+        "start": "2024-10-01T00:00:00+01:00",
+        "end": "2024-10-01T01:00:00+01:00",
+    }
+
+    # Test with non-existent account (returns 404)
+    response = client.post(
+        url_for("AccountAPI:post_annotation", id=99999),
+        json=annotation_data,
+        headers={"Authorization": auth_token},
+    )
+    assert response.status_code == 404
+
+    # Test with non-existent asset (returns 422)
+    response = client.post(
+        url_for("AssetAPI:post_annotation", id=99999),
+        json=annotation_data,
+        headers={"Authorization": auth_token},
+    )
+    assert (
+        response.status_code == 422
+    ), f"Expected 422, but got {response.status_code} with {response.json}"
+
+    # Test with non-existent sensor (returns 422)
+    response = client.post(
+        url_for("SensorAPI:post_annotation", id=99999),
+        json=annotation_data,
+        headers={"Authorization": auth_token},
+    )
+    assert (
+        response.status_code == 422
+    ), f"Expected 422, but got {response.status_code} with {response.json}"
+
+
+def test_post_annotation_idempotency(client, setup_api_test_data):
+    """Test that posting the same annotation twice is idempotent.
+
+    First POST should return 201 Created.
+    Second POST with identical data should return 200 OK.
+    Both should return the same annotation object.
+    """
+    from flexmeasures.api.tests.utils import get_auth_token
+
+    auth_token = get_auth_token(client, "test_admin_user@seita.nl", "testtest")
+
+    account = client.application.db.session.execute(
+        select(Account).filter_by(name="Test Prosumer Account")
+    ).scalar_one()
+
+    annotation_data = {
+        "content": "Idempotent annotation",
+        "start": "2024-11-01T00:00:00+01:00",
+        "end": "2024-11-01T01:00:00+01:00",
+        "type": "label",
+    }
+
+    # First POST - should create new annotation
+    response1 = client.post(
+        url_for("AccountAPI:post_annotation", id=account.id),
+        json=annotation_data,
+        headers={"Authorization": auth_token},
+    )
+
+    assert response1.status_code == 201
+    annotation_id_1 = response1.json["id"]
+
+    # Count annotations before second POST
+    annotation_count_before = client.application.db.session.scalar(
+        select(func.count()).select_from(Annotation)
+    )
+
+    # Second POST - should return existing annotation
+    response2 = client.post(
+        url_for("AccountAPI:post_annotation", id=account.id),
+        json=annotation_data,
+        headers={"Authorization": auth_token},
+    )
+
+    assert response2.status_code == 200
+    annotation_id_2 = response2.json["id"]
+
+    # Should be the same annotation
+    assert annotation_id_1 == annotation_id_2
+
+    # Count annotations after second POST
+    annotation_count_after = client.application.db.session.scalar(
+        select(func.count()).select_from(Annotation)
+    )
+
+    # No new annotation should have been created
+    assert annotation_count_before == annotation_count_after
+
+
+def test_post_annotation_with_prior(client, setup_api_test_data):
+    """Test that prior can be optionally specified.
+
+    When prior is provided, it should be stored and returned.
+    When omitted, the API should use the current time (tested implicitly).
+    """
+    from flexmeasures.api.tests.utils import get_auth_token
+
+    auth_token = get_auth_token(client, "test_admin_user@seita.nl", "testtest")
+
+    account = client.application.db.session.execute(
+        select(Account).filter_by(name="Test Prosumer Account")
+    ).scalar_one()
+
+    prior = "2024-12-01T12:00:00+01:00"
+
+    annotation_data = {
+        "content": "Annotation with belief time",
+        "start": "2024-12-01T00:00:00+01:00",
+        "end": "2024-12-01T01:00:00+01:00",
+        "prior": prior,
+    }
+
+    response = client.post(
+        url_for("AccountAPI:post_annotation", id=account.id),
+        json=annotation_data,
+        headers={"Authorization": auth_token},
+    )
+
+    assert (
+        response.status_code == 201
+    ), f"Expected 201, but got {response.status_code} with {response.json}"
+    assert "prior" in response.json
+    # Compare times after parsing to handle timezone conversions
+    import dateutil.parser
+
+    expected_time = dateutil.parser.isoparse(prior)
+    actual_time = dateutil.parser.isoparse(response.json["prior"])
+    assert expected_time == actual_time
+
+
+def test_post_annotation_default_type(client, setup_api_test_data):
+    """Test that type defaults to 'label' when not specified.
+
+    The type field is optional and should default to 'label'.
+    """
+    from flexmeasures.api.tests.utils import get_auth_token
+
+    auth_token = get_auth_token(client, "test_admin_user@seita.nl", "testtest")
+
+    account = client.application.db.session.execute(
+        select(Account).filter_by(name="Test Prosumer Account")
+    ).scalar_one()
+
+    annotation_data = {
+        "content": "Annotation with default type",
+        "start": "2024-12-15T00:00:00+01:00",
+        "end": "2024-12-15T01:00:00+01:00",
+        # type is omitted
+    }
+
+    response = client.post(
+        url_for("AccountAPI:post_annotation", id=account.id),
+        json=annotation_data,
+        headers={"Authorization": auth_token},
+    )
+
+    assert (
+        response.status_code == 201
+    ), f"Expected 201, but got {response.status_code} with {response.json}"
+    assert response.json["type"] == "label"
+
+
+def test_post_annotation_all_three_endpoints(client, setup_api_test_data):
+    """Test that all three endpoints work correctly with the same annotation data.
+
+    This comprehensive test validates that:
+    - Account annotation endpoint works
+    - Asset annotation endpoint works
+    - Sensor annotation endpoint works
+
+    All with the same user and similar data.
+    """
+    from flexmeasures.api.tests.utils import get_auth_token
+
+    auth_token = get_auth_token(client, "test_supplier_user_4@seita.nl", "testtest")
+
+    # Get test entities
+    supplier_account = find_user_by_email("test_supplier_user_4@seita.nl").account
+    asset = client.application.db.session.execute(
+        select(GenericAsset).filter_by(name="incineration line")
+    ).scalar_one()
+    sensor = client.application.db.session.execute(
+        select(Sensor).filter_by(name="some gas sensor")
+    ).scalar_one()
+
+    # Test account annotation
+    response = client.post(
+        url_for("AccountAPI:post_annotation", id=supplier_account.id),
+        json={
+            "content": "Account-level annotation",
+            "start": "2025-01-01T00:00:00+01:00",
+            "end": "2025-01-01T01:00:00+01:00",
+        },
+        headers={"Authorization": auth_token},
+    )
+    assert (
+        response.status_code == 201
+    ), f"Expected 201, but got {response.status_code} with {response.json}"
+    account_annotation_id = response.json["id"]
+
+    # Test asset annotation
+    response = client.post(
+        url_for("AssetAPI:post_annotation", id=asset.id),
+        json={
+            "content": "Asset-level annotation",
+            "start": "2025-01-02T00:00:00+01:00",
+            "end": "2025-01-02T01:00:00+01:00",
+        },
+        headers={"Authorization": auth_token},
+    )
+    assert (
+        response.status_code == 201
+    ), f"Expected 201, but got {response.status_code} with {response.json}"
+    asset_annotation_id = response.json["id"]
+
+    # Test sensor annotation
+    response = client.post(
+        url_for("SensorAPI:post_annotation", id=sensor.id),
+        json={
+            "content": "Sensor-level annotation",
+            "start": "2025-01-03T00:00:00+01:00",
+            "end": "2025-01-03T01:00:00+01:00",
+        },
+        headers={"Authorization": auth_token},
+    )
+    assert (
+        response.status_code == 201
+    ), f"Expected 201, but got {response.status_code} with {response.json}"
+    sensor_annotation_id = response.json["id"]
+
+    # Verify all annotations are distinct
+    assert account_annotation_id != asset_annotation_id
+    assert account_annotation_id != sensor_annotation_id
+    assert asset_annotation_id != sensor_annotation_id
+
+    # Verify annotations are correctly linked
+    db = client.application.db
+    account_annotation = db.session.get(Annotation, account_annotation_id)
+    asset_annotation = db.session.get(Annotation, asset_annotation_id)
+    sensor_annotation = db.session.get(Annotation, sensor_annotation_id)
+
+    assert account_annotation in supplier_account.annotations
+    assert asset_annotation in asset.annotations
+    assert sensor_annotation in sensor.annotations
+
+
+def test_post_annotation_response_schema(client, setup_api_test_data):
+    """Test that the response schema includes all expected fields.
+
+    The response should include:
+    - id (integer)
+    - content (string)
+    - start (ISO 8601 datetime)
+    - end (ISO 8601 datetime)
+    - type (string)
+    - prior (ISO 8601 datetime)
+    - source (integer)
+    """
+    from flexmeasures.api.tests.utils import get_auth_token
+
+    auth_token = get_auth_token(client, "test_admin_user@seita.nl", "testtest")
+
+    account = client.application.db.session.execute(
+        select(Account).filter_by(name="Test Prosumer Account")
+    ).scalar_one()
+
+    annotation_data = {
+        "content": "Complete response test",
+        "start": "2025-02-01T00:00:00+01:00",
+        "end": "2025-02-01T01:00:00+01:00",
+        "type": "warning",
+    }
+
+    response = client.post(
+        url_for("AccountAPI:post_annotation", id=account.id),
+        json=annotation_data,
+        headers={"Authorization": auth_token},
+    )
+
+    assert (
+        response.status_code == 201
+    ), f"Expected 201, but got {response.status_code} with {response.json}"
+
+    # Check all expected fields are present
+    assert "id" in response.json
+    assert "content" in response.json
+    assert "start" in response.json
+    assert "end" in response.json
+    assert "type" in response.json
+    assert "prior" in response.json
+    assert "source" in response.json
+
+    # Verify field types and values
+    assert isinstance(response.json["id"], int)
+    assert response.json["content"] == "Complete response test"
+    assert response.json["type"] == "warning"
+    assert isinstance(response.json["source"], int)
+
+    # Verify datetime fields are in ISO format
+    assert "T" in response.json["start"]
+    assert "T" in response.json["end"]
+    # prior may be None if not explicitly set
+    if response.json["prior"] is not None:
+        assert "T" in response.json["prior"]
diff --git a/flexmeasures/cli/data_add.py b/flexmeasures/cli/data_add.py
index f1c1e90a0e..68cbdc2cca 100755
--- a/flexmeasures/cli/data_add.py
+++ b/flexmeasures/cli/data_add.py
@@ -875,7 +875,7 @@ def add_annotation(
     _source = get_or_create_source(user)
 
     # Create annotation
-    annotation = get_or_create_annotation(
+    annotation, _ = get_or_create_annotation(
         Annotation(
             content=content,
             start=start,
@@ -967,17 +967,16 @@ def add_holidays(
         for holiday in holidays:
             start = pd.Timestamp(holiday[0])
             end = start + pd.offsets.DateOffset(days=1)
-            annotations.append(
-                get_or_create_annotation(
-                    Annotation(
-                        content=holiday[1],
-                        start=start,
-                        end=end,
-                        source=_source,
-                        type="holiday",
-                    )
+            annotation, _ = get_or_create_annotation(
+                Annotation(
+                    content=holiday[1],
+                    start=start,
+                    end=end,
+                    source=_source,
+                    type="holiday",
                 )
             )
+            annotations.append(annotation)
         num_holidays[country] = len(holidays)
     db.session.add_all(annotations)
     for account in accounts:
diff --git a/flexmeasures/data/models/annotations.py b/flexmeasures/data/models/annotations.py
index f06b4ab3f3..741cc343e5 100644
--- a/flexmeasures/data/models/annotations.py
+++ b/flexmeasures/data/models/annotations.py
@@ -197,10 +197,12 @@ class SensorAnnotationRelationship(db.Model):
 
 def get_or_create_annotation(
     annotation: Annotation,
-) -> Annotation:
+) -> tuple[Annotation, bool]:
     """Add annotation to db session if it doesn't exist in the session already.
 
-    Return the old annotation object if it exists (and expunge the new one). Otherwise, return the new one.
+    Return tuple of (annotation object, is_new boolean).
+    If annotation exists, return (existing_annotation, False).
+    If annotation is new, return (new_annotation, True).
     """
     with db.session.no_autoflush:
         existing_annotation = db.session.execute(
@@ -214,10 +216,10 @@ def get_or_create_annotation(
         ).scalar_one_or_none()
     if existing_annotation is None:
         db.session.add(annotation)
-        return annotation
+        return annotation, True
     if annotation in db.session:
         db.session.expunge(annotation)
-    return existing_annotation
+    return existing_annotation, False
 
 
 def to_annotation_frame(annotations: list[Annotation]) -> pd.DataFrame:
diff --git a/flexmeasures/data/schemas/account.py b/flexmeasures/data/schemas/account.py
index cb2e970ace..a977c4ad7d 100644
--- a/flexmeasures/data/schemas/account.py
+++ b/flexmeasures/data/schemas/account.py
@@ -1,12 +1,15 @@
 from typing import Any
 
-from flask.cli import with_appcontext
 from flexmeasures.data import ma
 from marshmallow import fields, validates
 
 from flexmeasures.data import db
 from flexmeasures.data.models.user import Account, AccountRole
-from flexmeasures.data.schemas.utils import FMValidationError, MarshmallowClickMixin
+from flexmeasures.data.schemas.utils import (
+    FMValidationError,
+    MarshmallowClickMixin,
+    with_appcontext_if_needed,
+)
 from flexmeasures.utils.validation_utils import validate_color_hex, validate_url
 
 
@@ -60,7 +63,7 @@ def validate_logo_url(self, value, **kwargs):
 class AccountIdField(fields.Int, MarshmallowClickMixin):
     """Field that deserializes to an Account and serializes back to an integer."""
 
-    @with_appcontext
+    @with_appcontext_if_needed()
     def _deserialize(self, value: Any, attr, data, **kwargs) -> Account:
         """Turn an account id into an Account."""
         account_id: int = super()._deserialize(value, attr, data, **kwargs)
diff --git a/flexmeasures/data/schemas/annotations.py b/flexmeasures/data/schemas/annotations.py
new file mode 100644
index 0000000000..34e8271756
--- /dev/null
+++ b/flexmeasures/data/schemas/annotations.py
@@ -0,0 +1,95 @@
+from __future__ import annotations
+
+from flask_security import current_user
+from marshmallow import Schema, fields, post_load, validates_schema, ValidationError
+from marshmallow.validate import OneOf, Length
+
+from flexmeasures.data.models.annotations import Annotation
+from flexmeasures.data.schemas.times import AwareDateTimeField
+from flexmeasures.data.services.data_sources import get_or_create_source
+
+
+class AnnotationSchema(Schema):
+    """Schema for annotation POST requests."""
+
+    id = fields.Int(
+        dump_only=True,
+        metadata=dict(
+            description="The annotation's ID, which is automatically assigned.",
+            example=19,
+        ),
+    )
+    source_id = fields.Int(
+        data_key="source",
+        dump_only=True,
+        metadata=dict(
+            description="The annotation's data source ID, which usually corresponds to a user (it is not the user ID, though).",
+            example=21,
+        ),
+    )
+
+    content = fields.Str(
+        required=True,
+        validate=Length(max=1024),
+        metadata={
+            "description": "Text content of the annotation (max 1024 characters).",
+            "examples": [
+                "Server maintenance",
+                "Installation upgrade",
+                "Operation Main Strike",
+            ],
+        },
+    )
+    start = AwareDateTimeField(
+        required=True,
+        format="iso",
+        metadata={
+            "description": "Start time in ISO 8601 format.",
+            "example": "2026-02-11T17:52:03+01:00",
+        },
+    )
+    end = AwareDateTimeField(
+        required=True,
+        format="iso",
+        metadata={
+            "description": "End time in ISO 8601 format.",
+            "example": "2026-02-11T19:00:00+01:00",
+        },
+    )
+    type = fields.Str(
+        required=False,
+        load_default="label",
+        validate=OneOf(["alert", "holiday", "label", "feedback", "warning", "error"]),
+        metadata={"description": "Type of annotation."},
+    )
+    belief_time = AwareDateTimeField(
+        data_key="prior",
+        required=False,
+        allow_none=True,
+        format="iso",
+        metadata={
+            "description": "Time when the annotation was recorded, in ISO 8601 format (default: now).",
+            "example": "2026-02-01T17:43:56+01:00",
+        },
+    )
+
+    @validates_schema
+    def validate_time_range(self, data, **kwargs):
+        """Validate that end is after start."""
+        if "start" in data and "end" in data:
+            if data["end"] <= data["start"]:
+                raise ValidationError("end must be after start")
+
+    @post_load
+    def to_annotation(self, data: dict, *args, **kwargs) -> Annotation:
+        """Load annotation data into a user-sourced annotation object."""
+        source = get_or_create_source(current_user)
+        annotation = Annotation(
+            content=data["content"],
+            start=data["start"],
+            end=data["end"],
+            type=data.get("type", "label"),
+            belief_time=data.get("belief_time"),
+            source=source,
+        )
+        return annotation
diff --git a/flexmeasures/data/tests/test_annotations.py b/flexmeasures/data/tests/test_annotations.py
index 678b89c42b..b8e85a8bfe 100644
--- a/flexmeasures/data/tests/test_annotations.py
+++ b/flexmeasures/data/tests/test_annotations.py
@@ -18,7 +18,9 @@ def test_get_or_create_annotation(db, setup_sources):
         source=source,
         type="holiday",
     )
-    assert first_annotation == get_or_create_annotation(first_annotation)
+    result_annotation, is_new = get_or_create_annotation(first_annotation)
+    assert result_annotation == first_annotation
+    assert is_new is True
     num_annotations_intermediate = db.session.scalar(
         select(func.count()).select_from(Annotation)
     )
@@ -42,7 +44,9 @@ def test_get_or_create_annotation(db, setup_sources):
         source=source,
         type="holiday",
     )
-    assert first_annotation == get_or_create_annotation(second_annotation)
+    result_annotation, is_new = get_or_create_annotation(second_annotation)
+    assert result_annotation == first_annotation
+    assert is_new is False
     num_annotations_after = db.session.scalar(select(func.count(Annotation.id)))
     assert num_annotations_after == num_annotations_intermediate
     assert second_annotation.id is None
diff --git a/flexmeasures/ui/static/openapi-specs.json b/flexmeasures/ui/static/openapi-specs.json
index ea91c572f7..bf225f10ba 100644
--- a/flexmeasures/ui/static/openapi-specs.json
+++ b/flexmeasures/ui/static/openapi-specs.json
@@ -339,7 +339,7 @@
       },
       "get": {
         "summary": "Get sensor data",
-        "description": "The unit has to be convertible from the sensor's unit - e.g. you ask for kW, and the sensor's unit is MW.\n\nOptional parameters:\n\n- \"resolution\" (read [the docs about frequency and resolutions](https://flexmeasures.readthedocs.io/latest/api/notation.html#frequency-and-resolution))\n- \"horizon\" (read [the docs about belief timing](https://flexmeasures.readthedocs.io/latest/api/notation.html#tracking-the-recording-time-of-beliefs))\n- \"prior\" (the belief timing docs also apply here)\n- \"source\" (read [the docs about sources](https://flexmeasures.readthedocs.io/latest/api/notation.html#sources))\n\nAn example query to fetch data for sensor with ID=1, for one hour starting June 7th 2021 at midnight, in 15 minute intervals, in m\u00b3/h:\n\n  ?start=2021-06-07T00:00:00+02:00&duration=PT1H&resolution=PT15M&unit=m\u00b3/h\n\n(you will probably need to escape the + in the timezone offset, depending on your HTTP client, and other characters like here in the unit, as well).\n\n > **Note:** This endpoint also accepts the query parameters as part of the JSON body. That is not conform to REST architecture, but it is easier for some developers.\n",
+        "description": "The unit has to be convertible from the sensor's unit - e.g. you ask for kW, and the sensor's unit is MW.\n\nOptional parameters:\n\n- \"resolution\" (read [the docs about frequency and resolutions](https://flexmeasures.readthedocs.io/latest/api/notation.html#frequency-and-resolution))\n- \"horizon\" (read [the docs about belief timing](https://flexmeasures.readthedocs.io/latest/api/notation.html#tracking-the-recording-time-of-beliefs))\n- \"prior\" (the belief timing docs also apply here)\n- \"source\" (read [the docs about sources](https://flexmeasures.readthedocs.io/latest/api/notation.html#sources))\n\nAn example query to fetch data for sensor with ID=1, for one hour starting June 7th 2021 at midnight, in 15 minute intervals, in m\u00b3/h:\n\n  ?start=2021-06-07T00:00:00+02:00&duration=PT1H&resolution=PT15M&unit=m\u00b3/h\n\n(you will probably need to escape the + in the timezone offset, depending on your HTTP client, and other characters like here in the unit, as well).\n\n > <strong>Note:</strong> This endpoint also accepts the query parameters as part of the JSON body. That is not conform to REST architecture, but it is easier for some developers.\n",
         "security": [
           {
             "ApiKeyAuth": []
@@ -911,7 +911,7 @@
     "/api/v3_0/sensors": {
       "get": {
         "summary": "Get list of sensors",
-        "description": "This endpoint returns all accessible sensors.\nBy default, \"accessible sensors\" means all sensors in the same account as the current user (if they have read permission to the account).\n\nYou can also specify an `account` (an ID parameter), if the user has read access to that account. In this case, all assets under the\nspecified account will be retrieved, and the sensors associated with these assets will be returned.\n\nAlternatively, you can filter by asset hierarchy by providing the `asset` parameter (ID). When this is set, all sensors on the specified\nasset and its sub-assets are retrieved, provided the user has read access to the asset.\n\n> **Note:** You can't set both account and asset at the same time, you can only have one set. The only exception is if the asset being specified is\n> part of the account that was set, then we allow to see sensors under that asset but then ignore the account (account = None).\n\nFinally, you can use the `include_consultancy_clients` parameter to include sensors from accounts for which the current user account is a consultant.\nThis is only possible if the user has the role of a consultant.\n\nOnly admins can use this endpoint to fetch sensors from a different account (by using the `account_id` query parameter).\n\nThe `filter` parameter allows you to search for sensors by name or account name.\nThe `unit` parameter allows you to filter by unit.\n\nFor the pagination of the sensor list, you can use the `page` and `per_page` query parameters, the `page` parameter is used to trigger\npagination, and the `per_page` parameter is used to specify the number of records per page. The default value for `page` is 1 and for `per_page` is 10.\n",
+        "description": "This endpoint returns all accessible sensors.\nBy default, \"accessible sensors\" means all sensors in the same account as the current user (if they have read permission to the account).\n\nYou can also specify an `account` (an ID parameter), if the user has read access to that account. In this case, all assets under the\nspecified account will be retrieved, and the sensors associated with these assets will be returned.\n\nAlternatively, you can filter by asset hierarchy by providing the `asset` parameter (ID). When this is set, all sensors on the specified\nasset and its sub-assets are retrieved, provided the user has read access to the asset.\n\n> <strong>Note:</strong> You can't set both account and asset at the same time, you can only have one set. The only exception is if the asset being specified is\n> part of the account that was set, then we allow to see sensors under that asset but then ignore the account (account = None).\n\nFinally, you can use the `include_consultancy_clients` parameter to include sensors from accounts for which the current user account is a consultant.\nThis is only possible if the user has the role of a consultant.\n\nOnly admins can use this endpoint to fetch sensors from a different account (by using the `account_id` query parameter).\n\nThe `filter` parameter allows you to search for sensors by name or account name.\nThe `unit` parameter allows you to filter by unit.\n\nFor the pagination of the sensor list, you can use the `page` and `per_page` query parameters, the `page` parameter is used to trigger\npagination, and the `per_page` parameter is used to specify the number of records per page. The default value for `page` is 1 and for `per_page` is 10.\n",
         "security": [
           {
             "ApiKeyAuth": []
@@ -1160,10 +1160,66 @@
         ]
       }
     },
+    "/api/v3_0/sensors/{id}/annotations": {
+      "post": {
+        "summary": "Creates a new sensor annotation.",
+        "description": "This endpoint creates a new annotation on a sensor.\n",
+        "security": [
+          {
+            "ApiKeyAuth": []
+          }
+        ],
+        "parameters": [
+          {
+            "name": "id",
+            "in": "path",
+            "description": "The ID of the sensor to register the annotation on.",
+            "required": true,
+            "schema": {
+              "type": "integer",
+              "format": "int32"
+            }
+          }
+        ],
+        "requestBody": {
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/AnnotationSchema"
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "OK"
+          },
+          "201": {
+            "description": "PROCESSED"
+          },
+          "400": {
+            "description": "INVALID_REQUEST"
+          },
+          "401": {
+            "description": "UNAUTHORIZED"
+          },
+          "403": {
+            "description": "INVALID_SENDER"
+          },
+          "422": {
+            "description": "UNPROCESSABLE_ENTITY"
+          }
+        },
+        "tags": [
+          "Sensors",
+          "Annotations"
+        ]
+      }
+    },
     "/api/v3_0/sensors/{id}/forecasts/trigger": {
       "post": {
         "summary": "Trigger forecasting job for one sensor",
-        "description": "Trigger a forecasting job for a sensor.\n\nThis endpoint starts a forecasting job asynchronously and returns a\njob UUID. The job will run in the background and generate forecast values\nfor the specified period.\n\nOnce triggered, the job status and results can be retrieved using the\n``GET /api/v3_0/sensors/<id>/forecasts/<uuid>`` endpoint.\n",
+        "description": "Trigger a forecasting job for a sensor.\n\nThis endpoint starts a forecasting job asynchronously and returns a\njob UUID. The job will run in the background and generate forecast values\nfor the specified period.\n\nOnce triggered, the job status and results can be retrieved using the\n<code>GET /api/v3_0/sensors/<id>/forecasts/<uuid></code> endpoint.\n",
         "security": [
           {
             "ApiKeyAuth": []
@@ -1262,7 +1318,7 @@
     "/api/v3_0/sensors/{id}/schedules/trigger": {
       "post": {
         "summary": "Trigger scheduling job for one device",
-        "description": "Trigger FlexMeasures to create a schedule for this sensor.\nThe assumption is that this sensor is the power sensor on a flexible asset.\n\nIn this request, you can describe:\n\n- the schedule's main features (when does it start, what unit should it report, prior to what time can we assume knowledge)\n- the flexibility model for the sensor (state and constraint variables, e.g. current state of charge of a battery, or connection capacity)\n- the flexibility context which the sensor operates in (other sensors under the same EMS which are relevant, e.g. prices)\n\nFor details on flexibility model and context, see the [documentation on describing flexibility](https://flexmeasures.readthedocs.io/latest/features/scheduling.html#describing-flexibility).\nThe schemas we use in this endpoint documentation do not describe the full flexibility model and context (as the docs do), as these are very flexible (e.g. fixed values or sensors).\nThe examples below illustrate how to describe a flexibility model and context.\n\n> **Note:** To schedule an EMS with multiple flexible sensors at once,\n> use the [Assets scheduling endpoint](#/Assets/post_api_v3_0_assets__id__schedules_trigger) instead.\n\nAbout the duration of the schedule and targets within the schedule:\n\n- The length of the schedule can be set explicitly through the 'duration' field.\n- Otherwise, it is set by the config setting `FLEXMEASURES_PLANNING_HORIZON`, which defaults to 48 hours.\n- If the flex-model contains targets that lie beyond the planning horizon, the length of the schedule is extended to accommodate them.\n- Finally, the schedule length is limited by the config setting `FLEXMEASURES_MAX_PLANNING_HORIZON`, which defaults to 2520 steps of the sensor's resolution. Targets that exceed the max planning horizon are not accepted.\n\nThe 'resolution' field governs how often setpoints are allowed to change.\nNote that the resulting schedule is still saved in the sensor resolution.\n\nAbout the scheduling algorithm being used:\n\n- The appropriate algorithm is chosen by FlexMeasures (based on asset type).\n- It's also possible to use custom schedulers and custom flexibility models.\n- If you have ideas for algorithms that should be part of FlexMeasures, let us know: [https://flexmeasures.io/get-in-touch/](https://flexmeasures.io/get-in-touch/)\n",
+        "description": "Trigger FlexMeasures to create a schedule for this sensor.\nThe assumption is that this sensor is the power sensor on a flexible asset.\n\nIn this request, you can describe:\n\n- the schedule's main features (when does it start, what unit should it report, prior to what time can we assume knowledge)\n- the flexibility model for the sensor (state and constraint variables, e.g. current state of charge of a battery, or connection capacity)\n- the flexibility context which the sensor operates in (other sensors under the same EMS which are relevant, e.g. prices)\n\nFor details on flexibility model and context, see the [documentation on describing flexibility](https://flexmeasures.readthedocs.io/latest/features/scheduling.html#describing-flexibility).\nThe schemas we use in this endpoint documentation do not describe the full flexibility model and context (as the docs do), as these are very flexible (e.g. fixed values or sensors).\nThe examples below illustrate how to describe a flexibility model and context.\n\n> <strong>Note:</strong> To schedule an EMS with multiple flexible sensors at once,\n> use the [Assets scheduling endpoint](#/Assets/post_api_v3_0_assets__id__schedules_trigger) instead.\n\nAbout the duration of the schedule and targets within the schedule:\n\n- The length of the schedule can be set explicitly through the 'duration' field.\n- Otherwise, it is set by the config setting `FLEXMEASURES_PLANNING_HORIZON`, which defaults to 48 hours.\n- If the flex-model contains targets that lie beyond the planning horizon, the length of the schedule is extended to accommodate them.\n- Finally, the schedule length is limited by the config setting `FLEXMEASURES_MAX_PLANNING_HORIZON`, which defaults to 2520 steps of the sensor's resolution. Targets that exceed the max planning horizon are not accepted.\n\nThe 'resolution' field governs how often setpoints are allowed to change.\nNote that the resulting schedule is still saved in the sensor resolution.\n\nAbout the scheduling algorithm being used:\n\n- The appropriate algorithm is chosen by FlexMeasures (based on asset type).\n- It's also possible to use custom schedulers and custom flexibility models.\n- If you have ideas for algorithms that should be part of FlexMeasures, let us know: [https://flexmeasures.io/get-in-touch/](https://flexmeasures.io/get-in-touch/)\n",
         "security": [
           {
             "ApiKeyAuth": []
@@ -1302,7 +1358,7 @@
                 },
                 "complex_schedule": {
                   "summary": "Complex 24-hour schedule",
-                  "description": "In this complex example, let's really show off a lot of potential configurations.\n\nThis message triggers a 24-hour schedule for a storage asset, starting at 10.00am,\nat which the state of charge (soc) is 12.1 kWh, with a target state of charge of 25 kWh at 4.00pm.\n\nThe charging efficiency is constant (120%) and the discharging efficiency is determined by the contents of sensor\nwith id 98. If just the ``roundtrip-efficiency`` is known, it can be described with its own field.\nThe global minimum and maximum soc are set to 10 and 25 kWh, respectively.\n\nTo guarantee a minimum SOC in the period prior, the sensor with ID 300 contains beliefs at 2.00pm and 3.00pm, for 15kWh and 20kWh, respectively.\nStorage efficiency is set to 99.99%, denoting the state of charge left after each time step equal to the sensor's resolution.\nAggregate consumption (of all devices within this EMS) should be priced by sensor 9,\nand aggregate production should be priced by sensor 10,\nwhere the aggregate power flow in the EMS is described by the sum over sensors 13, 14, 15,\nand the power sensor of the flexible device being optimized (referenced in the endpoint URL).\n\n\nThe battery consumption power capacity is limited by sensor 42 and the production capacity is constant (30 kW).\n\nFinally, the (contractual and physical) situation of the site is part of the flex-context.\nThe site has a physical power capacity of 100 kVA, but the production capacity is limited to 80 kW,\nwhile the consumption capacity is limited by a dynamic capacity contract whose values are recorded under sensor 32.\nBreaching either capacity is penalized heavily in the optimization problem, with a price of 1000 EUR/kW.\nFinally, peaks over 50 kW in either direction are penalized with a price of 260 EUR/MW.\n\nThese penalties can be used to steer the schedule into a certain behavior (e.g. avoiding breaches and peaks),\neven if no direct financial impacts are expected at the given prices in the real world.\n\nFor example, site owners may be requested by their network operators to reduce stress on the grid,\nbe it explicitly or under a social contract.\n\nNote that, if forecasts for sensors 13, 14 and 15 are not available, a schedule cannot be computed.\n",
+                  "description": "In this complex example, let's really show off a lot of potential configurations.\n\nThis message triggers a 24-hour schedule for a storage asset, starting at 10.00am,\nat which the state of charge (soc) is 12.1 kWh, with a target state of charge of 25 kWh at 4.00pm.\n\nThe charging efficiency is constant (120%) and the discharging efficiency is determined by the contents of sensor\nwith id 98. If just the <code>roundtrip-efficiency</code> is known, it can be described with its own field.\nThe global minimum and maximum soc are set to 10 and 25 kWh, respectively.\n\nTo guarantee a minimum SOC in the period prior, the sensor with ID 300 contains beliefs at 2.00pm and 3.00pm, for 15kWh and 20kWh, respectively.\nStorage efficiency is set to 99.99%, denoting the state of charge left after each time step equal to the sensor's resolution.\nAggregate consumption (of all devices within this EMS) should be priced by sensor 9,\nand aggregate production should be priced by sensor 10,\nwhere the aggregate power flow in the EMS is described by the sum over sensors 13, 14, 15,\nand the power sensor of the flexible device being optimized (referenced in the endpoint URL).\n\n\nThe battery consumption power capacity is limited by sensor 42 and the production capacity is constant (30 kW).\n\nFinally, the (contractual and physical) situation of the site is part of the flex-context.\nThe site has a physical power capacity of 100 kVA, but the production capacity is limited to 80 kW,\nwhile the consumption capacity is limited by a dynamic capacity contract whose values are recorded under sensor 32.\nBreaching either capacity is penalized heavily in the optimization problem, with a price of 1000 EUR/kW.\nFinally, peaks over 50 kW in either direction are penalized with a price of 260 EUR/MW.\n\nThese penalties can be used to steer the schedule into a certain behavior (e.g. avoiding breaches and peaks),\neven if no direct financial impacts are expected at the given prices in the real world.\n\nFor example, site owners may be requested by their network operators to reduce stress on the grid,\nbe it explicitly or under a social contract.\n\nNote that, if forecasts for sensors 13, 14 and 15 are not available, a schedule cannot be computed.\n",
                   "value": {
                     "start": "2015-06-02T10:00:00+00:00",
                     "duration": "PT24H",
@@ -1662,7 +1718,7 @@
       },
       "patch": {
         "summary": "Update an existing account.",
-        "description": "This endpoint updates the details for an existing account.\n\nIn the JSON body, sent in only the fields you want to update.\n\n**Restrictions on Fields:**\n- The **id** field is read-only and cannot be updated.\n- The **consultancy_account_id** field can only be edited if the current user has an **admin** role.\n",
+        "description": "This endpoint updates the details for an existing account.\n\nIn the JSON body, sent in only the fields you want to update.\n\n<strong>Restrictions on Fields:</strong>\n- The <strong>id</strong> field is read-only and cannot be updated.\n- The <strong>consultancy_account_id</strong> field can only be edited if the current user has an <strong>admin</strong> role.\n",
         "security": [
           {
             "ApiKeyAuth": []
@@ -1868,6 +1924,62 @@
         ]
       }
     },
+    "/api/v3_0/accounts/{id}/annotations": {
+      "post": {
+        "summary": "Creates a new account annotation.",
+        "description": "This endpoint creates a new annotation on an account.\n",
+        "security": [
+          {
+            "ApiKeyAuth": []
+          }
+        ],
+        "parameters": [
+          {
+            "name": "id",
+            "in": "path",
+            "description": "The ID of the account to register the annotation on.",
+            "required": true,
+            "schema": {
+              "type": "integer",
+              "format": "int32"
+            }
+          }
+        ],
+        "requestBody": {
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/AnnotationSchema"
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "OK"
+          },
+          "201": {
+            "description": "PROCESSED"
+          },
+          "400": {
+            "description": "INVALID_REQUEST"
+          },
+          "401": {
+            "description": "UNAUTHORIZED"
+          },
+          "403": {
+            "description": "INVALID_SENDER"
+          },
+          "422": {
+            "description": "UNPROCESSABLE_ENTITY"
+          }
+        },
+        "tags": [
+          "Accounts",
+          "Annotations"
+        ]
+      }
+    },
     "/api/v3_0/users/{id}/auditlog": {
       "get": {
         "summary": "Get history of user actions.",
@@ -3405,7 +3517,7 @@
       },
       "post": {
         "summary": "Creates a new asset.",
-        "description": "This endpoint creates a new asset.\n\nTo establish a hierarchical relationship, you can optionally include the **parent_asset_id** in the request body to make the new asset a child of an existing asset.\n",
+        "description": "This endpoint creates a new asset.\n\nTo establish a hierarchical relationship, you can optionally include the <strong>parent_asset_id</strong> in the request body to make the new asset a child of an existing asset.\n",
         "security": [
           {
             "ApiKeyAuth": []
@@ -3493,6 +3605,62 @@
         ]
       }
     },
+    "/api/v3_0/assets/{id}/annotations": {
+      "post": {
+        "summary": "Creates a new asset annotation.",
+        "description": "This endpoint creates a new annotation on an asset.\n",
+        "security": [
+          {
+            "ApiKeyAuth": []
+          }
+        ],
+        "parameters": [
+          {
+            "name": "id",
+            "in": "path",
+            "description": "The ID of the asset to register the annotation on.",
+            "required": true,
+            "schema": {
+              "type": "integer",
+              "format": "int32"
+            }
+          }
+        ],
+        "requestBody": {
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/AnnotationSchema"
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "OK"
+          },
+          "201": {
+            "description": "PROCESSED"
+          },
+          "400": {
+            "description": "INVALID_REQUEST"
+          },
+          "401": {
+            "description": "UNAUTHORIZED"
+          },
+          "403": {
+            "description": "INVALID_SENDER"
+          },
+          "422": {
+            "description": "UNPROCESSABLE_ENTITY"
+          }
+        },
+        "tags": [
+          "Assets",
+          "Annotations"
+        ]
+      }
+    },
     "/api/v3_0/assets/public": {
       "get": {
         "summary": "Return all public assets.",
@@ -3537,7 +3705,7 @@
     "/api/v3_0/assets/{id}/schedules/trigger": {
       "post": {
         "summary": "Trigger scheduling job for any number of devices",
-        "description": "Trigger FlexMeasures to create a schedule for this asset.\nThe flex-model needs to reference the power sensors of flexible devices, which must belong to the given asset,\neither directly or indirectly, by being assigned to one of the asset's (grand)children.\n\nIn this request, you can describe:\n\n- the schedule's main features (when does it start, what unit should it report, prior to what time can we assume knowledge)\n- the flexibility models for the asset's relevant sensors (state and constraint variables, e.g. current state of charge of a battery, or connection capacity)\n- the flexibility context which the asset operates in (other sensors under the same EMS which are relevant, e.g. prices)\n\nFor details on flexibility model and context, [see describing_flexibility](https://flexmeasures.readthedocs.io/stable/features/scheduling.html#describing-flexibility).\nBelow, we'll also list some examples.\nThe schemas we use in this endpoint documentation do not describe the full flexibility model and context (as the docs do), as these are very flexible (e.g. fixed values or sensors). The examples below illustrate how to describe a flexibility model and context.\n\n> **Note:** This endpoint supports scheduling an EMS with multiple flexible devices at once.\n> It can do so jointly (the default) or sequentially\n> (considering previously scheduled sensors as inflexible).\n> To use sequential scheduling, use ``sequential=true`` in the JSON body.\n\nThe length of the schedule can be set explicitly through the 'duration' field.\nOtherwise, it is set by [a config setting](https://flexmeasures.readthedocs.io/stable/configuration.html#flexmeasures-planning-horizon), which defaults to 48 hours.\nIf the flex-model contains targets that lie beyond the planning horizon, the length of the schedule is extended to accommodate them.\nFinally, the schedule length is limited by [a config setting](https://flexmeasures.readthedocs.io/stable/configuration.html#flexmeasures-max-planning-horizon), which defaults to 2520 steps of each sensor's resolution.\nTargets that exceed the max planning horizon are not accepted.\n\nThe 'resolution' field governs how often setpoints are allowed to change.\nNote that the resulting schedule is still saved in the resolution of each individual sensor.\n\nThe appropriate algorithm is chosen by FlexMeasures (based on asset type).\nIt's also possible to use custom schedulers and custom flexibility models, [see plugin_customization](https://flexmeasures.readthedocs.io/stable/plugin/customisation.html#plugin-customization).\n\nIf you have ideas for algorithms that should be part of FlexMeasures, let us know: [https://flexmeasures.io/get-in-touch/](https://flexmeasures.io/get-in-touch/)\n",
+        "description": "Trigger FlexMeasures to create a schedule for this asset.\nThe flex-model needs to reference the power sensors of flexible devices, which must belong to the given asset,\neither directly or indirectly, by being assigned to one of the asset's (grand)children.\n\nIn this request, you can describe:\n\n- the schedule's main features (when does it start, what unit should it report, prior to what time can we assume knowledge)\n- the flexibility models for the asset's relevant sensors (state and constraint variables, e.g. current state of charge of a battery, or connection capacity)\n- the flexibility context which the asset operates in (other sensors under the same EMS which are relevant, e.g. prices)\n\nFor details on flexibility model and context, [see describing_flexibility](https://flexmeasures.readthedocs.io/stable/features/scheduling.html#describing-flexibility).\nBelow, we'll also list some examples.\nThe schemas we use in this endpoint documentation do not describe the full flexibility model and context (as the docs do), as these are very flexible (e.g. fixed values or sensors). The examples below illustrate how to describe a flexibility model and context.\n\n> <strong>Note:</strong> This endpoint supports scheduling an EMS with multiple flexible devices at once.\n> It can do so jointly (the default) or sequentially\n> (considering previously scheduled sensors as inflexible).\n> To use sequential scheduling, use <code>sequential=true</code> in the JSON body.\n\nThe length of the schedule can be set explicitly through the 'duration' field.\nOtherwise, it is set by [a config setting](https://flexmeasures.readthedocs.io/stable/configuration.html#flexmeasures-planning-horizon), which defaults to 48 hours.\nIf the flex-model contains targets that lie beyond the planning horizon, the length of the schedule is extended to accommodate them.\nFinally, the schedule length is limited by [a config setting](https://flexmeasures.readthedocs.io/stable/configuration.html#flexmeasures-max-planning-horizon), which defaults to 2520 steps of each sensor's resolution.\nTargets that exceed the max planning horizon are not accepted.\n\nThe 'resolution' field governs how often setpoints are allowed to change.\nNote that the resulting schedule is still saved in the resolution of each individual sensor.\n\nThe appropriate algorithm is chosen by FlexMeasures (based on asset type).\nIt's also possible to use custom schedulers and custom flexibility models, [see plugin_customization](https://flexmeasures.readthedocs.io/stable/plugin/customisation.html#plugin-customization).\n\nIf you have ideas for algorithms that should be part of FlexMeasures, let us know: [https://flexmeasures.io/get-in-touch/](https://flexmeasures.io/get-in-touch/)\n",
         "security": [
           {
             "ApiKeyAuth": []
@@ -4378,6 +4546,73 @@
         ],
         "additionalProperties": false
       },
+      "AnnotationSchema": {
+        "type": "object",
+        "properties": {
+          "id": {
+            "type": "integer",
+            "readOnly": true,
+            "description": "The annotation's ID, which is automatically assigned.",
+            "example": 19
+          },
+          "source": {
+            "type": "integer",
+            "readOnly": true,
+            "description": "The annotation's data source ID, which usually corresponds to a user (it is not the user ID, though).",
+            "example": 21
+          },
+          "content": {
+            "type": "string",
+            "maxLength": 1024,
+            "description": "Text content of the annotation (max 1024 characters).",
+            "examples": [
+              "Server maintenance",
+              "Installation upgrade",
+              "Operation Main Strike"
+            ]
+          },
+          "start": {
+            "type": "string",
+            "format": "date-time",
+            "description": "Start time in ISO 8601 format.",
+            "example": "2026-02-11T17:52:03+01:00"
+          },
+          "end": {
+            "type": "string",
+            "format": "date-time",
+            "description": "End time in ISO 8601 format.",
+            "example": "2026-02-11T19:00:00+01:00"
+          },
+          "type": {
+            "type": "string",
+            "default": "label",
+            "enum": [
+              "alert",
+              "holiday",
+              "label",
+              "feedback",
+              "warning",
+              "error"
+            ],
+            "description": "Type of annotation."
+          },
+          "prior": {
+            "type": [
+              "string",
+              "null"
+            ],
+            "format": "date-time",
+            "description": "Time when the annotation was recorded, in ISO 8601 format (default: now).",
+            "example": "2026-02-01T17:43:56+01:00"
+          }
+        },
+        "required": [
+          "content",
+          "end",
+          "start"
+        ],
+        "additionalProperties": false
+      },
       "DefaultAssetViewJSONSchema": {
         "type": "object",
         "properties": {
diff --git a/flexmeasures/utils/doc_utils.py b/flexmeasures/utils/doc_utils.py
index ba887aad91..e0ddd1c140 100644
--- a/flexmeasures/utils/doc_utils.py
+++ b/flexmeasures/utils/doc_utils.py
@@ -11,6 +11,7 @@ def rst_to_openapi(text: str) -> str:
     - Converts ``inline code`` to <code>
     - Converts **bold** to <strong>
     - Converts *italic* to <em>
+    - Converts :ref:`strings <with cross-references>` to just strings
     """
 
     # Remove footnote references
@@ -56,4 +57,16 @@ def sup_repl(power_match):
     # Handle italics
     text = re.sub(r"\*(.*?)\*", r"<em>\1</em>", text)
 
+    # Handle cross-references
+    def ref_repl(match):
+        content = match.group(1)
+        # Case: "text <label>"
+        if "<" in content and content.endswith(">"):
+            visible, _label = content.rsplit("<", 1)
+            return visible.strip()
+        # Case: "label"
+        return content.strip()
+
+    text = re.sub(r":ref:`([^`]+)`", ref_repl, text)
+
     return text