Skip to main content

Annotations and resolution

Annotations are the public review-note surface.

Routes​

The main annotation routes are:

  • GET /v1/sessions/{sessionId}/annotations
  • POST /v1/sessions/{sessionId}/annotations
  • PATCH /v1/sessions/{sessionId}/annotations/{annotationId}

Why annotations exist separately​

Annotations are not xattrs and they are not bus messages.

Use annotations when you need:

  • durable review notes
  • file-level feedback
  • resolution state such as open or resolved
  • reviewer-visible workflow commentary

Stale-content protection​

When creating an annotation, the public contract requires the client to provide the expected content hash for the file it is viewing.

That matters because review notes should not silently attach to stale content.

Retrieval model​

GET /annotations can retrieve:

  • all annotations for a session
  • only annotations for one file when filePath is provided

This is a good fit for:

  • review panes
  • code review sidebars
  • “show all unresolved comments” views

Resolution model​

The update route changes annotation status.

This is the right place to express “resolved” or “still open” semantics. Do not overload tags or cache entries for that purpose.