openapi: 3.0.2
info:
  title: RxInferServer OpenAPI specification
  description: API for RxInferServer.jl - A Julia server for RxInfer probabilistic programming framework
  version: 1.0.0
  contact:
    name: RxInferServer Team
    url: https://github.com/lazydynamics/RxInferServer
servers:
  - url: 'http://localhost:8000/v1'
    description: Local development server
tags:
  - name: Server
    description: Server management endpoints
  - name: Authentication
    description: Authentication related endpoints
  - name: Models
    description: Model management endpoints
# Global security - apply to all endpoints by default
security:
  - ApiKeyAuth: []
paths:
  /info:
    get:
      tags:
        - Server
      summary: Get server information
      operationId: getServerInfo
      description: Returns information about the server, such as the RxInfer version, Server version, Server edition, and Julia version
      responses:
        '200':
          description: Successfully retrieved server information
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServerInfo'
              examples:
                known_versions:
                  value:
                    rxinfer_version: "4.2.0"
                    server_version: "1.0.0-DEV"
                    server_edition: "CommunityEdition"
                    julia_version: "1.11.3"
                    api_version: "v1"
                unknown_versions:
                  value:
                    rxinfer_version: "unknown"
                    server_version: "unknown" 
                    server_edition: "CommunityEdition"
                    julia_version: "1.11.3"
                    api_version: "v1"
        '401':
          description: Access token is missing or invalid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedResponse'
  /models:
    get:
      tags:
        - Models
      summary: Get models
      operationId: getModels
      description: Retrieve the list of available models and their lightweight details. Note that some access tokens might not have access to all models.
      responses:
        '200':
          description: Successfully retrieved list of models
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ModelList'
              example:
                models:
                  - name: "BetaBernoulli-v1"
                    description: "A simple beta-bernoulli model"
                  - name: "LinearRegression-v1"
                    description: "A simple linear regression model"
                  - name: "GaussianMixture-v2"
                    description: "A simple Gaussian mixture model"
        '401':
          description: Access token is missing or invalid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedResponse'
  /models/{model_name}/details:
    get:
      tags:
        - Models
      summary: Get model details
      operationId: getModelDetails
      description: Retrieve detailed information about a specific model
      parameters:
        - name: model_name
          in: path
          required: true
          schema:
            type: string
          description: Name of the model to retrieve information for (including version identifier if applicable, e.g. "BetaBernoulli-v1")
      responses:
        '200':
          description: Successfully retrieved model details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ModelDetails'
        '401':
          description: Access token is missing or invalid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedResponse'
        '404':
          description: Model not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundResponse'
              example:
                error: "Not Found"
                message: "The requested model could not be found"
  /ping:
    get:
      tags:
        - Server
      summary: Health check endpoint
      operationId: pingServer
      description: Simple endpoint to check if the server is alive and running
      # This endpoint doesn't require authentication
      security: []
      responses:
        '200':
          description: Successfully pinged the server
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PingResponse'
              example:
                status: "ok"
  /generate-token:
    post:
      tags:
        - Authentication
      summary: Generate authentication token
      operationId: generateToken
      description: Generates a new authentication token for accessing protected endpoints
      # This endpoint doesn't require authentication
      security: []
      responses:
        '200':
          description: Successfully generated authentication token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TokenResponse'
        '400':
          description: Unable to generate token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error: "Bad Request"
                message: "Unable to generate token due to internal error"
  /models/create:
    post:
      tags:
        - Models
      summary: Create a new model instance
      operationId: createModel
      description: Creates a new instance of a model with the specified configuration
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateModelRequest'
            examples:
              simple:
                value:
                  model: "BetaBernoulli-v1"
                  description: "Testing beta-bernoulli model"
              with_arguments:
                value:
                  model: "LinearRegression-v1"
                  arguments:
                    dt: 0.1
                    horizon: 10
                  description: "Linear regression with custom parameters"
      responses:
        '200':
          description: Model instance created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateModelResponse'
              example:
                model_id: "123e4567-e89b-12d3-a456-426614174000"
        '401':
          description: Access token is missing or invalid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedResponse'
        '404':
          description: Model not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundResponse'
              example:
                error: "Not Found"
                message: "The specified model does not exist"
  /models/created/info:
    get:
      tags:
        - Models
      summary: Get information about all created models for a specific token
      operationId: getCreatedModelsInfo
      description: Retrieve detailed information about all created models for a specific token
      responses:
        '200':
          description: Successfully retrieved list of created models
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/CreatedModelInfo'
        '401':
          description: Access token is missing or invalid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedResponse'
  /models/{model_id}/info:
    get:
      tags:
        - Models
      summary: Get model information
      operationId: getModelInfo
      description: Retrieve detailed information about a specific model instance
      parameters:
        - name: model_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
          description: ID of the model to retrieve information for
      responses:
        '200':
          description: Successfully retrieved model information
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreatedModelInfo'
        '401':
          description: Access token is missing, invalid or has no access to the specific model
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedResponse'
        '404':
          description: Model not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundResponse'
  /models/{model_id}/delete:
    delete:
      tags:
        - Models
      summary: Delete a model instance
      operationId: deleteModel
      description: Delete a specific model instance by its ID
      parameters:
        - name: model_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
          description: ID of the model to delete
      responses:
        '200':
          description: Model successfully deleted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
              example:
                message: "Model deleted successfully"
        '401':
          description: Access token is missing, invalid or has no access to the specific model
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedResponse'
        '404':
          description: Model not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundResponse'
