RAG Service
API Docs Center
← Back to Documentation Center

Data Schemas

This page documents the data models and schemas used by the RAG API Core platform, including request/response formats and validation rules.

Core Schemas

Document Schema

{
  "id": "string",
  "filename": "string",
  "content_type": "string",
  "size_bytes": "integer",
  "upload_date": "datetime",
  "last_modified": "datetime",
  "metadata": {
    "title": "string",
    "author": "string",
    "language": "string",
    "page_count": "integer",
    "word_count": "integer"
  },
  "processing_status": "enum[pending, processing, completed, failed]",
  "index_status": "enum[not_indexed, indexing, indexed, failed]",
  "tags": ["string"],
  "permissions": {
    "owner": "string",
    "readers": ["string"],
    "writers": ["string"]
  }
}

Chat Message Schema

{
  "role": "enum[user, assistant, system]",
  "content": "string",
  "timestamp": "datetime",
  "metadata": {
    "model": "string",
    "temperature": "float",
    "tokens_used": "integer"
  }
}

Search Query Schema

{
  "query": "string",
  "filters": {
    "document_types": ["string"],
    "date_range": {
      "start": "datetime",
      "end": "datetime"
    },
    "tags": ["string"],
    "metadata_filters": "object"
  },
  "options": {
    "top_k": "integer",
    "include_content": "boolean",
    "similarity_threshold": "float",
    "rerank": "boolean"
  }
}

Search Result Schema

{
  "query": "string",
  "total_results": "integer",
  "results": [
    {
      "document_id": "string",
      "chunk_id": "string",
      "content": "string",
      "score": "float",
      "metadata": {
        "document_title": "string",
        "page_number": "integer",
        "chunk_index": "integer"
      },
      "highlights": ["string"]
    }
  ],
  "facets": {
    "document_types": [
      {
        "value": "string",
        "count": "integer"
      }
    ],
    "tags": [
      {
        "value": "string",
        "count": "integer"
      }
    ]
  },
  "processing_time_ms": "integer"
}

API Request/Response Schemas

Health Check Response

{
  "status": "enum[healthy, degraded, unhealthy]",
  "timestamp": "datetime",
  "version": "string",
  "services": {
    "database": {
      "status": "enum[up, down, degraded]",
      "response_time_ms": "integer",
      "last_checked": "datetime"
    },
    "search_index": {
      "status": "enum[up, down, degraded]",
      "document_count": "integer",
      "last_checked": "datetime"
    },
    "ai_services": {
      "status": "enum[up, down, degraded]",
      "models_available": ["string"],
      "last_checked": "datetime"
    }
  },
  "system_metrics": {
    "cpu_usage_percent": "float",
    "memory_usage_percent": "float",
    "disk_usage_percent": "float"
  }
}

Upload Document Request

{
  "file": "binary",
  "metadata": {
    "title": "string",
    "description": "string",
    "tags": ["string"],
    "custom_fields": "object"
  },
  "processing_options": {
    "extract_metadata": "boolean",
    "generate_preview": "boolean",
    "index_immediately": "boolean"
  }
}

Upload Document Response

{
  "document_id": "string",
  "upload_id": "string",
  "status": "enum[received, processing, completed, failed]",
  "estimated_processing_time": "integer",
  "processing_steps": [
    {
      "step": "string",
      "status": "enum[pending, running, completed, failed]",
      "progress_percent": "integer"
    }
  ]
}

Chat Request

{
  "messages": [
    {
      "role": "enum[user, assistant, system]",
      "content": "string"
    }
  ],
  "options": {
    "model": "string",
    "temperature": "float",
    "max_tokens": "integer",
    "stream": "boolean",
    "system_prompt": "string"
  },
  "context": {
    "document_ids": ["string"],
    "max_context_length": "integer",
    "include_sources": "boolean"
  }
}

Chat Response

{
  "message": {
    "role": "assistant",
    "content": "string",
    "timestamp": "datetime"
  },
  "usage": {
    "prompt_tokens": "integer",
    "completion_tokens": "integer",
    "total_tokens": "integer"
  },
  "sources": [
    {
      "document_id": "string",
      "chunk_id": "string",
      "content": "string",
      "score": "float",
      "metadata": "object"
    }
  ],
  "metadata": {
    "model": "string",
    "processing_time_ms": "integer",
    "model_version": "string"
  }
}

