{
  "openapi": "3.1.0",
  "info": {
    "title": "LLM Stateless API and Agent Platform",
    "version": "2.0.0",
    "description": "Stateless LLM API plus the surrounding agent endpoints. The LLM API only accepts a prompt, a model, options, and an API key."
  },
  "servers": [
    {
      "url": "https://llm.potthast.ruhr"
    }
  ],
  "paths": {
    "/api.php": {
      "post": {
        "summary": "Stateless LLM execution endpoint",
        "description": "Validates the API key, forwards the current prompt to Ollama, and returns the model response without session history.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/LLMRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successful response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/LLMSuccessResponse"
                }
              }
            }
          },
          "400": {
            "description": "Bad request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "401": {
            "description": "Invalid API key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "405": {
            "description": "Method not allowed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/agent/job/start": {
      "post": {
        "summary": "Start async agent job",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/AgentJobStartRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Job accepted",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/JobStartResponse"
                }
              }
            }
          }
        }
      }
    },
    "/agent/job/{id}": {
      "get": {
        "summary": "Get async job status",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Job status",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/JobStatusResponse"
                }
              }
            }
          }
        }
      }
    },
    "/agent/chat": {
      "post": {
        "summary": "Agent chat entry point",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/AgentChatRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Chat response or job ack",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/JobStartResponse"
                }
              }
            }
          }
        }
      }
    },
    "/agent/conversation/{id}": {
      "get": {
        "summary": "Get conversation history",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Conversation payload",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ConversationResponse"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "ErrorResponse": {
        "type": "object",
        "properties": {
          "ok": {
            "const": false
          },
          "error": {
            "type": "string"
          },
          "message": {
            "type": "string"
          },
          "details": {
            "type": "object"
          }
        },
        "required": [
          "ok",
          "error",
          "message",
          "details"
        ]
      },
      "LLMRequest": {
        "type": "object",
        "properties": {
          "api_key": {
            "type": "string"
          },
          "model": {
            "type": "string"
          },
          "prompt": {
            "type": "string"
          },
          "options": {
            "type": "object"
          }
        },
        "required": [
          "api_key",
          "model",
          "prompt"
        ]
      },
      "LLMSuccessResponse": {
        "type": "object",
        "properties": {
          "ok": {
            "const": true
          },
          "model": {
            "type": "string"
          },
          "response": {
            "type": "string"
          },
          "elapsed": {
            "type": "number"
          }
        },
        "required": [
          "ok",
          "model",
          "response",
          "elapsed"
        ]
      },
      "AgentJobStartRequest": {
        "type": "object",
        "properties": {
          "source": {
            "type": "string"
          },
          "scope_type": {
            "type": "string"
          },
          "scope_id": {
            "oneOf": [
              {
                "type": "string"
              },
              {
                "type": "integer"
              }
            ]
          },
          "task": {
            "type": "string"
          }
        },
        "required": [
          "source",
          "scope_type",
          "scope_id",
          "task"
        ]
      },
      "AgentChatRequest": {
        "type": "object",
        "properties": {
          "source": {
            "type": "string"
          },
          "scope_type": {
            "type": "string"
          },
          "scope_id": {
            "oneOf": [
              {
                "type": "string"
              },
              {
                "type": "integer"
              }
            ]
          },
          "prompt": {
            "type": "string"
          },
          "profile": {
            "type": "string"
          }
        },
        "required": [
          "source",
          "scope_type",
          "scope_id",
          "prompt"
        ]
      },
      "JobStartResponse": {
        "type": "object",
        "properties": {
          "ok": {
            "const": true
          },
          "data": {
            "type": "object",
            "properties": {
              "job_id": {
                "type": "string"
              },
              "status": {
                "type": "string",
                "enum": [
                  "running",
                  "queued"
                ]
              }
            },
            "required": [
              "job_id",
              "status"
            ]
          }
        },
        "required": [
          "ok",
          "data"
        ]
      },
      "JobStatusResponse": {
        "type": "object",
        "properties": {
          "ok": {
            "const": true
          },
          "data": {
            "type": "object",
            "properties": {
              "job_id": {
                "type": "string"
              },
              "status": {
                "type": "string"
              },
              "final_result": {
                "type": "object"
              },
              "error": {
                "type": "string"
              },
              "steps": {
                "type": "array"
              }
            },
            "required": [
              "job_id",
              "status"
            ]
          }
        },
        "required": [
          "ok",
          "data"
        ]
      },
      "ConversationResponse": {
        "type": "object",
        "properties": {
          "ok": {
            "const": true
          },
          "data": {
            "type": "object",
            "properties": {
              "conversation_id": {
                "type": "string"
              },
              "messages": {
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "role": {
                      "type": "string"
                    },
                    "content": {
                      "type": "string"
                    }
                  }
                }
              }
            },
            "required": [
              "conversation_id",
              "messages"
            ]
          }
        },
        "required": [
          "ok",
          "data"
        ]
      }
    }
  }
}