Skip to main content

RAG Service: General Concepts

Our API is built on RESTful principles, using JSON for data exchange and standard HTTP methods for operations. It is designed with a focus on scalability, robust error handling, and forward compatibility to ensure that your integration remains stable as we introduce new features.

The sections below outline the core concepts — such as authentication, naming conventions, and extensibility — that apply across all endpoints.

API Extensibility​

The API is designed to support future extensions in a backward-compatible manner. Backward compatibility means that existing API clients continue to work with newer API versions without requiring updates. In general, only the following changes are considered backward compatible:

  • Adding new API endpoints
  • Adding new fields to existing request or response objects

To ensure this compatibility, the API follows several simple rules:

  • Use objects instead of primitive types for field values.
    Primitive type values (e.g., String or List[String]) cannot be safely extended without breaking clients. In contrast, object-based fields (e.g., ResearchAnswer object) allow new fields to be added without affecting existing clients.
  • Clients must tolerate and ignore unknown fields in API responses.
    This is a common practice when deserializing API responses and ensures compatibility with newly added fields.
  • Any new fields added to request objects must be optional, and the server must tolerate their absence.
    The server should apply sensible default values when such fields are not provided.

Naming Conventions​

API request and response object names, as well as their fields, use CamelCase naming conventions:

  • Object names start with an uppercase letter (e.g., ResearchRequest, Article).
  • Field names start with a lowercase letter (e.g., previousInteractionId, paraSpecs).

Required and Optional Fields​

API request and response objects include both required and optional fields. In this documentation, required fields are explicitly marked with the word Required; optional fields are unmarked.

  • API Request Objects

    • Required fields: Clients must send all required fields with valid values. Missing required fields will result in a 400 Bad Request response containing validation error details.
    • Optional fields: Clients may omit optional fields. When included, these fields must contain valid values and will be validated normally. “Empty” values, such as null, ”” (empty string), or [] (empty list), are allowed and are treated the same as not sending the field.

  • API Response Objects

    • Required fields: The server always populates required response fields with valid values.
    • Optional fields: Optional fields are omitted when they have no value (e.g., null, empty string). Optional fields with valid values are included.

API Request and Response Objects​

All API requests and responses use JSON format. For details on JSON syntax, refer to the JavaScript Object Notation (JSON) Data Interchange Format specification.

Additional rules:

  • Language fields: regular String fields containing a two-letter ISO 639-1 language code (e.g., en, fr).
  • Date fields: regular String fields formatted according to ISO 8601: YYYY-MM-DDThh:mm:ssZ (e.g., 2024-05-14T14:30:00Z)

Content-Type and Encoding​

All API endpoints accept and return application/json with utf-8 encoding, except for the streaming API which requires application/x-ndjson.

If the client sends the header Accept-Encoding: gzip, the server will return a gzip-compressed JSON response.

HTTP Status Codes​

The API follows standard HTTP status conventions. A summary of relevant codes:

  • 2xx – Success
    The request completed successfully and the response contains the requested data.
  • 4xx – Client Error
    The request is invalid. The response body includes details describing the issue.
    Examples include:
    • 403 Forbidden – Invalid or missing X-Api-Key header
    • 404 Not Found – The requested resource does not exist (e.g., incorrect article ID)
    • 429 Too Many Requests – Rate limits exceeded (tracked per API key)
    • 422 Unprocessable Entity – Returned by the Indexing API when a dataset exceeds configured limits
  • 5xx – Server Error
    An unexpected server-side error occurred. The response contains additional details. These errors are generally intermittent, and clients should retry failed requests.

HTTP Headers​

HTTP header names are case-insensitive (e.g., X-API-Key, x-api-key).

X-Api-Key​

This header is required for all endpoints that require client authentication. Typically, all endpoints require it except GET /status.

API keys are issued by Geneea and are used to authenticate the client and apply the correct configuration for processing requests.

X-Correlation-Id​

This header is accepted and returned by the API service and is used solely for tracking and debugging.

  • All endpoints accept an optional X-Correlation-Id.
  • If provided, it must contain a unique request identifier.
  • Its value is forwarded to all downstream services involved in request processing.
  • If the client does not supply one, the server generates a new unique ID.

All API responses include the X-Correlation-Id reflecting the ID used during processing.

Background asynchronous processes in the Geneea system also generate correlation IDs (using the UUIDv4 scheme) when calling downstream services.

X-Customer-Id​

This header is included by the API service when making callback requests to customer-provided APIs.

Its value is supplied by the customer and must be configured within the Geneea API service.