{
  "openapi": "3.0.3",
  "info": {
    "title": "AI Flow - Complete API Reference",
    "description": "Complete API documentation for AI Flow, covering both Workflow Execution and Evaluation APIs.\n\n## APIs Overview\n\n### Workflow Execution API\nExecute AI workflows programmatically. Build complex AI pipelines with multiple steps and expose them as simple API endpoints compatible with OpenAI's format.\n\n### Evaluation API\nEvaluate AI/chat applications for quality using precision, recall, and groundedness metrics. Test any AI system against ground truth data without modifying your codebase.\n\n## Authentication\n\nAll API requests require an API key. Generate one in the AI Flow dashboard under **Settings → API Keys**.\n\n```\nAuthorization: Bearer YOUR_API_KEY\n```\n\nor\n\n```\nX-API-Key: YOUR_API_KEY\n```\n\n## Quick Links\n\n- [Workflow API Guide](/docs/workflow-api.md)\n- [Evaluation API Guide](/docs/external-evaluation-api.md)\n- [Dashboard](https://www.ai-flow.eu)",
    "version": "1.0.0",
    "contact": {
      "name": "AI Flow Support",
      "email": "support@ai-flow.eu",
      "url": "https://www.ai-flow.eu"
    },
    "license": {
      "name": "Proprietary",
      "url": "https://www.ai-flow.eu/terms"
    }
  },
  "servers": [
    {
      "url": "https://www.ai-flow.eu",
      "description": "Production server"
    },
    {
      "url": "http://localhost:3000",
      "description": "Local development server"
    }
  ],
  "tags": [
    {
      "name": "Workflow Execution",
      "description": "Execute AI workflows via API"
    },
    {
      "name": "Evaluation - Collections",
      "description": "Manage question collections for organizing test cases"
    },
    {
      "name": "Evaluation - Questions",
      "description": "Manage individual questions with ground truth answers"
    },
    {
      "name": "Evaluation - Services",
      "description": "Register and manage external services to evaluate"
    },
    {
      "name": "Evaluation - Run",
      "description": "Run evaluations and retrieve results"
    }
  ],
  "paths": {
    "/api/V1/chat/completions": {
      "post": {
        "tags": ["Workflow Execution"],
        "summary": "Execute a workflow (OpenAI-compatible)",
        "description": "Execute an AI Flow workflow using the OpenAI Chat Completions format. Your `model` parameter is the workflow ID, and the `messages` array is passed to your workflow as input.",
        "operationId": "createChatCompletion",
        "security": [{ "bearerAuth": [] }, { "apiKeyHeader": [] }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ChatCompletionRequest"
              },
              "example": {
                "model": "customer-support-agent",
                "messages": [
                  { "role": "user", "content": "How do I reset my password?" }
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successful completion",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ChatCompletionResponse"
                }
              }
            }
          },
          "400": { "description": "Bad request" },
          "401": { "description": "Unauthorized" },
          "403": { "description": "Forbidden" },
          "404": { "description": "Workflow not found" }
        }
      }
    },
    "/api/V1/eval/collections": {
      "get": {
        "tags": ["Evaluation - Collections"],
        "summary": "List all question collections",
        "operationId": "listCollections",
        "security": [{ "bearerAuth": [] }, { "apiKeyHeader": [] }],
        "responses": {
          "200": {
            "description": "List of collections",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "collections": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Collection"
                      }
                    }
                  }
                }
              }
            }
          },
          "401": { "description": "Unauthorized" },
          "403": { "description": "Forbidden" }
        }
      }
    },
    "/api/V1/eval/questions": {
      "post": {
        "tags": ["Evaluation - Questions"],
        "summary": "Add questions to a collection",
        "operationId": "addQuestions",
        "security": [{ "bearerAuth": [] }, { "apiKeyHeader": [] }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/AddQuestionsRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Questions added successfully",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "addedCount": { "type": "integer" },
                    "questionIds": {
                      "type": "array",
                      "items": { "type": "string" }
                    }
                  }
                }
              }
            }
          },
          "400": { "description": "Bad request" },
          "401": { "description": "Unauthorized" }
        }
      },
      "get": {
        "tags": ["Evaluation - Questions"],
        "summary": "Get questions from a collection",
        "operationId": "getQuestions",
        "security": [{ "bearerAuth": [] }, { "apiKeyHeader": [] }],
        "parameters": [
          {
            "name": "collectionId",
            "in": "query",
            "description": "Filter by collection ID",
            "schema": { "type": "string" }
          }
        ],
        "responses": {
          "200": {
            "description": "List of questions",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "questions": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Question"
                      }
                    }
                  }
                }
              }
            }
          },
          "401": { "description": "Unauthorized" }
        }
      }
    },
    "/api/V1/eval/questions/{questionId}": {
      "put": {
        "tags": ["Evaluation - Questions"],
        "summary": "Update a question",
        "operationId": "updateQuestion",
        "security": [{ "bearerAuth": [] }, { "apiKeyHeader": [] }],
        "parameters": [
          {
            "name": "questionId",
            "in": "path",
            "required": true,
            "schema": { "type": "string" }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/UpdateQuestionRequest"
              }
            }
          }
        },
        "responses": {
          "200": { "description": "Question updated" },
          "404": { "description": "Question not found" }
        }
      },
      "delete": {
        "tags": ["Evaluation - Questions"],
        "summary": "Delete a question",
        "operationId": "deleteQuestion",
        "security": [{ "bearerAuth": [] }, { "apiKeyHeader": [] }],
        "parameters": [
          {
            "name": "questionId",
            "in": "path",
            "required": true,
            "schema": { "type": "string" }
          }
        ],
        "responses": {
          "200": { "description": "Question deleted" },
          "404": { "description": "Question not found" }
        }
      }
    },
    "/api/V1/eval/services": {
      "post": {
        "tags": ["Evaluation - Services"],
        "summary": "Register an external service",
        "operationId": "createService",
        "security": [{ "bearerAuth": [] }, { "apiKeyHeader": [] }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateServiceRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Service registered",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "serviceId": { "type": "string" },
                    "name": { "type": "string" }
                  }
                }
              }
            }
          },
          "400": { "description": "Bad request" }
        }
      },
      "get": {
        "tags": ["Evaluation - Services"],
        "summary": "List registered services",
        "operationId": "listServices",
        "security": [{ "bearerAuth": [] }, { "apiKeyHeader": [] }],
        "responses": {
          "200": {
            "description": "List of services",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "services": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Service"
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/V1/eval/run": {
      "post": {
        "tags": ["Evaluation - Run"],
        "summary": "Start an evaluation run",
        "description": "Start an evaluation run against a question collection using either a registered service or ad-hoc service URL.",
        "operationId": "startEvaluationRun",
        "security": [{ "bearerAuth": [] }, { "apiKeyHeader": [] }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/StartEvaluationRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Evaluation started",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "status": { "type": "string" },
                    "runId": { "type": "string" }
                  }
                }
              }
            }
          },
          "400": { "description": "Bad request" },
          "404": { "description": "Collection or service not found" }
        }
      }
    },
    "/api/V1/eval/run/{runId}": {
      "get": {
        "tags": ["Evaluation - Run"],
        "summary": "Get evaluation run results",
        "operationId": "getEvaluationRun",
        "security": [{ "bearerAuth": [] }, { "apiKeyHeader": [] }],
        "parameters": [
          {
            "name": "runId",
            "in": "path",
            "required": true,
            "schema": { "type": "string" }
          }
        ],
        "responses": {
          "200": {
            "description": "Evaluation run results",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EvaluationRunResult"
                }
              }
            }
          },
          "404": { "description": "Run not found" }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "description": "API key as Bearer token"
      },
      "apiKeyHeader": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key",
        "description": "API key in custom header"
      }
    },
    "schemas": {
      "ChatCompletionRequest": {
        "type": "object",
        "required": ["model", "messages"],
        "properties": {
          "model": {
            "type": "string",
            "description": "The workflow ID to execute"
          },
          "messages": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ChatMessage"
            }
          }
        }
      },
      "ChatMessage": {
        "type": "object",
        "required": ["role", "content"],
        "properties": {
          "role": {
            "type": "string",
            "enum": ["system", "user", "assistant"]
          },
          "content": {
            "type": "string"
          }
        }
      },
      "ChatCompletionResponse": {
        "type": "object",
        "properties": {
          "id": { "type": "string" },
          "object": { "type": "string" },
          "created": { "type": "integer" },
          "model": { "type": "string" },
          "choices": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "index": { "type": "integer" },
                "message": { "$ref": "#/components/schemas/ChatMessage" },
                "finish_reason": { "type": "string" }
              }
            }
          }
        }
      },
      "Collection": {
        "type": "object",
        "properties": {
          "collectionId": { "type": "string" },
          "name": { "type": "string" },
          "questionCount": { "type": "integer" },
          "lastModified": { "type": "string", "format": "date-time" }
        }
      },
      "Question": {
        "type": "object",
        "properties": {
          "_id": { "type": "string" },
          "question": { "type": "string" },
          "groundTruth": { "type": "string" },
          "collectionId": { "type": "string" },
          "stepGroundTruths": { "type": "object" },
          "metadata": { "type": "object" }
        }
      },
      "AddQuestionsRequest": {
        "type": "object",
        "required": ["questions"],
        "properties": {
          "collectionId": { "type": "string" },
          "questions": {
            "type": "array",
            "items": {
              "type": "object",
              "required": ["question", "groundTruth"],
              "properties": {
                "question": { "type": "string" },
                "groundTruth": { "type": "string" },
                "stepGroundTruths": { "type": "object" },
                "metadata": { "type": "object" }
              }
            }
          }
        }
      },
      "UpdateQuestionRequest": {
        "type": "object",
        "properties": {
          "question": { "type": "string" },
          "groundTruth": { "type": "string" },
          "stepGroundTruths": { "type": "object" },
          "metadata": { "type": "object" }
        }
      },
      "Service": {
        "type": "object",
        "properties": {
          "_id": { "type": "string" },
          "name": { "type": "string" },
          "url": { "type": "string" },
          "authType": { "type": "string" }
        }
      },
      "CreateServiceRequest": {
        "type": "object",
        "required": ["name", "url"],
        "properties": {
          "name": { "type": "string" },
          "description": { "type": "string" },
          "url": { "type": "string" },
          "authType": {
            "type": "string",
            "enum": ["none", "bearer", "apiKey", "basic"]
          },
          "authToken": { "type": "string" },
          "requestTimeout": { "type": "integer" },
          "concurrency": { "type": "integer" }
        }
      },
      "StartEvaluationRequest": {
        "type": "object",
        "required": ["collectionId"],
        "properties": {
          "collectionId": { "type": "string" },
          "externalServiceId": { "type": "string" },
          "externalServiceUrl": { "type": "string" },
          "externalServiceAuth": {
            "type": "object",
            "properties": {
              "type": { "type": "string" },
              "token": { "type": "string" }
            }
          },
          "runOptions": {
            "type": "object",
            "properties": {
              "name": { "type": "string" },
              "evaluateIntermediateSteps": { "type": "boolean" }
            }
          }
        }
      },
      "EvaluationRunResult": {
        "type": "object",
        "properties": {
          "status": { "type": "string" },
          "runId": { "type": "string" },
          "name": { "type": "string" },
          "stats": {
            "type": "object",
            "properties": {
              "avgPrecision": { "type": "number" },
              "avgRecall": { "type": "number" },
              "avgGroundedness": { "type": "number" }
            }
          },
          "results": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "questionId": { "type": "string" },
                "finalOutput": { "type": "string" },
                "finalPrecision": { "type": "number" },
                "finalRecall": { "type": "number" }
              }
            }
          }
        }
      }
    }
  }
}