openapi: 3.1.0
info:
  title: Railigent X - EU Data Act REST API
  description: "# Introduction\n\nThe **Railigent X - EU Data Act REST API** allows\
    \ users to retrieve real-time streaming information from assets and access raw\
    \ data they are authorized to retrieve from the Railigent X data lake.\nThis API\
    \ provides streamlined access to streaming functionalities while ensuring regulatory\
    \ compliance with the EU Data Act.\n\nThe API returns **presigned URLs** that\
    \ provide secure access to download customer-related data files directly\nfrom\
    \ the storage system.\n\nThe API provides two categories of endpoints:\n\n• Topics\
    \ endpoints for discovering available streaming data sources\n• Consumers endpoints\
    \ for creating data consumers and retrieving streaming information for accessible\
    \ raw and meta files.\n\n# Service Usage Guide\n\nFor typical use cases, the usage\
    \ of the Railigent X - EU Data Act REST API can be characterized in principle\
    \ as a four-step workflow:\n\n[Comment: The /statistics/api.png route is correctly\
    \ resolved at runtime through asgi.py]::\n\n<img src=\"/statics/api_eudataact.png\"\
    \ alt=\"Principal Workflow for Client\" width=\"901\" height=\"281\">\n\n1. Use\
    \ the Topics endpoints to discover which streaming data sources are available\
    \ and which asset information streams are eligible for each topic. Based on the\
    \ API response, you can determine which streaming data sources are relevant for\
    \ individual use cases.\n2. Create a consumer and record its name. **Important:**\
    \ Each consumer name must be unique.\n3. Subscribe the consumer to the relevant\
    \ topics for continuous data streaming.\n4. Retrieve data for the subscribed topics.\
    \ **Important** First calls return empty as the consumer needs initialization\
    \ time. \n\n***Result:*** You continuously retrieve URLs to files containing the\
    \ live streaming information. The consumer starts at the earliest available data\
    \ in the stream if the default value for `\"autoOffsetReset\": \"latest\"` was\
    \ not changed during consumer creation.\n\n## Code Example\n\nA code example is\
    \ provided with the [GET /v1/consumers/{consumerName}/files](./docs#get-/v1/consumers/-consumerName-/files)\
    \ method.\n\n## Additional methods\n\nAdditional methods are available for a more\
    \ elaborate workflow with conditional creation of consumers and subscriptions.\n\
    \n**Adjusting streaming position of the consumer**\n\nAdjusting the consumer's\
    \ position in a data stream to re-process recent data or start from the very beginning.\
    \ This is useful for replaying events or ensuring you don't miss any data.\n\n\
    - `end` of the data stream\n- `beginning` of the data stream\n\n```\nPOST /v1/consumers/NAME/position/POSITION\n\
    \     { topics (optional) }\n└─ 204:NoContent\n```\n\n**Listing subscriptions\
    \ of a consumer**\n\nLists the topics to which the consumer \"NAME\" is subscribed\
    \ to.\n\n```\nGET /v1/consumers/NAME/subscription\n└─ topics (subscribed)\n```\n\
    \n**Unsubscribing a consumer from topics**\n\nStop receiving data from a specific\
    \ topic.\n\n```\nDELETE /v1/consumers/NAME/subscription\n└─ 204:NoContent\n```\n\
    \n**Deleting a consumer**\n\nRemove a consumer entirely when it's no longer needed.\n\
    \n```\nDELETE /v1/consumers/NAME\n└─ 204:NoContent\n```\n\n**Retrieving topic\
    \ configuration (retention time)**\n\nUnderstand details about a specific topic,\
    \ such as its data retention period.\n\n```\nGET /v1/topics/TOPIC\n└─ { configuration\
    \ }\n```\n\n## Key Concepts\n\n- **Topics** - Data streams (e.g., `com.railigent.rs.asset-features.PROJECT.CUSTOMER`)\n\
    - **Consumers** - Data receivers for one or multiple topics. Each Consumer must\
    \ have a unique name within your project to ensure independent data processing.\n\
    - **Subscriptions** - Subscription is the link between a consumer and a topic.\
    \ When a consumer subscribes to a topic, it begins to receive all new data published\
    \ to that topic.\n- **Files** - JSON messages with file meta information and a\
    \ presigned URL for downloading file content\n- **Raw files** - Contain raw data\
    \ to which the user has access to.\n- **Meta file** - Contains information on\
    \ how to decode the raw data contained in raw files.\n- **Streaming position `beginning`**\
    \ - Consumer starts at the earliest available data in the stream (up to the API's\
    \ historical retention period). This is useful for reprocessing historical data,\
    \ re-initializing an application, or ensuring no data is missed if your consumer\
    \ was offline for an extended period.\n- **Streaming position `end`** - Consumer\
    \ starts at the latest available data in the stream. The consumer discards any\
    \ unread historical messages and begins consuming only new messages published\
    \ from that point forward. This is ideal for scenarios where real-time updates\
    \ are needed and past events do not need to be processed.\n\n## Important Notes\n\
    \n⚠️ **First calls return empty** - When you first create or activate a consumer,\
    \ its initial data retrieval calls may return empty. This is normal as the consumer\
    \ initializes. Please allow a few seconds and retry your request.\n⚠️ **Successful\
    \ call returns empty** - If a successful response (200) returns empty, there are\
    \ no new files to be retrieved. Retry after some time. If there should be newer\
    \ data to be retrieved, contact support.\n⚠️ **Consumer names must be unique**\
    \ - Each consumer you create must have a unique name within your project. The\
    \ API does not currently provide a method to list existing consumer names, so\
    \ we recommend maintaining your own record of the consumer names you create.\n\
    \n## Data retention\n\nTo use the full historical retention period, create a consumer\
    \ with the default offset `\"autoOffsetReset\": \"latest\"` or position the consumer\
    \ to the `beginning`.\n\n- **Messages in the data stream** = 1 day in the past\n\
    \n\n# Service Access Control\n\nOnly authenticated and authorized access to the\
    \ API is allowed. You can use your \nRailigent X credentials that you have received\
    \ from the Railigent X Support Desk.\n\n# Service Usage Limits\n\nDepending on\
    \ your individual API subscription, service usage limits (maximum \nnumber of\
    \ requests per minute and maximum number of requests per hour) may apply. \nWhen\
    \ reaching a service usage limit, all subsequent requests will yield a HTTP \n\
    status code of `429` until the service usage limit is automatically reset.\n\n\
    The pre-signed URL for EU Data Act compliant calls is valid for 1 h after the\
    \ URL was created. \nThe URL is created internally when the files route is used.\n\
    \n# Service Changelog\n\nAPI versioning is based on the Semantic Versioning 2.0.0.\n\
    \n## Version 1.0.0:\n\n• Initial Release  \n• Compliance with Xcelerator REST\
    \ API Guidelines V2\n\n# Support\n\n**Issues:** Secure-operations.mobility@siemens.com\
    \  \n"
  termsOfService: https://www.mobility.siemens.com/global/en/general/terms-of-use.html
  contact:
    name: Railigent X Support Desk
    url: https://www.railigent.com/
    email: secure-operations.mobility@siemens.com
  version: 1.0.0
