{
  "openapi": "3.1.0",
  "info": {
    "title": "GoRules Agent API",
    "description": "High-performance rule evaluation service. The Agent loads decision models from releases and executes them with minimal latency.",
    "contact": {
      "name": "GoRules",
      "email": "hi@gorules.io"
    },
    "version": "1.23.3"
  },
  "tags": [
    {
      "name": "Evaluation",
      "description": "Evaluate decision models"
    },
    {
      "name": "Projects",
      "description": "Project information"
    },
    {
      "name": "System",
      "description": "Health and version endpoints"
    }
  ],
  "security": [
    {
      "AccessToken": []
    }
  ],
  "paths": {
    "/api/health": {
      "get": {
        "tags": [
          "System"
        ],
        "operationId": "getHealth",
        "summary": "Health check",
        "description": "Returns the health status of the Agent service. Use this endpoint for load balancer health checks.",
        "security": [],
        "responses": {
          "200": {
            "description": "Service is healthy",
            "content": {
              "text/plain": {
                "schema": {
                  "type": "string",
                  "example": "OK"
                }
              }
            }
          }
        }
      }
    },
    "/api/version": {
      "get": {
        "tags": [
          "System"
        ],
        "operationId": "getVersion",
        "summary": "Get version",
        "description": "Returns the current version of the Agent service.",
        "security": [],
        "responses": {
          "200": {
            "description": "Agent version string",
            "content": {
              "text/plain": {
                "schema": {
                  "type": "string",
                  "example": "1.23.3"
                }
              }
            }
          }
        }
      }
    },
    "/api/projects/{project}": {
      "get": {
        "tags": [
          "Projects"
        ],
        "operationId": "getProjectInfo",
        "summary": "Get project info",
        "description": "Returns information about the loaded project including the current release version.",
        "parameters": [
          {
            "name": "project",
            "in": "path",
            "description": "Project slug or ID",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "my-project"
          }
        ],
        "responses": {
          "200": {
            "description": "Project information",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProjectInfo"
                }
              }
            }
          },
          "404": {
            "description": "Project not found"
          }
        }
      }
    },
    "/api/projects/{project}/evaluate/{key}": {
      "post": {
        "tags": [
          "Evaluation"
        ],
        "operationId": "evaluateDecision",
        "summary": "Evaluate decision",
        "description": "Evaluates a decision model with the provided context and returns the result. Optionally include trace information for debugging.",
        "parameters": [
          {
            "name": "project",
            "in": "path",
            "description": "Project slug or ID",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "my-project"
          },
          {
            "name": "key",
            "in": "path",
            "description": "Decision model key (path)",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "pricing/calculate-discount"
          }
        ],
        "requestBody": {
          "description": "Evaluation request with context data",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/EvaluateRequest"
              },
              "example": {
                "context": {
                  "customer": {
                    "tier": "gold",
                    "totalOrders": 50
                  },
                  "order": {
                    "amount": 150
                  }
                },
                "trace": false
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "Evaluation result",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EvaluateResponse"
                }
              }
            }
          },
          "400": {
            "description": "Invalid request or evaluation error"
          },
          "401": {
            "description": "Unauthorized - invalid or missing access token"
          },
          "404": {
            "description": "Project or decision model not found"
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "AccessToken": {
        "type": "apiKey",
        "in": "header",
        "name": "X-Access-Token",
        "description": "Evaluation token from project settings"
      }
    },
    "schemas": {
      "EvaluateRequest": {
        "type": "object",
        "description": "Request body for decision evaluation",
        "required": [
          "context"
        ],
        "properties": {
          "context": {
            "type": "object",
            "description": "Input data for the decision model. The structure depends on your decision model's expected input.",
            "additionalProperties": true
          },
          "trace": {
            "type": "boolean",
            "nullable": true,
            "description": "When true, includes detailed trace information in the response for debugging purposes.",
            "default": false
          }
        }
      },
      "EvaluateResponse": {
        "type": "object",
        "description": "Response from decision evaluation",
        "properties": {
          "result": {
            "type": "object",
            "description": "The output from the decision model evaluation",
            "additionalProperties": true
          },
          "trace": {
            "type": "object",
            "description": "Detailed trace information (only included when trace=true in request)",
            "nullable": true
          },
          "details": {
            "$ref": "#/components/schemas/EvaluateDetailsResponse"
          }
        }
      },
      "EvaluateDetailsResponse": {
        "type": "object",
        "description": "Metadata about the evaluation",
        "properties": {
          "releaseId": {
            "type": "string",
            "nullable": true,
            "description": "ID of the release used for evaluation"
          },
          "versionId": {
            "type": "string",
            "nullable": true,
            "description": "Version ID of the decision model"
          }
        }
      },
      "ProjectInfo": {
        "type": "object",
        "description": "Information about a loaded project",
        "required": [
          "project_id",
          "project_key",
          "release_id",
          "release_version"
        ],
        "properties": {
          "project_id": {
            "type": "string",
            "description": "Unique identifier of the project"
          },
          "project_key": {
            "type": "string",
            "description": "Human-readable project key/slug"
          },
          "release_id": {
            "type": "string",
            "description": "ID of the currently loaded release"
          },
          "release_version": {
            "type": "string",
            "description": "Semantic version of the loaded release"
          }
        }
      }
    }
  }
}