Notes - Some chat and RAG responses now include answers[] when multiple completions are requested (n > 1); the answer field mirrors the first item to preserve backwards compatibility. - When available from the provider/router, response_metadata.parameters reflects the effective generation parameters used (e.g., temperature, top_p, max_tokens, frequency_penalty, presence_penalty, repetition_penalty, stop).

Response Metadata (model_used)

Many responses include a response_metadata.model_used object describing which model actually served the request (after alias routing). This helps with auditing and debugging.

{
  "response_metadata": {
    "model_used": {
      "alias": "default",
      "provider": "azure",
      "deployment": "gpt-4o-mini", 
      "model": null
    }
  }
}

Notes - alias: The configured logical alias selected (default or overridden per request). - provider: The underlying provider (e.g., azure, openrouter, etc.). - deployment or model: One of these will be present depending on provider type. - See Endpoints > Models for alias discovery and validation: GET /api/v2/models.

Configuration Schemas

Application Configuration

{
  "azure": {
    "subscription_id": "string",
    "resource_group": "string",
    "location": "string"
  },
  "ai": {
    "openai": {
      "endpoint": "string",
      "deployment_name": "string",
      "api_version": "string"
    },
    "search": {
      "service_name": "string",
      "index_name": "string",
      "api_version": "string"
    }
  },
  "storage": {
    "account_name": "string",
    "container_name": "string"
  },
  "security": {
    "key_vault_name": "string",
    "tenant_id": "string",
    "client_id": "string"
  },
  "processing": {
    "max_file_size_mb": "integer",
    "supported_formats": ["string"],
    "chunk_size": "integer",
    "overlap_size": "integer"
  }
}

Environment Variables Schema

{
  "CONFIG_SOURCE": "enum[filesystem, blob_storage]",
  "CONFIG_PATH": "string",
  "AZURE_CLIENT_ID": "string",
  "AZURE_CLIENT_SECRET": "string",
  "AZURE_TENANT_ID": "string",
  "AZURE_SUBSCRIPTION_ID": "string",
  "AZURE_RESOURCE_GROUP": "string",
  "AZURE_LOCATION": "string",
  "AZURE_AI_SEARCH_ENDPOINT": "string",
  "AZURE_AI_SEARCH_KEY": "string",
  "AZURE_OPENAI_ENDPOINT": "string",
  "AZURE_OPENAI_KEY": "string",
  "AZURE_STORAGE_ACCOUNT": "string",
  "AZURE_STORAGE_KEY": "string",
  "AZURE_KEY_VAULT_NAME": "string",
  "LOG_LEVEL": "enum[DEBUG, INFO, WARNING, ERROR, CRITICAL]",
  "MAX_WORKERS": "integer"
}

Validation Rules

Common Validation Patterns

  • UUID Format: ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$
  • Email Format: ^[^\s@]+@[^\s@]+\.[^\s@]+$
  • URL Format: ^https?://[^\s/$.?#].[^\s]*$
  • ISO DateTime: ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d{3})?Z?$

Field Constraints

Field Type Min Max Pattern
document_id string 1 128 UUID
filename string 1 255 [\w\-. ]+
content string 1 10000 -
query string 1 1000 -
temperature float 0.0 2.0 -
max_tokens integer 1 4000 -
top_k integer 1 100 -

Error Response Schema

{
  "error": {
    "code": "string",
    "message": "string",
    "details": "object",
    "timestamp": "datetime",
    "request_id": "string"
  },
  "status_code": "integer",
  "path": "string",
  "method": "string"
}

Webhook Schemas

Document Processing Webhook

{
  "event": "document.processed",
  "document_id": "string",
  "status": "enum[completed, failed]",
  "processing_time_ms": "integer",
  "metadata": {
    "chunks_created": "integer",
    "content_length": "integer",
    "processing_errors": ["string"]
  },
  "timestamp": "datetime",
  "webhook_id": "string"
}

Chat Completion Webhook

{
  "event": "chat.completed",
  "conversation_id": "string",
  "message_count": "integer",
  "total_tokens": "integer",
  "processing_time_ms": "integer",
  "timestamp": "datetime",
  "webhook_id": "string"
}

Pagination Schema

{
  "items": ["object"],
  "pagination": {
    "page": "integer",
    "page_size": "integer",
    "total_items": "integer",
    "total_pages": "integer",
    "has_next": "boolean",
    "has_previous": "boolean",
    "next_page_url": "string",
    "previous_page_url": "string"
  }
}