Implementation:Langgenius Dify Service Annotation

Knowledge Sources	Langgenius_Dify
Domains	Frontend, API_Service
Last Updated	2026-02-12 07:00 GMT

Overview

Annotation API service module providing CRUD operations for app-level annotation management including configuration, batch import, hit history tracking, and annotation reply enable/disable.

Description

annotation.ts provides a complete set of API service functions for managing annotations within Dify applications. Annotations are predefined question-answer pairs that can be used for automatic reply matching. The module includes: fetchAnnotationConfig to retrieve the current annotation settings for an app; updateAnnotationStatus to enable or disable annotation replies with optional embedding model configuration and score threshold (defaulting to ANNOTATION_DEFAULT.score_threshold); updateAnnotationScore to update the score threshold for an existing annotation setting; queryAnnotationJobStatus to poll the status of async enable/disable jobs; fetchAnnotationList to retrieve paginated annotations; fetchExportAnnotationList to export all annotations; addAnnotation to create a new annotation; editAnnotation to update an existing annotation; delAnnotation and delAnnotations to delete single or multiple annotations; annotationBatchImport to import annotations from a CSV/file via FormData (with bodyStringify: false and deleteContentType: true for multipart upload); checkAnnotationBatchImportProgress to poll batch import job status; fetchHitHistoryList to view which messages matched an annotation; and clearAllAnnotations to delete all annotations for an app.

Usage

Use this module in annotation management UI components. Import the specific functions needed for the annotation CRUD workflow, batch import operations, or hit history viewing.

Code Reference

Source Location

• Repository: Langgenius_Dify
• File: web/service/annotation.ts
• Lines: 1-73

Signature

export const fetchAnnotationConfig = (appId: string) => Promise<any>

export const updateAnnotationStatus = (
  appId: string,
  action: AnnotationEnableStatus,
  embeddingModel?: EmbeddingModelConfig,
  score?: number
) => Promise<any>

export const updateAnnotationScore = (
  appId: string,
  settingId: string,
  score: number
) => Promise<any>

export const queryAnnotationJobStatus = (
  appId: string,
  action: AnnotationEnableStatus,
  jobId: string
) => Promise<any>

export const fetchAnnotationList = (
  appId: string,
  params: Record<string, any>
) => Promise<any>

export const fetchExportAnnotationList = (appId: string) => Promise<any>

export const addAnnotation = (
  appId: string,
  body: AnnotationItemBasic
) => Promise<AnnotationCreateResponse>

export const annotationBatchImport = (
  { url, body }: { url: string, body: FormData }
) => Promise<{ job_id: string, job_status: string }>

export const checkAnnotationBatchImportProgress = (
  { jobID, appId }: { jobID: string, appId: string }
) => Promise<{ job_id: string, job_status: string }>

export const editAnnotation = (appId: string, annotationId: string, body: AnnotationItemBasic) => Promise<any>
export const delAnnotation = (appId: string, annotationId: string) => Promise<any>
export const delAnnotations = (appId: string, annotationIds: string[]) => Promise<any>
export const fetchHitHistoryList = (appId: string, annotationId: string, params: Record<string, any>) => Promise<any>
export const clearAllAnnotations = (appId: string) => Promise<any>

Import

import {
  fetchAnnotationConfig,
  updateAnnotationStatus,
  addAnnotation,
  editAnnotation,
  delAnnotation,
  fetchAnnotationList,
  annotationBatchImport,
} from '@/service/annotation'

I/O Contract

Inputs

Name	Type	Required	Description
appId	string	Yes	Application ID for scoping annotation operations
action	AnnotationEnableStatus	Varies	Enable or disable action for annotation replies
embeddingModel	EmbeddingModelConfig	No	Embedding model configuration for annotation matching
score	number	No	Score threshold for annotation matching (defaults to ANNOTATION_DEFAULT.score_threshold)
annotationId	string	Varies	Specific annotation ID for edit/delete/history operations
body	AnnotationItemBasic	Varies	Annotation content with question and answer fields
params	Record<string, any>	Varies	Pagination and filter parameters for list queries

Outputs

Name	Type	Description
AnnotationCreateResponse	AnnotationCreateResponse	Created annotation with generated ID
job_id, job_status	{ job_id: string, job_status: string }	Async job tracking for batch operations and enable/disable
annotation list	any	Paginated list of annotations
hit history	any	List of messages that matched an annotation

Usage Examples

Enable Annotation Replies

import { updateAnnotationStatus } from '@/service/annotation'

await updateAnnotationStatus('app-123', 'enable', {
  embedding_provider_name: 'openai',
  embedding_model_name: 'text-embedding-ada-002',
}, 0.9)

Add a New Annotation

import { addAnnotation } from '@/service/annotation'

const result = await addAnnotation('app-123', {
  question: 'What is Dify?',
  answer: 'Dify is an open-source LLM app development platform.',
})

Batch Import Annotations

import { annotationBatchImport } from '@/service/annotation'

const formData = new FormData()
formData.append('file', csvFile)

const { job_id } = await annotationBatchImport({
  url: `/apps/app-123/annotations/batch-import`,
  body: formData,
})

Related Pages

• Principle:Langgenius_Dify_Annotation_System
• Langgenius_Dify_Service_Base - HTTP method wrappers (get, post, del) used by all functions
• Langgenius_Dify_Use_Log - Annotation count hook that queries annotation data