Implementation:Langgenius Dify Annotation Service

Knowledge Sources	Langgenius_Dify
Domains	Frontend, Annotations, App Management
Last Updated	2026-02-08 00:00 GMT

Overview

Service functions for managing annotation replies on Dify applications, including CRUD operations, batch import, export, and hit-history retrieval.

Description

The Annotation Service provides a collection of plain async functions (not React Query hooks) that call Dify backend API endpoints for annotation management. Annotations are pre-defined question-answer pairs that allow apps to return curated replies when a user query matches closely enough based on an embedding similarity score. The service handles enabling/disabling annotation reply with an embedding model configuration, adjusting the score threshold, creating/editing/deleting individual annotations, batch importing annotations from file uploads, exporting annotation lists, checking batch import job status, querying annotation hit histories, and clearing all annotations for an app.

Usage

Use these functions in the Dify console to manage annotation-based auto-reply for chat and completion applications. They are typically called from annotation settings panels and annotation list views within the app configuration UI.

Code Reference

Source Location

• Repository: Langgenius_Dify
• File: web/service/annotation.ts

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: (params: { url: string, body: FormData }) => Promise<{ job_id: string, job_status: string }>
export const checkAnnotationBatchImportProgress: (params: { 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,
  clearAllAnnotations,
} from '@/service/annotation'

I/O Contract

Inputs

Name	Type	Required	Description
appId	string	Yes	The application ID to manage annotations for
action	AnnotationEnableStatus	Yes (enable/disable)	Whether to enable or disable annotation reply
embeddingModel	EmbeddingModelConfig	No	Embedding model configuration for annotation matching
score	number	No	Similarity score threshold (defaults to ANNOTATION_DEFAULT.score_threshold)
body	AnnotationItemBasic	Yes (create/edit)	The annotation question-answer pair
annotationId	string	Yes (edit/delete/history)	ID of the specific annotation
params	Record<string, any>	No	Pagination and filter parameters for list queries

Outputs

Name	Type	Description
AnnotationCreateResponse	AnnotationCreateResponse	Response after creating an annotation with the new ID
job_id	string	Batch import job identifier for status polling
job_status	string	Current status of the batch import job

Usage Examples

import { fetchAnnotationList, addAnnotation, updateAnnotationStatus } from '@/service/annotation'

// Enable annotation reply with an embedding model
await updateAnnotationStatus('app-123', 'enable', {
  embedding_provider_name: 'openai',
  embedding_model_name: 'text-embedding-ada-002',
}, 0.9)

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

// Fetch annotation list with pagination
const list = await fetchAnnotationList('app-123', { page: 1, limit: 20 })

Related Pages

• Langgenius_Dify_UseLog - Log service hooks that include annotation count queries
• Langgenius_Dify_Fetch_Layer - Underlying HTTP client used by annotation API calls