Skip to main content

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 filter
  • status (optional): Status filter
  • user_role (optional): User role filter
  • department (optional): Department filter
  • limit (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 filter
  • user_id (optional): User ID filter
  • action (optional): Action filter
  • limit (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 operation
  • 400 Bad Request: Invalid request parameters
  • 401 Unauthorized: Authentication required
  • 403 Forbidden: Insufficient permissions
  • 404 Not Found: Resource not found
  • 500 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 domain
  • status: Filter by status
  • user_role: Filter by user role
  • department: Filter by department
  • sort: Sort field (e.g., created_at, confidence)
  • order: Sort order (asc or desc)

Example:

GET /query-expansion/synonyms?domain=technical&status=active&sort=confidence&order=desc&limit=50