components:
  securitySchemes:
    ApiKeyAuth:
      type: http
      scheme: bearer
      description: Simple token authentication. Use the Authorization header with the Bearer scheme.
  schemas:
    ServerInfo:
      type: object
      required:
        - rxinfer_version
        - server_version
        - server_edition
        - julia_version
        - api_version
      properties:
        rxinfer_version:
          type: string
          description: The version of RxInfer that the server is using, returns unknown if the version is unknown or hidden
        server_version:
          type: string
          description: The version of the RxInferServer, returns unknown if the version is unknown or hidden
        server_edition:
          type: string
          description: The edition of the RxInferServer, as set in RXINFER_EDITION environment variable
        julia_version:
          type: string
          description: The version of Julia as presented in VERSION
        api_version:
          type: string
          description: The version of the API being used
          default: "v1"
    TokenResponse:
      type: object
      required:
        - token
      properties:
        token:
          type: string
          description: The token to use in the Authorization header with the format "Bearer {token}"
    PingResponse:
      type: object
      required:
        - status
      properties:
        status:
          type: string
          description: Status of the server
          default: "ok"
    SuccessResponse:
      type: object
      required:
        - message
      properties:
        message:
          type: string
          description: Success message
      example:
        message: "Model deleted successfully"
    ErrorResponse:
      type: object
      required:
        - error
      properties:
        error:
          type: string
          description: Error message explaining the failure
        message:
          type: string
          description: Additional message providing details about the failure
      example:
        error: "Unauthorized"
        message: "The request requires authentication, generate a token using the /generate-token endpoint"
    NotFoundResponse:
      type: object
      required:
        - error
        - message
      properties:
        error:
          type: string
          description: Error type, always "Not Found" for this error
          enum: ["Not Found"]
        message:
          type: string
          description: Detailed message explaining why the resource was not found
      example:
        error: "Not Found"
        message: "The requested resource could not be found"
    UnauthorizedResponse:
      type: object
      required:
        - error
        - message
      properties:
        error:
          type: string
          description: Error type, always "Unauthorized" for this error
          enum: ["Unauthorized"]
        message:
          type: string
          description: Detailed message explaining why authentication failed
      example:
        error: "Unauthorized"
        message: "The request requires authentication, generate a token using the /generate-token endpoint"
    ModelList:
      type: object
      required:
        - models
      properties:
        models:
          type: array
          description: List of available models
          items:
            $ref: '#/components/schemas/LightweightModelDetails'
    ModelDetails:
      type: object
      required:
        - details
        - config
      properties:
        details:
          $ref: '#/components/schemas/LightweightModelDetails'
          description: Basic model details
        config:
          type: object
          description: Extended model-specific configuration
          additionalProperties: true
    LightweightModelDetails:
      type: object
      required:
        - name
        - description
      properties:
        name:
          type: string
          description: Name of the model (including version identifier, e.g. "BetaBernoulli-v1")
        description:
          type: string
          description: Brief description of the model
    CreateModelRequest:
      type: object
      required:
        - model
      properties:
        model:
          type: string
          description: The name of the model to create (including version identifier if applicable, e.g. "BetaBernoulli-v1")
        arguments:
          type: object
          description: Model-specific configuration arguments
          additionalProperties: true
        description:
          type: string
          maxLength: 128
          description: Optional description of the model instance
    CreateModelResponse:
      type: object
      required:
        - model_id
      properties:
        model_id:
          type: string
          format: uuid
          description: Unique identifier for the created model instance
    CreatedModelInfo:
      type: object
      required:
        - model_id
        - model_name
        - created_at
        - description
        - arguments
      properties:
        model_id:
          type: string
          format: uuid
          description: Unique identifier for the created model instance
        model_name:
          type: string
          description: Name of the model (including version identifier if applicable, e.g. "BetaBernoulli-v1")
        created_at:
          type: string
          format: date-time
          description: Timestamp of when the model was created
        description:
          type: string
          description: Description of the created model instance
        arguments:
          type: object
          description: Model-specific configuration arguments
          additionalProperties: true
    DeleteModelRequest:
      type: object
      required:
        - model_id
      properties:
        model_id:
          type: string
          format: uuid
          description: ID of the model to delete