paths:
  /v1/topics:
    get:
      tags:
      - Topics
      summary: List topics
      description: Retrieve a list of available Kafka topics
      operationId: list_topics
      responses:
        '200':
          description: All accessible topics retrieved successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListTopicResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error400Response'
        '404':
          description: Not Found or Permission Denied
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error404Response'
        '422':
          description: Unprocessable Entity
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error422Response'
        '429':
          description: Too Many Requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error429Response'
        '500':
          description: Internal Service Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error500Response'
      security:
      - GatewayConsumerHTTPBasic: []
  /v1/topics/{topicName}:
    get:
      tags:
      - Topics
      summary: Retrieve topic metadata
      description: Retrieve the metadata of a given topic, including retention.ms
        configuration
      operationId: get_individual_topic
      security:
      - GatewayConsumerHTTPBasic: []
      parameters:
      - name: topicName
        in: path
        required: true
        schema:
          type: string
          minLength: 1
          description: Name of the topic to retrieve
          examples:
          - com.railigent.rs.eu-data-act.raw.vectron.customer
          title: Topicname
        description: Name of the topic to retrieve
      responses:
        '200':
          description: Successfully retrieved metadata about the specified topic
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TopicMetadataResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error400Response'
        '404':
          description: Not Found or Permission Denied
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error404Response'
        '422':
          description: Unprocessable Entity
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error422Response'
        '429':
          description: Too Many Requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error429Response'
        '500':
          description: Internal Service Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error500Response'
  /v1/consumers/{consumerName}:
    post:
      tags:
      - Consumers
      summary: Create a consumer instance
      description: Create a consumer instance
      operationId: create_consumer
      security:
      - GatewayConsumerHTTPBasic: []
      parameters:
      - name: consumerName
        in: path
        required: true
        schema:
          type: string
          pattern: ^[a-zA-Z][a-zA-Z0-9-]{0,47}$
          description: Name of the consumer instance to be created
          title: Consumername
        description: Name of the consumer instance to be created
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ConsumerConfiguration'
              description: Settings for new consumer instance
      responses:
        '201':
          description: Consumer instance created successfully.
          content:
            application/json:
              schema: {}
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error400Response'
        '404':
          description: Not Found or Permission Denied
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error404Response'
        '422':
          description: Unprocessable Entity
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error422Response'
        '429':
          description: Too Many Requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error429Response'
        '500':
          description: Internal Service Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error500Response'
        '409':
          description: Consumer instance with the same name already exists.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error409AlreadyExistsResponse'
    delete:
      tags:
      - Consumers
      summary: Delete consumer instance
      description: Delete a specified consumer instance
      operationId: delete_consumer
      security:
      - GatewayConsumerHTTPBasic: []
      parameters:
      - name: consumerName
        in: path
        required: true
        schema:
          type: string
          pattern: ^[a-zA-Z][a-zA-Z0-9-]{0,47}$
          description: Name of the consumer instance to delete
          title: Consumername
        description: Name of the consumer instance to delete
      responses:
        '204':
          description: Consumer instance deleted successfully.
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error400Response'
        '404':
          description: Not Found or Permission Denied
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error404Response'
        '422':
          description: Unprocessable Entity
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error422Response'
        '429':
          description: Too Many Requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error429Response'
        '500':
          description: Internal Service Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error500Response'
  /v1/consumers/{consumerName}/subscription:
    post:
      tags:
      - Consumers
      summary: Subscribe consumer to topics
      description: Subscribe a consumer to one or more topics
      operationId: create_subscription
      security:
      - GatewayConsumerHTTPBasic: []
      parameters:
      - name: consumerName
        in: path
        required: true
        schema:
          type: string
          pattern: ^[a-zA-Z][a-zA-Z0-9-]{0,47}$
          description: Name of the consumer instance to subscribe to topics
          title: Consumername
        description: Name of the consumer instance to subscribe to topics
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Subscription'
              description: Subscriptions
      responses:
        '204':
          description: Consumer subscribed successfully.
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error400Response'
        '404':
          description: Not Found or Permission Denied
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error404Response'
        '422':
          description: Unprocessable Entity
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error422Response'
        '429':
          description: Too Many Requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error429Response'
        '500':
          description: Internal Service Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error500Response'
        '409':
          description: Subscriptions to topics and partitions are mutually exclusive.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error409MutuallyExclusiveResponse'
    delete:
      tags:
      - Consumers
      summary: Unsubscribe consumer from all topics
      description: Unsubscribe a consumer from all topics
      operationId: delete_subscription
      security:
      - GatewayConsumerHTTPBasic: []
      parameters:
      - name: consumerName
        in: path
        required: true
        schema:
          type: string
          pattern: ^[a-zA-Z][a-zA-Z0-9-]{0,47}$
          description: Name of the consumer instance to unsubscribe from all topics
          title: Consumername
        description: Name of the consumer instance to unsubscribe from all topics
      responses:
        '204':
          description: Consumer unsubscribed successfully from all topics.
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error400Response'
        '404':
          description: Not Found or Permission Denied
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error404Response'
        '422':
          description: Unprocessable Entity
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error422Response'
        '429':
          description: Too Many Requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error429Response'
        '500':
          description: Internal Service Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error500Response'
    get:
      tags:
      - Consumers
      summary: Retrieve subscribed topics
      description: Retrieve a list of the topics to which the consumer is subscribed
      operationId: retrieve_subscribed_topics
      security:
      - GatewayConsumerHTTPBasic: []
      parameters:
      - name: consumerName
        in: path
        required: true
        schema:
          type: string
          pattern: ^[a-zA-Z][a-zA-Z0-9-]{0,47}$
          description: Name of the subscribed consumer instance
          title: Consumername
        description: Name of the subscribed consumer instance
      responses:
        '200':
          description: Subscribed topics retrieved successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RetrievedTopicsResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error400Response'
        '404':
          description: Not Found or Permission Denied
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error404Response'
        '422':
          description: Unprocessable Entity
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error422Response'
        '429':
          description: Too Many Requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error429Response'
        '500':
          description: Internal Service Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error500Response'
  /v1/consumers/{consumerName}/positions/{position}:
    post:
      tags:
      - Consumers
      summary: Configure consumer to seek a position in the stream
      description: Configure a subscribed consumer to seek the first or last position
        in the stream
      operationId: set_position_beginning_end
      security:
      - GatewayConsumerHTTPBasic: []
      parameters:
      - name: consumerName
        in: path
        required: true
        schema:
          type: string
          pattern: ^[a-zA-Z][a-zA-Z0-9-]{0,47}$
          description: Name of the consumer instance to set position
          title: Consumername
        description: Name of the consumer instance to set position
      - name: position
        in: path
        required: true
        schema:
          type: string
          pattern: ^(beginning|end)$
          description: Logical position to seek
          examples:
          - end
          title: Position
        description: Logical position to seek
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Subscription'
              description: Topics to position or null for all
      responses:
        '204':
          description: Seek to the beginning or end performed successfully.
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error400Response'
        '404':
          description: Not Found or Permission Denied
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error404Response'
        '422':
          description: Unprocessable Entity
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error422Response'
        '429':
          description: Too Many Requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error429Response'
        '500':
          description: Internal Service Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error500Response'
  /v1/consumers/{consumerName}/files:
    get:
      tags:
      - Consumers
      - With code samples
      summary: Retrieve files per consumer
      description: Retrieve files for a subscribed consumer
      operationId: retrieve_files
      security:
      - GatewayConsumerHTTPBasic: []
      parameters:
      - name: consumerName
        in: path
        required: true
        schema:
          type: string
          minLength: 1
          maxLength: 48
          description: Name of the subscribed consumer instance to retrieve files
          title: Consumername
        description: Name of the subscribed consumer instance to retrieve files
      responses:
        '200':
          description: Presigned URL file information. There might be no new files
            when an empty data array is returned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RetrievedFilesResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error400Response'
        '404':
          description: Not Found or Permission Denied
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error404Response'
        '422':
          description: Unprocessable Entity
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error422Response'
        '429':
          description: Too Many Requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error429Response'
        '500':
          description: Internal Service Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error500Response'
      x-code-samples:
      - lang: toml
        label: pyproject.toml
        source: "\n[project]\nname = \"example-client\"\nversion = \"0.1.0\"\ndescription\
          \ = \"Railigent X Streaming Data REST API Example Client\"\nrequires-python\
          \ = \">=3.13\"\ndependencies = [\n    \"requests>=2.32.5\"\n]\n        \
          \        "
      - lang: python
        label: Python
        source: "\"\"\"\nExample code to access the data provided by the Railigent\
          \ X Streaming API\n\"\"\"\nimport logging\nimport signal\nimport sys\nimport\
          \ time\n\nimport requests  # package requests >= \"2.35.5\" is required\n\
          from requests.auth import HTTPBasicAuth\n\n\ndef fail(how: str):\n    logging.error('FAILED\
          \ %s', how)\n    sys.exit(1)\n\n\ndef resumable_consumer(endpoint: str =\
          \ 'https://example.api.railigent.com',\n         \
          \              name: str = 'example',\n                       topic: str\
          \ = 'com.railigent.rs.eu-data-act.raw.vectron.customer'):\n    session =\
          \ requests.Session()\n    session.auth = HTTPBasicAuth('YOUR-USERNAME',\
          \ 'YOUR-PASSWORD')\n    need_consumer = False\n    need_subscription = False\n\
          \    with session.get(url=f'{endpoint}/v1/consumers/{name}/subscription')\
          \ as response:\n        if response.status_code == 200:\n            need_subscription\
          \ = topic not in response.json()['data']['topics']\n        elif response.status_code\
          \ == 404:  # no such consumer found\n            need_consumer = True\n\
          \        else:\n            fail(f\"get_topics {response.status_code} {response.text}\"\
          )\n    if need_consumer:\n        with session.post(url=f'{endpoint}/v1/consumers/{name}',\
          \ json={}) as response:\n            if response.status_code != 201:\n \
          \               fail(f\"create_consumer {response.status_code} {response.text}\"\
          )\n    if need_subscription:\n        with session.post(url=f'{endpoint}/v1/consumers/{name}/subscription',\
          \ json={'topics': [topic]}) as response:\n            if response.status_code\
          \ != 204:\n                fail(f\"subscribe_consumer {response.status_code}\
          \ {response.text}\")\n\n    read_forever(endpoint, name, session)\n\n\n\
          def read_forever(endpoint, name, session):\n    forever = True\n\n    def\
          \ stop(_x, _y):\n        nonlocal forever\n        forever = False\n\n \
          \   signal.signal(signal.SIGTERM, stop)\n    signal.signal(signal.SIGINT,\
          \ stop)\n    while forever:\n        with session.get(url=f'{endpoint}/v1/consumers/{name}/files')\
          \ as response:\n            if response.status_code == 429:\n          \
          \      time.sleep(float(response.headers.get('Retry-After', 0.3)))\n   \
          \         elif response.status_code != 200:\n                fail(f\"fetch_data\
          \ {response.status_code} {response.text}\")\n            else:\n       \
          \         got = response.json()['data']\n                if got:\n     \
          \               for message in got:\n                        print(f\"{message}\"\
          )\n                else:\n                    time.sleep(1.0)  # no data\
          \ received, wait a bit\n\n\nif __name__ == '__main__':\n    logging.basicConfig(level='DEBUG',\
          \ stream=sys.stderr)\n    resumable_consumer()\n"
