Query Expansion API Reference
This document provides a comprehensive reference for the Query Expansion System API endpoints and data structures.
Base URL
All query expansion endpoints are available under the /query-expansion
prefix:
https://your-api-domain.com/query-expansion
Authentication
All endpoints require authentication. Include the user ID in the request context or use the appropriate authentication method.
Core Endpoints
Query Expansion
POST /query-expansion/expand
Expand a query using multiple strategies.
Request Body:
{
"query": "API documentation",
"user_id": "user123",
"user_role": "developer",
"department": "engineering",
"domain": "technical",
"session_id": "session123",
"enabled_strategies": ["synonym_expansion", "acronym_expansion"],
"expansion_settings": {
"max_expansions": 3,
"confidence_threshold": 0.7
}
}
Response:
{
"original_query": "API documentation",
"expanded_queries": [
{
"expanded_query": "API documentation OR Application Programming Interface documentation",
"expansion_type": "synonym_expansion",
"confidence_score": 0.9,
"relevance_score": 0.8,
"synonyms_used": [
{
"term": "API",
"synonym": "Application Programming Interface",
"confidence": 0.9
}
],
"metadata": {
"expanded_token": "API",
"synonym_count": 1
}
}
],
"expansion_metadata": {
"total_expansions": 1,
"strategies_used": ["synonym_expansion"],
"avg_confidence": 0.9
},
"success": true
}
POST /query-expansion/feedback
Submit user feedback on expansion effectiveness.
Request Body:
{
"expansion_id": "exp_123",
"was_helpful": true,
"rating": 5,
"comment": "Very helpful expansion"
}
Response:
{
"success": true,
"message": "Feedback recorded successfully"
}
Synonym Management
POST /query-expansion/synonyms
Add a new synonym.
Request Body:
{
"term": "ML",
"synonym": "Machine Learning",
"domain": "technical",
"confidence": 0.9,
"context": "artificial intelligence",
"user_role": "developer",
"department": "engineering",
"tags": ["ai", "learning"],
"notes": "Machine learning abbreviation"
}
Response:
{
"success": true,
"message": "Synonym added successfully",
"synonym_id": 123
}
GET /query-expansion/synonyms
Get synonyms with filtering.
Query Parameters:
domain
(optional): Domain filterstatus
(optional): Status filteruser_role
(optional): User role filterdepartment
(optional): Department filterlimit
(optional): Maximum results (default: 100)offset
(optional): Result offset (default: 0)
Response:
{
"synonyms": [
{
"id": 123,
"term": "API",
"synonym": "Application Programming Interface",
"domain": "technical",
"confidence": 0.9,
"relevance_score": 0.8,
"usage_count": 15,
"success_rate": 0.85,
"status": "active",
"created_by": "admin_user",
"created_at": "2024-01-01T00:00:00Z",
"updated_at": "2024-01-01T00:00:00Z",
"tags": ["programming", "interface"],
"notes": "Common programming interface"
}
],
"total": 1
}
PUT /query-expansion/synonyms/{synonym_id}
Update a synonym entry.
Path Parameters:
synonym_id
(int): Synonym ID
Request Body:
{
"confidence": 0.95,
"notes": "Updated confidence score",
"reason": "Improved based on user feedback"
}
Response:
{
"success": true,
"message": "Synonym updated successfully"
}
DELETE /query-expansion/synonyms/{synonym_id}
Delete a synonym entry.
Path Parameters:
synonym_id
(int): Synonym ID
Request Body:
{
"reason": "Outdated terminology"
}
Response:
{
"success": true,
"message": "Synonym deleted successfully"
}
Analytics
GET /query-expansion/analytics/expansion
Get expansion analytics.
Query Parameters:
start_date
(optional): Start date filter (ISO format)end_date
(optional): End date filter (ISO format)domain
(optional): Domain filter
Response:
{
"metrics": {
"total_expansions": 1000,
"successful_expansions": 850,
"success_rate": 0.85,
"average_confidence": 0.78,
"average_relevance": 0.82,
"domain_breakdown": {
"technical": 600,
"business": 400
},
"user_satisfaction": 0.85,
"expansion_quality_score": 0.81
}
}
GET /query-expansion/analytics/synonyms
Get synonym analytics.
Query Parameters:
domain
(optional): Domain filter
Response:
{
"metrics": {
"total_synonyms": 500,
"active_synonyms": 450,
"popular_synonyms": [
{
"term": "API",
"synonym": "Application Programming Interface",
"domain": "technical",
"usage_count": 150,
"success_rate": 0.9,
"confidence": 0.95
}
],
"domain_distribution": {
"technical": 300,
"business": 200
},
"source_breakdown": {
"manual_curation": 400,
"user_feedback": 100
},
"confidence_distribution": {
"high": 200,
"medium": 200,
"low": 100
},
"usage_frequency": {
"0": 50,
"1-10": 200,
"11-50": 150,
"51+": 100
},
"success_rates": {
"API_Application Programming Interface": 0.9,
"SQL_Structured Query Language": 0.85
}
}
}
GET /query-expansion/analytics/report
Get comprehensive analytics report.
Query Parameters:
start_date
(optional): Start date filter (ISO format)end_date
(optional): End date filter (ISO format)domain
(optional): Domain filter
Response:
{
"report_metadata": {
"generated_at": "2024-01-01T00:00:00Z",
"start_date": "2024-01-01T00:00:00Z",
"end_date": "2024-01-31T23:59:59Z",
"domain": "technical"
},
"expansion_metrics": {
"total_expansions": 1000,
"successful_expansions": 850,
"success_rate": 0.85,
"average_confidence": 0.78,
"average_relevance": 0.82,
"domain_breakdown": {
"technical": 600,
"business": 400
},
"user_satisfaction": 0.85,
"expansion_quality_score": 0.81
},
"synonym_metrics": {
"total_synonyms": 500,
"active_synonyms": 450,
"popular_synonyms": [...],
"domain_distribution": {...},
"source_breakdown": {...},
"confidence_distribution": {...},
"usage_frequency": {...},
"success_rates": {...}
},
"user_behavior_metrics": {
"total_users": 100,
"active_users": 75,
"user_engagement": {
"avg_expansions_per_user": 13.3
},
"role_preferences": {
"developer": {
"usage_count": 600,
"avg_confidence": 0.8,
"success_rate": 0.85
},
"manager": {
"usage_count": 400,
"avg_confidence": 0.75,
"success_rate": 0.8
}
},
"department_usage": {
"engineering": 600,
"business": 400
},
"feedback_patterns": {
"total_feedback": 200,
"feedback_by_type": {
"positive": 150,
"negative": 50
},
"average_rating": 4.2
},
"satisfaction_trends": [
{
"date": "2024-01-01",
"satisfaction": 0.8
}
]
},
"quality_metrics": {
"precision_score": 0.82,
"recall_score": 0.78,
"f1_score": 0.80,
"false_positive_rate": 0.18,
"false_negative_rate": 0.22,
"domain_accuracy": {
"technical": 0.85,
"business": 0.75
},
"user_rating_distribution": {
"5": 100,
"4": 50,
"3": 30,
"2": 15,
"1": 5
},
"quality_trends": [
{
"date": "2024-01-01",
"precision": 0.8,
"recall": 0.75,
"f1": 0.77
}
]
},
"insights": [
{
"type": "positive",
"category": "expansion_effectiveness",
"message": "High expansion success rate: 85%",
"impact": "high"
},
{
"type": "warning",
"category": "synonym_utilization",
"message": "Low synonym utilization: 450/500 active",
"impact": "medium"
}
],
"recommendations": [
{
"category": "expansion_optimization",
"priority": "high",
"action": "Improve expansion quality",
"description": "Focus on improving synonym confidence and relevance scoring",
"impact": "high"
},
{
"category": "synonym_management",
"priority": "medium",
"action": "Review and curate synonyms",
"description": "Remove unused synonyms and improve quality of existing ones",
"impact": "medium"
}
]
}
Admin Operations
GET /query-expansion/admin/dashboard
Get admin dashboard data.
Response:
{
"summary": {
"total_synonyms": 500,
"active_synonyms": 450,
"pending_synonyms": 25,
"deprecated_synonyms": 25,
"avg_confidence": 0.78,
"avg_success_rate": 0.82
},
"domain_distribution": {
"technical": 300,
"business": 200
},
"recent_activity": {
"create": 10,
"update": 5,
"delete": 2
},
"top_contributors": {
"admin_user": 100,
"domain_expert_1": 75,
"user_123": 50
}
}
GET /query-expansion/admin/audit-log
Get audit log entries.
Query Parameters:
synonym_id
(optional): Synonym ID filteruser_id
(optional): User ID filteraction
(optional): Action filterlimit
(optional): Maximum results (default: 100)
Response:
{
"audit_entries": [
{
"id": 1,
"synonym_id": 123,
"action": "create",
"performed_by": "admin_user",
"performed_at": "2024-01-01T00:00:00Z",
"old_values": null,
"new_values": {
"term": "API",
"synonym": "Application Programming Interface"
},
"reason": "New synonym created"
}
],
"total": 1
}
POST /query-expansion/admin/bulk-import
Bulk import synonyms from file.
Request Body:
{
"file_path": "/path/to/synonyms.csv",
"import_format": "csv",
"domain": "technical"
}
Response:
{
"success": true,
"result": {
"total_records": 100,
"successful_imports": 95,
"failed_imports": 5,
"conflicts_detected": 2,
"errors": [
{
"row": 10,
"error": "Missing required fields: term or synonym",
"data": {"term": "", "synonym": "test"}
}
],
"warnings": [
{
"row": 15,
"warning": "Conflicts detected for API -> Application Programming Interface",
"conflicts": ["exact_match"]
}
]
}
}
POST /query-expansion/admin/export
Export synonyms to file.
Request Body:
{
"output_path": "/path/to/export.csv",
"export_format": "csv",
"domain": "technical",
"status": "active"
}
Response:
{
"success": true,
"message": "Export completed successfully"
}
Data Types
ExpansionType
enum ExpansionType {
SYNONYM_EXPANSION = "synonym_expansion",
ACRONYM_EXPANSION = "acronym_expansion",
ABBREVIATION_EXPANSION = "abbreviation_expansion",
DOMAIN_SPECIFIC = "domain_specific",
CONTEXTUAL = "contextual",
SEMANTIC = "semantic"
}
SynonymSource
enum SynonymSource {
MANUAL_CURATION = "manual_curation",
USER_FEEDBACK = "user_feedback",
ML_DISCOVERY = "ml_discovery",
DOMAIN_EXPERT = "domain_expert",
COLLABORATIVE = "collaborative",
EXTERNAL_API = "external_api"
}
SynonymStatus
enum SynonymStatus {
ACTIVE = "active",
PENDING = "pending",
REJECTED = "rejected",
DEPRECATED = "deprecated",
UNDER_REVIEW = "under_review"
}
Error Responses
All endpoints return appropriate HTTP status codes and error messages:
200 OK
: Successful operation400 Bad Request
: Invalid request parameters401 Unauthorized
: Authentication required403 Forbidden
: Insufficient permissions404 Not Found
: Resource not found500 Internal Server Error
: Server error
Error Response Format:
{
"error": "Invalid query parameter",
"message": "The 'query' parameter is required",
"code": "MISSING_QUERY_PARAMETER",
"details": {
"field": "query",
"expected_type": "string",
"provided_value": null
}
}
Rate Limiting
API endpoints are rate-limited to prevent abuse:
- Query Expansion: 100 requests per minute per user
- Synonym Management: 50 requests per minute per user
- Analytics: 20 requests per minute per user
- Admin Operations: 10 requests per minute per user
Rate limit headers are included in responses:
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1640995200
Pagination
List endpoints support pagination:
Query Parameters:
limit
: Number of results per page (default: 100, max: 1000)offset
: Number of results to skip (default: 0)
Response Headers:
X-Total-Count: 1000
X-Page-Size: 100
X-Page-Offset: 0
X-Has-More: true
Filtering and Sorting
Many endpoints support filtering and sorting:
Query Parameters:
domain
: Filter by domainstatus
: Filter by statususer_role
: Filter by user roledepartment
: Filter by departmentsort
: Sort field (e.g.,created_at
,confidence
)order
: Sort order (asc
ordesc
)
Example:
GET /query-expansion/synonyms?domain=technical&status=active&sort=confidence&order=desc&limit=50