{
  "openapi": "3.1.0",
  "info": {
    "title": "Sol API",
    "version": "1.2.0",
    "description": "Read-only grounded chat plus read-only semantic knowledge query over Sol's local-first stack. Text chat turns can use ambient runtime awareness from current site metrics, sensor readouts, and local service telemetry when available. The schema includes a simple GET chat route for text-only prompts and a POST chat route for multimodal turns with optional image attachments, page context, and explicit profile selection."
  },
  "servers": [
    {
      "url": "https://sol.system42.one"
    }
  ],
  "paths": {
    "/api/chat/query": {
      "get": {
        "operationId": "queryChat",
        "summary": "Ask Sol a grounded question with ambient runtime awareness when available",
        "parameters": [
          {
            "name": "query",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Natural-language user message. When explicit page context is omitted, Sol may also use current site metrics, sensor readouts, and service telemetry as ambient runtime context."
          },
          {
            "name": "profile",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "reasoning",
                "vision",
                "vision_fast"
              ]
            },
            "description": "Preferred backend profile. Text-only Action use should usually leave this as the default reasoning lane."
          },
          {
            "name": "session",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Optional session identifier. If omitted and persist is not enabled, the request is processed statelessly."
          },
          {
            "name": "persist",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "enum": [
                0,
                1
              ],
              "default": 0
            },
            "description": "Set to 1 to persist the turn into session history."
          },
          {
            "name": "page_context",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "JSON-encoded page context object. Use this to send the current page title, headings, questions, and content in one field. If omitted, Sol may fall back to live runtime context when available."
          },
          {
            "name": "page_title",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "page_target",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "page_content_type",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "page_content",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Plain-text summary of the current page. This is useful when a caller cannot easily JSON-encode page_context."
          }
        ],
        "responses": {
          "200": {
            "description": "Grounded chat answer and retrieval metadata",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "message": {
                      "type": "string"
                    },
                    "session": {
                      "type": "string"
                    },
                    "persisted": {
                      "type": "boolean"
                    },
                    "grounded": {
                      "type": "boolean"
                    },
                    "retrieval": {
                      "type": "object",
                      "properties": {
                        "used": {
                          "type": "boolean"
                        },
                        "query": {
                          "type": "string"
                        },
                        "warning": {
                          "type": [
                            "string",
                            "null"
                          ]
                        },
                        "grounding_mode": {
                          "type": "string"
                        },
                        "hits": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "rank": {
                                "type": "integer"
                              },
                              "score": {
                                "type": "number"
                              },
                              "path": {
                                "type": "string"
                              },
                              "doc_key": {
                                "type": "string"
                              },
                              "chunk": {
                                "type": "integer"
                              },
                              "text": {
                                "type": "string"
                              }
                            },
                            "required": [
                              "rank",
                              "score",
                              "path",
                              "doc_key",
                              "chunk",
                              "text"
                            ]
                          }
                        },
                        "supplemental": {
                          "type": "object",
                          "description": "Optional additive retrieval bundle generated by the chat backend itself via a second knowledge-query call for the same turn.",
                          "properties": {
                            "query": {
                              "type": "string"
                            },
                            "used": {
                              "type": "boolean"
                            },
                            "warning": {
                              "type": [
                                "string",
                                "null"
                              ]
                            },
                            "grounding_mode": {
                              "type": "string"
                            },
                            "hits": {
                              "type": "array",
                              "items": {
                                "type": "object",
                                "properties": {
                                  "rank": {
                                    "type": "integer"
                                  },
                                  "score": {
                                    "type": "number"
                                  },
                                  "path": {
                                    "type": "string"
                                  },
                                  "doc_key": {
                                    "type": "string"
                                  },
                                  "chunk": {
                                    "type": "integer"
                                  },
                                  "text": {
                                    "type": "string"
                                  }
                                }
                              }
                            },
                            "source_documents": {
                              "type": "array",
                              "items": {
                                "type": "object"
                              }
                            }
                          }
                        },
                        "source_documents": {
                          "type": "array",
                          "description": "Optional current-file context for top retrieval hits. For HTML files, current_file_content is visible rendered text rather than raw markup.",
                          "items": {
                            "type": "object",
                            "properties": {
                              "path": {
                                "type": "string"
                              },
                              "resolved_path": {
                                "type": "string"
                              },
                              "retrieved_snippet": {
                                "type": "string"
                              },
                              "content_mode": {
                                "type": "string"
                              },
                              "snippet_found_in_current_file": {
                                "type": "boolean"
                              },
                              "current_file_representation": {
                                "type": "string"
                              },
                              "current_file_content": {
                                "type": "string"
                              }
                            }
                          }
                        },
                        "live_site_state": {
                          "type": "object",
                          "description": "Optional live site metrics and runtime context included as additional grounding for text turns.",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "used",
                        "query",
                        "hits"
                      ]
                    },
                    "page_context_applied": {
                      "type": "boolean"
                    },
                    "history_size": {
                      "type": "integer"
                    },
                    "fallback_grounding_used": {
                      "type": "boolean"
                    },
                    "backend_profile": {
                      "type": "string"
                    },
                    "backend_model_id": {
                      "type": "string"
                    },
                    "image_count": {
                      "type": "integer"
                    },
                    "query": {
                      "type": "string"
                    },
                    "cache_hit": {
                      "type": "boolean"
                    },
                    "cache_version": {
                      "type": "integer"
                    }
                  },
                  "required": [
                    "message",
                    "session",
                    "persisted",
                    "grounded",
                    "page_context_applied",
                    "history_size",
                    "fallback_grounding_used",
                    "backend_profile",
                    "backend_model_id",
                    "image_count",
                    "query",
                    "cache_hit"
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/api/chat": {
      "post": {
        "operationId": "chatTurn",
        "summary": "Send a chat turn, including optional images for vision and ambient runtime awareness for text turns",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "message": {
                    "type": "string",
                    "description": "Natural-language user message. For image-only turns, this may be omitted and Sol will default to describing the attached image. Text turns without explicit page context may use ambient runtime context from current site metrics, sensor readouts, and service telemetry."
                  },
                  "session": {
                    "type": "string",
                    "description": "Optional session identifier for continued conversation state."
                  },
                  "persist": {
                    "type": "boolean",
                    "default": false,
                    "description": "Set to true to persist the turn into session history."
                  },
                  "stream": {
                    "type": "boolean",
                    "default": false,
                    "description": "Set to true only if the caller expects an SSE stream. GPT Actions should usually leave this false."
                  },
                  "profile": {
                    "type": "string",
                    "enum": [
                      "reasoning",
                      "vision",
                      "vision_fast"
                    ],
                    "description": "Preferred backend profile. Use a vision profile when sending images."
                  },
                  "page_context": {
                    "type": "object",
                    "description": "Optional structured page context for grounding a reply in the current interface state. If omitted on text turns, Sol may use ambient runtime context when available.",
                    "properties": {
                      "target": {
                        "type": "string"
                      },
                      "title": {
                        "type": "string"
                      },
                      "content_type": {
                        "type": "string"
                      },
                      "headings": {
                        "type": "array",
                        "items": {
                          "type": "string"
                        }
                      },
                      "suggested_questions": {
                        "type": "array",
                        "items": {
                          "type": "string"
                        }
                      },
                      "content": {
                        "type": "string"
                      }
                    }
                  },
                  "images": {
                    "type": "array",
                    "description": "Optional attached images for multimodal turns. Each image must currently be supplied as a data URL.",
                    "items": {
                      "type": "object",
                      "properties": {
                        "name": {
                          "type": "string"
                        },
                        "mime_type": {
                          "type": "string",
                          "description": "Image MIME type such as image/jpeg or image/png."
                        },
                        "data_url": {
                          "type": "string",
                          "description": "A base64 data URL in the form data:image/<type>;base64,..."
                        }
                      },
                      "required": [
                        "data_url"
                      ]
                    }
                  }
                },
                "anyOf": [
                  {
                    "required": [
                      "message"
                    ]
                  },
                  {
                    "required": [
                      "images"
                    ]
                  }
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Chat answer and retrieval metadata for text or multimodal turns",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "message": {
                      "type": "string"
                    },
                    "session": {
                      "type": "string"
                    },
                    "persisted": {
                      "type": "boolean"
                    },
                    "grounded": {
                      "type": "boolean"
                    },
                    "retrieval": {
                      "type": "object",
                      "properties": {
                        "used": {
                          "type": "boolean"
                        },
                        "query": {
                          "type": "string"
                        },
                        "warning": {
                          "type": [
                            "string",
                            "null"
                          ]
                        },
                        "grounding_mode": {
                          "type": "string"
                        },
                        "hits": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "rank": {
                                "type": "integer"
                              },
                              "score": {
                                "type": "number"
                              },
                              "path": {
                                "type": "string"
                              },
                              "doc_key": {
                                "type": "string"
                              },
                              "chunk": {
                                "type": "integer"
                              },
                              "text": {
                                "type": "string"
                              }
                            },
                            "required": [
                              "rank",
                              "score",
                              "path",
                              "doc_key",
                              "chunk",
                              "text"
                            ]
                          }
                        },
                        "supplemental": {
                          "type": "object",
                          "description": "Optional additive retrieval bundle generated by the chat backend itself via a second knowledge-query call for the same turn.",
                          "properties": {
                            "query": {
                              "type": "string"
                            },
                            "used": {
                              "type": "boolean"
                            },
                            "warning": {
                              "type": [
                                "string",
                                "null"
                              ]
                            },
                            "grounding_mode": {
                              "type": "string"
                            },
                            "hits": {
                              "type": "array",
                              "items": {
                                "type": "object",
                                "properties": {
                                  "rank": {
                                    "type": "integer"
                                  },
                                  "score": {
                                    "type": "number"
                                  },
                                  "path": {
                                    "type": "string"
                                  },
                                  "doc_key": {
                                    "type": "string"
                                  },
                                  "chunk": {
                                    "type": "integer"
                                  },
                                  "text": {
                                    "type": "string"
                                  }
                                }
                              }
                            },
                            "source_documents": {
                              "type": "array",
                              "items": {
                                "type": "object"
                              }
                            }
                          }
                        },
                        "source_documents": {
                          "type": "array",
                          "description": "Optional current-file context for top retrieval hits. For HTML files, current_file_content is visible rendered text rather than raw markup.",
                          "items": {
                            "type": "object",
                            "properties": {
                              "path": {
                                "type": "string"
                              },
                              "resolved_path": {
                                "type": "string"
                              },
                              "retrieved_snippet": {
                                "type": "string"
                              },
                              "content_mode": {
                                "type": "string"
                              },
                              "snippet_found_in_current_file": {
                                "type": "boolean"
                              },
                              "current_file_representation": {
                                "type": "string"
                              },
                              "current_file_content": {
                                "type": "string"
                              }
                            }
                          }
                        },
                        "live_site_state": {
                          "type": "object",
                          "description": "Optional live site metrics and runtime context included as additional grounding for text turns.",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "used",
                        "query",
                        "hits"
                      ]
                    },
                    "page_context_applied": {
                      "type": "boolean"
                    },
                    "history_size": {
                      "type": "integer"
                    },
                    "fallback_grounding_used": {
                      "type": "boolean"
                    },
                    "backend_profile": {
                      "type": "string"
                    },
                    "backend_model_id": {
                      "type": "string"
                    },
                    "image_count": {
                      "type": "integer"
                    },
                    "query": {
                      "type": "string"
                    },
                    "cache_hit": {
                      "type": "boolean"
                    },
                    "cache_version": {
                      "type": "integer"
                    }
                  },
                  "required": [
                    "message",
                    "session",
                    "persisted",
                    "grounded",
                    "page_context_applied",
                    "history_size",
                    "fallback_grounding_used",
                    "backend_profile",
                    "backend_model_id",
                    "image_count",
                    "query",
                    "cache_hit"
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/api/chat/health": {
      "get": {
        "operationId": "chatHealth",
        "summary": "Check chat backend readiness and active local model state",
        "responses": {
          "200": {
            "description": "Chat runtime health and stack inventory",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean"
                    },
                    "strict_grounding": {
                      "type": "boolean"
                    },
                    "backend_configured": {
                      "type": "boolean"
                    },
                    "backend_base_url": {
                      "type": "string"
                    },
                    "backend_model_id": {
                      "type": "string"
                    },
                    "backend_profile": {
                      "type": "string"
                    },
                    "voice_available": {
                      "type": "boolean"
                    },
                    "tts_cache_enabled": {
                      "type": "boolean"
                    },
                    "stack": {
                      "type": "object"
                    },
                    "backends": {
                      "type": "array",
                      "items": {
                        "type": "object"
                      }
                    }
                  },
                  "required": [
                    "ok",
                    "strict_grounding",
                    "backend_configured",
                    "backend_base_url",
                    "backend_model_id",
                    "backend_profile",
                    "voice_available",
                    "tts_cache_enabled",
                    "stack",
                    "backends"
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/api/knowledge/query": {
      "get": {
        "operationId": "queryKnowledge",
        "summary": "Semantic search over the knowledge cache",
        "parameters": [
          {
            "name": "query",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Natural-language query text."
          },
          {
            "name": "top_k",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "default": 5,
              "minimum": 1,
              "maximum": 12
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Top matching knowledge chunks",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "query": {
                      "type": "string"
                    },
                    "top_k": {
                      "type": "integer"
                    },
                    "backend": {
                      "type": "string"
                    },
                    "cache_path": {
                      "type": "string"
                    },
                    "requested_backend": {
                      "type": "string"
                    },
                    "warning": {
                      "type": "string"
                    },
                    "results": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "rank": {
                            "type": "integer"
                          },
                          "score": {
                            "type": "number"
                          },
                          "path": {
                            "type": "string"
                          },
                          "chunk": {
                            "type": "integer"
                          },
                          "doc_key": {
                            "type": "string"
                          },
                          "text": {
                            "type": "string"
                          }
                        },
                        "required": [
                          "rank",
                          "score",
                          "path",
                          "chunk",
                          "doc_key",
                          "text"
                        ]
                      }
                    }
                  },
                  "required": [
                    "query",
                    "top_k",
                    "backend",
                    "cache_path",
                    "results"
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/api/knowledge/health": {
      "get": {
        "operationId": "knowledgeHealth",
        "summary": "Check whether the knowledge cache is loaded",
        "responses": {
          "200": {
            "description": "Current cache status, including query-embedding cache metadata when available",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean"
                    },
                    "backend": {
                      "type": "string"
                    },
                    "cache_path": {
                      "type": "string"
                    },
                    "knowledge_dir": {
                      "type": "string"
                    },
                    "docs": {
                      "type": "integer"
                    },
                    "query_cache_path": {
                      "type": "string"
                    },
                    "query_cache_entries": {
                      "type": "integer"
                    }
                  },
                  "required": [
                    "ok",
                    "backend",
                    "cache_path",
                    "knowledge_dir",
                    "docs",
                    "query_cache_path",
                    "query_cache_entries"
                  ]
                }
              }
            }
          }
        }
      }
    }
  }
}