components:
  schemas:
    ConsumerConfiguration:
      properties:
        autoOffsetReset:
          $ref: '#/components/schemas/OffsetResetEnum'
          title: autoOffsetReset
          description: Retrieve earliest or latest records.
          default: latest
      type: object
      title: ConsumerConfiguration
      example:
        autoOffsetReset: latest
    Error400Response:
      properties:
        errors:
          items:
            $ref: '#/components/schemas/XceleratorApiError'
          type: array
          title: errors
          description: Optional error payload.
          examples:
          - code: RLGTX-000
            correlationId: 50a37dfa-ae2b-4a66-a439-3862145d59dd
            detail: Error details for client-side diagnosis.
            status: '418'
            title: Error summary.
      type: object
      required:
      - errors
      title: Error400Response
      example:
        errors:
        - code: RLGTX-400
          detail: The request could not be understood or was missing required parameters.
          status: '400'
          title: Bad Request
    Error404Response:
      properties:
        errors:
          items:
            $ref: '#/components/schemas/XceleratorApiError'
          type: array
          title: errors
          description: Optional error payload.
          examples:
          - code: RLGTX-000
            correlationId: 50a37dfa-ae2b-4a66-a439-3862145d59dd
            detail: Error details for client-side diagnosis.
            status: '418'
            title: Error summary.
      type: object
      required:
      - errors
      title: Error404Response
      example:
        errors:
        - code: RLGTX-404
          detail: The requested resource could not be found or you do not have permission
            to access it.
          status: '404'
          title: Not Found or Permission Denied
    Error409AlreadyExistsResponse:
      properties:
        errors:
          items:
            $ref: '#/components/schemas/XceleratorApiError'
          type: array
          title: errors
          description: Optional error payload.
          examples:
          - code: RLGTX-000
            correlationId: 50a37dfa-ae2b-4a66-a439-3862145d59dd
            detail: Error details for client-side diagnosis.
            status: '418'
            title: Error summary.
      type: object
      required:
      - errors
      title: Error409AlreadyExistsResponse
      example:
        errors:
        - code: RLGTX-409
          detail: A consumer instance with the specified name already exists.
          status: '409'
          title: Conflict
    Error409MutuallyExclusiveResponse:
      properties:
        errors:
          items:
            $ref: '#/components/schemas/XceleratorApiError'
          type: array
          title: errors
          description: Optional error payload.
          examples:
          - code: RLGTX-000
            correlationId: 50a37dfa-ae2b-4a66-a439-3862145d59dd
            detail: Error details for client-side diagnosis.
            status: '418'
            title: Error summary.
      type: object
      required:
      - errors
      title: Error409MutuallyExclusiveResponse
      example:
        errors:
        - code: RLGTX-409
          detail: Subscriptions to topics, partitions, and patterns are mutually exclusive.
          status: '409'
          title: Conflict
    Error422Response:
      properties:
        errors:
          items:
            $ref: '#/components/schemas/XceleratorApiError'
          type: array
          title: errors
          description: Optional error payload.
          examples:
          - code: RLGTX-000
            correlationId: 50a37dfa-ae2b-4a66-a439-3862145d59dd
            detail: Error details for client-side diagnosis.
            status: '418'
            title: Error summary.
      type: object
      required:
      - errors
      title: Error422Response
      example:
        errors:
        - code: RLGTX-422
          detail: The request was well-formed but contains semantic errors or violates
            business rules.
          status: '422'
          title: Unprocessable Entity
    Error429Response:
      properties:
        errors:
          items:
            $ref: '#/components/schemas/XceleratorApiError'
          type: array
          title: errors
          description: Optional error payload.
          examples:
          - code: RLGTX-000
            correlationId: 50a37dfa-ae2b-4a66-a439-3862145d59dd
            detail: Error details for client-side diagnosis.
            status: '418'
            title: Error summary.
      type: object
      required:
      - errors
      title: Error429Response
      example:
        errors:
        - code: RLGTX-429
          detail: The user has sent too many requests in a given amount of time (rate
            limiting).
          status: '429'
          title: Too Many Requests
    Error500Response:
      properties:
        errors:
          items:
            $ref: '#/components/schemas/XceleratorApiError'
          type: array
          title: errors
          description: Optional error payload.
          examples:
          - code: RLGTX-000
            correlationId: 50a37dfa-ae2b-4a66-a439-3862145d59dd
            detail: Error details for client-side diagnosis.
            status: '418'
            title: Error summary.
      type: object
      required:
      - errors
      title: Error500Response
      example:
        errors:
        - code: RLGTX-500
          detail: The requested resource could not be served due to an internal service
            error.
          status: '500'
          title: Internal Service Error
    ListTopicResponse:
      properties:
        data:
          items:
            type: string
          type: array
          title: data
          description: List all topics.
      type: object
      required:
      - data
      title: ListTopicResponse
      example:
        data:
        - com.railigent.rs.eu-data-act.raw.vectron.customer
        - com.railigent.rs.eu-data-act.meta.vectron.customer
    OffsetResetEnum:
      type: string
      enum:
      - earliest
      - latest
      title: OffsetResetEnum
    RetrievedFilesResponse:
      properties:
        data:
          items:
            $ref: '#/components/schemas/RetrievedPresignedUrls'
          type: array
          title: data
          description: Retrieved file information
      type: object
      required:
      - data
      title: RetrievedFilesResponse
      example:
        data:
        - fileName: file1.txt
          presignedUrl: https://example.com/presigned_url_file1.txt
          size: 98679
          topic: com.railigent.rs.eu-data-act.raw.vectron.customer
          ts: '2025-11-17T20:15:34.789Z'
        - fileName: file2.txt
          presignedUrl: https://example.com/presigned_url_file2.txt
          size: 1
          topic: com.railigent.rs.eu-data-act.raw.vectron.customer
    RetrievedPresignedUrls:
      properties:
        topic:
          type: string
          title: topic
          description: Name of the topic.
        fileName:
          type: string
          title: fileName
          description: Name of the file to generate a presigned URL for.
        presignedUrl:
          type: string
          title: presignedUrl
          description: Presigned URL for accessing the S3 object.
        size:
          anyOf:
          - type: integer
          - type: 'null'
          title: size
          description: Length of file in bytes.
        ts:
          anyOf:
          - type: string
          - type: 'null'
          title: ts
          description: Event timestamp.
      type: object
      required:
      - topic
      - fileName
      - presignedUrl
      title: RetrievedPresignedUrls
    RetrievedTopics:
      properties:
        topics:
          items:
            type: string
          type: array
          title: topics
          description: List of subscribed topics.
      type: object
      title: RetrievedTopics
    RetrievedTopicsResponse:
      properties:
        data:
          $ref: '#/components/schemas/RetrievedTopics'
          title: data
          description: Retrieves the list of topics for a subscribed consumer.
      type: object
      required:
      - data
      title: RetrievedTopicsResponse
      example:
        data:
          topics:
          - topic1
          - topic2
    Subscription:
      properties:
        topics:
          items:
            type: string
          type: array
          minItems: 1
          title: topics
          description: List of topics to be subscribed.
      type: object
      required:
      - topics
      title: Subscription
      example:
        topics:
        - com.railigent.rs.eu-data-act.raw.vectron.customer
        - com.railigent.rs.eu-data-act.meta.vectron.customer
    Topic:
      properties:
        name:
          type: string
          title: name
          description: Name of the topic.
        configuration:
          additionalProperties:
            type: string
          type: object
          title: configuration
          description: Configuration settings for the topic.
      type: object
      required:
      - name
      - configuration
      title: Topic
    TopicMetadataResponse:
      properties:
        data:
          $ref: '#/components/schemas/Topic'
          title: data
          description: Representation of a topic with its configuration settings.
      type: object
      required:
      - data
      title: TopicMetadataResponse
      example:
        data:
          configuration:
            retention.ms: '604800000'
          name: topic1
    XceleratorApiError:
      properties:
        code:
          anyOf:
          - type: string
          - type: 'null'
          title: code
          description: Railigent X error code.
          examples:
          - RLGTX-000
        status:
          anyOf:
          - type: string
          - type: 'null'
          title: status
          description: HTTP status code.
          examples:
          - '418'
        title:
          anyOf:
          - type: string
          - type: 'null'
          title: title
          description: Summary of the error.
          examples:
          - Error summary.
        detail:
          anyOf:
          - type: string
          - type: 'null'
          title: detail
          description: Detailed description of the error.
          examples:
          - Error details for client-side diagnosis.
        correlationId:
          anyOf:
          - type: string
          - type: 'null'
          title: correlationId
          description: Error correlation information.
          examples:
          - 50a37dfa-ae2b-4a66-a439-3862145d59dd
      type: object
      required:
      - code
      - status
      - title
      - detail
      title: XceleratorApiError
  securitySchemes:
    GatewayConsumerHTTPBasic:
      type: http
      scheme: basic
tags:
- name: EU-Data-Act
  description: Endpoints for Streaming Data REST API.
