{
  "openapi": "3.0.3",
  "info": {
    "title": "AI Flow - Workflow Execution API",
    "description": "Execute AI workflows programmatically via REST API. AI Flow allows you to build complex AI workflows with multiple steps (LLM prompts, retrieval, API calls, etc.) and expose them as simple API endpoints.\n\n## Key Features\n\n- **OpenAI-Compatible**: Use the same format as OpenAI's Chat Completions API\n- **Workflow as a Model**: Your workflow ID becomes the `model` parameter\n- **Flexible Input**: Pass messages, documents, and structured data to your workflows\n- **Tracing Support**: Get detailed execution traces for debugging and evaluation\n\n## Authentication\n\nAll API requests require an API key. You can generate an API key in the AI Flow dashboard under **Settings → API Keys**.\n\nInclude your API key in the request headers:\n```\nAuthorization: Bearer YOUR_API_KEY\n```\nor\n```\nX-API-Key: YOUR_API_KEY\n```\n\n## Prerequisites\n\nBefore calling a workflow via API:\n1. Create a workflow in AI Flow\n2. Add an **API Endpoint** trigger to the workflow\n3. Activate the trigger\n4. Copy the workflow ID from the trigger configuration",
    "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": "Chat Completions",
      "description": "OpenAI-compatible endpoint for workflow execution"
    },
    {
      "name": "Models",
      "description": "Discover available workflows/models"
    },
    {
      "name": "Versions",
      "description": "Manage and execute specific workflow versions (Plus tier and above)"
    },
    {
      "name": "Legacy",
      "description": "Legacy endpoint (deprecated, use Chat Completions instead)"
    }
  ],
  "paths": {
    "/api/V1/models": {
      "get": {
        "tags": ["Models"],
        "summary": "List available models (workflows)",
        "description": "Returns a list of workflows available to the authenticated user. This includes:\n\n- **Your own workflows** with active API triggers\n- **Organization workflows** shared with you\n\nThis endpoint follows the OpenAI `/models` format, making AI Flow compatible with tools like Cursor, Continue, Open WebUI, and other OpenAI-compatible clients.\n\n### Integration with IDEs\n\nWhen configuring AI Flow in an OpenAI-compatible tool:\n1. Set the base URL to `https://www.ai-flow.eu/api/V1`\n2. Enter your API key\n3. The tool will automatically discover your available workflows via this endpoint",
        "operationId": "listModels",
        "security": [{ "bearerAuth": [] }, { "apiKeyHeader": [] }],
        "responses": {
          "200": {
            "description": "List of available models",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "object": {
                      "type": "string",
                      "example": "list"
                    },
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "string",
                            "description": "The workflow ID (use this as the `model` parameter)",
                            "example": "customer-support-agent"
                          },
                          "object": {
                            "type": "string",
                            "example": "model"
                          },
                          "created": {
                            "type": "integer",
                            "description": "Unix timestamp of when the workflow was created",
                            "example": 1699900000
                          },
                          "owned_by": {
                            "type": "string",
                            "description": "Owner: 'user' for your workflows, organization name for shared workflows",
                            "example": "user"
                          },
                          "aiflow_metadata": {
                            "type": "object",
                            "description": "Additional AI Flow metadata (non-standard)",
                            "properties": {
                              "name": {
                                "type": "string",
                                "description": "Human-readable workflow name",
                                "example": "Customer Support Agent"
                              },
                              "description": {
                                "type": "string",
                                "nullable": true,
                                "description": "Workflow description"
                              },
                              "color": {
                                "type": "string",
                                "nullable": true,
                                "description": "Workflow color for UI display"
                              }
                            }
                          }
                        }
                      }
                    }
                  }
                },
                "example": {
                  "object": "list",
                  "data": [
                    {
                      "id": "customer-support-agent",
                      "object": "model",
                      "created": 1699900000,
                      "owned_by": "user",
                      "aiflow_metadata": {
                        "name": "Customer Support Agent",
                        "description": "Handles customer inquiries",
                        "color": "#4CAF50"
                      }
                    },
                    {
                      "id": "document-analyzer",
                      "object": "model",
                      "created": 1699800000,
                      "owned_by": "acme-corp",
                      "aiflow_metadata": {
                        "name": "Document Analyzer",
                        "description": null,
                        "color": "#2196F3"
                      }
                    }
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Invalid API key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/V1/models/{modelId}/versions": {
      "get": {
        "tags": ["Versions"],
        "summary": "List versions of a workflow",
        "description": "Returns all saved versions of a specific workflow. Versions allow you to save snapshots of your workflow configuration and execute specific versions via the API.\n\n**Requires Plus tier or higher.**",
        "operationId": "listVersions",
        "security": [{ "bearerAuth": [] }, { "apiKeyHeader": [] }],
        "parameters": [
          {
            "name": "modelId",
            "in": "path",
            "required": true,
            "description": "The workflow ID",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "List of workflow versions",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "object": {
                      "type": "string",
                      "example": "list"
                    },
                    "model": {
                      "type": "string",
                      "description": "The workflow ID"
                    },
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Version"
                      }
                    }
                  }
                },
                "example": {
                  "object": "list",
                  "model": "customer-support-agent",
                  "data": [
                    {
                      "id": "abc123",
                      "name": "v1.0 - Production",
                      "created": 1699900000,
                      "created_by": "user123"
                    },
                    {
                      "id": "def456",
                      "name": "v0.9 - Beta",
                      "created": 1699800000,
                      "created_by": "user123"
                    }
                  ]
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "description": "Forbidden - workflow versioning requires Plus tier or higher",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "error": {
                    "message": "Your plan does not include workflow versioning. Please upgrade to Plus or higher.",
                    "type": "permission_error"
                  }
                }
              }
            }
          },
          "404": {
            "description": "Workflow not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/V1/chat/completions": {
      "post": {
        "tags": ["Chat Completions"],
        "summary": "Execute a workflow (OpenAI-compatible)",
        "description": "Execute an AI Flow workflow using the OpenAI Chat Completions format. This is the **recommended** endpoint for all new integrations.\n\n### How It Works\n\n1. Your `model` parameter is the workflow ID\n2. The `messages` array is passed to your workflow as input\n3. Your workflow processes the messages and returns a response\n4. The response is formatted as an OpenAI Chat Completion\n\n### Compatibility\n\nThis endpoint is compatible with:\n- OpenAI SDK (Python, Node.js, etc.)\n- LangChain\n- Any tool that supports OpenAI's API format\n\n### Example with OpenAI Python SDK\n\n```python\nfrom openai import OpenAI\n\nclient = OpenAI(\n    api_key=\"your-aiflow-api-key\",\n    base_url=\"https://www.ai-flow.eu/api/V1\"\n)\n\nresponse = client.chat.completions.create(\n    model=\"your-workflow-id\",\n    messages=[\n        {\"role\": \"user\", \"content\": \"Hello, how can you help me?\"}\n    ]\n)\n\nprint(response.choices[0].message.content)\n```",
        "operationId": "createChatCompletion",
        "security": [{ "bearerAuth": [] }, { "apiKeyHeader": [] }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ChatCompletionRequest"
              },
              "examples": {
                "simple": {
                  "summary": "Simple message",
                  "value": {
                    "model": "customer-support-agent",
                    "messages": [
                      {
                        "role": "user",
                        "content": "How do I reset my password?"
                      }
                    ]
                  }
                },
                "conversation": {
                  "summary": "Multi-turn conversation",
                  "value": {
                    "model": "customer-support-agent",
                    "messages": [
                      {
                        "role": "system",
                        "content": "You are a helpful customer support agent."
                      },
                      {
                        "role": "user",
                        "content": "I can't log in to my account"
                      },
                      {
                        "role": "assistant",
                        "content": "I'm sorry to hear that. Can you tell me what error message you're seeing?"
                      },
                      {
                        "role": "user",
                        "content": "It says 'Invalid credentials'"
                      }
                    ]
                  }
                },
                "withContext": {
                  "summary": "Message with additional context",
                  "value": {
                    "model": "document-qa-workflow",
                    "messages": [
                      {
                        "role": "system",
                        "content": "Answer questions based on the provided documents."
                      },
                      {
                        "role": "user",
                        "content": "What is the refund policy?",
                        "context": { "documentIds": ["doc-123", "doc-456"] }
                      }
                    ]
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successful completion",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ChatCompletionResponse"
                },
                "examples": {
                  "success": {
                    "summary": "Successful response",
                    "value": {
                      "id": "chatcmpl-abc123xyz",
                      "object": "chat.completion",
                      "created": 1701234567,
                      "model": "customer-support-agent",
                      "choices": [
                        {
                          "index": 0,
                          "message": {
                            "role": "assistant",
                            "content": "To reset your password, go to the login page and click 'Forgot Password'. Enter your email address and you'll receive a reset link within a few minutes."
                          },
                          "finish_reason": "stop"
                        }
                      ],
                      "usage": {
                        "prompt_tokens": 0,
                        "completion_tokens": 0,
                        "total_tokens": 0
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Bad request - missing or invalid parameters",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "examples": {
                  "missingModel": {
                    "summary": "Missing model parameter",
                    "value": {
                      "error": {
                        "message": "'model' is required (use your workflow ID)",
                        "type": "invalid_request_error",
                        "param": null,
                        "code": null
                      }
                    }
                  },
                  "missingMessages": {
                    "summary": "Missing messages parameter",
                    "value": {
                      "error": {
                        "message": "'messages' array is required",
                        "type": "invalid_request_error",
                        "param": null,
                        "code": null
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized - invalid or missing API key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "error": {
                    "message": "Invalid API key",
                    "type": "authentication_error",
                    "param": null,
                    "code": null
                  }
                }
              }
            }
          },
          "403": {
            "description": "Forbidden - no access to this workflow or API not enabled",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "examples": {
                  "noAccess": {
                    "summary": "No access to workflow",
                    "value": {
                      "error": {
                        "message": "You do not have access to this model",
                        "type": "permission_error",
                        "param": null,
                        "code": null
                      }
                    }
                  },
                  "apiNotEnabled": {
                    "summary": "API trigger not enabled",
                    "value": {
                      "error": {
                        "message": "API access is not enabled for this model",
                        "type": "permission_error",
                        "param": null,
                        "code": null
                      }
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "Workflow not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "error": {
                    "message": "Model 'unknown-workflow' not found",
                    "type": "invalid_request_error",
                    "param": null,
                    "code": null
                  }
                }
              }
            }
          },
          "422": {
            "description": "Workflow returned invalid output format",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "error": {
                    "message": "Workflow returned structured data instead of a text response. Please ensure the workflow ends with an AI Agent or Prompt step.",
                    "type": "invalid_response_error",
                    "param": null,
                    "code": null
                  }
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "error": {
                    "message": "Failed to load model configuration",
                    "type": "server_error",
                    "param": null,
                    "code": null
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/V1/chatbot": {
      "post": {
        "tags": ["Legacy"],
        "summary": "Execute a workflow (Legacy format)",
        "description": "**⚠️ Deprecated**: This endpoint is maintained for backward compatibility. New integrations should use `/api/V1/chat/completions` instead.\n\nExecutes an AI Flow workflow with custom input parameters. This endpoint supports both the legacy format and OpenAI format for easier migration.",
        "operationId": "executeChatbot",
        "deprecated": true,
        "security": [{ "bearerAuth": [] }, { "apiKeyHeader": [] }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "oneOf": [
                  { "$ref": "#/components/schemas/LegacyChatbotRequest" },
                  { "$ref": "#/components/schemas/ChatCompletionRequest" }
                ]
              },
              "examples": {
                "legacy": {
                  "summary": "Legacy format",
                  "value": {
                    "workflowId": "customer-support-agent",
                    "userInput": {
                      "messages": [
                        {
                          "role": "user",
                          "content": "How do I reset my password?"
                        }
                      ]
                    },
                    "asyncProcessing": false
                  }
                },
                "openai": {
                  "summary": "OpenAI format (also supported)",
                  "value": {
                    "model": "customer-support-agent",
                    "messages": [
                      {
                        "role": "user",
                        "content": "How do I reset my password?"
                      }
                    ]
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successful execution",
            "content": {
              "application/json": {
                "schema": {
                  "oneOf": [
                    { "$ref": "#/components/schemas/ChatCompletionResponse" },
                    { "$ref": "#/components/schemas/LegacyChatbotResponse" }
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Bad request",
            "content": {
              "text/plain": {
                "example": "Bad request: workflowId and userInput are required (or use 'model' and 'messages' for OpenAI format)."
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "text/plain": {
                "example": "Unauthorized"
              }
            }
          },
          "403": {
            "description": "Forbidden",
            "content": {
              "text/plain": {
                "example": "API access for this workflow is not enabled or trigger not found."
              }
            }
          },
          "404": {
            "description": "Workflow not found",
            "content": {
              "text/plain": {
                "example": "A workflow with the provided ID does not exist."
              }
            }
          },
          "405": {
            "description": "Method not allowed",
            "content": {
              "text/plain": {
                "example": "Method not allowed"
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "text/plain": {
                "example": "Failed to load workflow configuration."
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "description": "API key as Bearer token: `Authorization: Bearer YOUR_API_KEY`"
      },
      "apiKeyHeader": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key",
        "description": "API key in custom header: `X-API-Key: YOUR_API_KEY`"
      }
    },
    "schemas": {
      "ChatCompletionRequest": {
        "type": "object",
        "required": ["model", "messages"],
        "properties": {
          "model": {
            "type": "string",
            "description": "The workflow ID to execute. This is the unique identifier of your AI Flow workflow.",
            "example": "customer-support-agent"
          },
          "messages": {
            "type": "array",
            "description": "An array of messages representing the conversation. The workflow will receive these messages as input.",
            "items": {
              "$ref": "#/components/schemas/ChatMessage"
            },
            "minItems": 1
          },
          "stream": {
            "type": "boolean",
            "description": "Whether to stream the response. **Note: Streaming is not yet supported.**",
            "default": false
          },
          "version": {
            "type": "string",
            "description": "**AI Flow extension.** The version ID to execute. If omitted, the current/latest version of the workflow is used. Use the `/api/V1/models/{modelId}/versions` endpoint to list available versions. **Requires Plus tier or higher.**",
            "example": "abc123"
          }
        }
      },
      "Version": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "Unique version identifier (use this as the `version` parameter)"
          },
          "name": {
            "type": "string",
            "description": "Human-readable version name"
          },
          "created": {
            "type": "integer",
            "description": "Unix timestamp of when the version was created"
          },
          "created_by": {
            "type": "string",
            "nullable": true,
            "description": "User ID of who created this version"
          }
        }
      },
      "ChatMessage": {
        "type": "object",
        "required": ["role", "content"],
        "properties": {
          "role": {
            "type": "string",
            "enum": ["system", "user", "assistant"],
            "description": "The role of the message author."
          },
          "content": {
            "type": "string",
            "description": "The content of the message."
          }
        }
      },
      "ChatCompletionResponse": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "Unique identifier for this completion",
            "example": "chatcmpl-abc123xyz"
          },
          "object": {
            "type": "string",
            "enum": ["chat.completion"],
            "description": "Object type, always 'chat.completion'"
          },
          "created": {
            "type": "integer",
            "description": "Unix timestamp of when the completion was created",
            "example": 1701234567
          },
          "model": {
            "type": "string",
            "description": "The workflow ID that was used",
            "example": "customer-support-agent"
          },
          "choices": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ChatCompletionChoice"
            }
          },
          "usage": {
            "$ref": "#/components/schemas/UsageInfo"
          },
          "aiflow_tracing": {
            "$ref": "#/components/schemas/TracingData",
            "description": "Execution tracing data (only included when `X-AIFlow-Eval-Run: true` header is set)"
          }
        }
      },
      "ChatCompletionChoice": {
        "type": "object",
        "properties": {
          "index": {
            "type": "integer",
            "description": "Index of this choice",
            "example": 0
          },
          "message": {
            "$ref": "#/components/schemas/ChatMessage"
          },
          "finish_reason": {
            "type": "string",
            "enum": ["stop", "length", "tool_calls"],
            "description": "The reason the generation stopped",
            "example": "stop"
          }
        }
      },
      "UsageInfo": {
        "type": "object",
        "description": "Token usage information (currently returns 0 as token counting is not implemented)",
        "properties": {
          "prompt_tokens": {
            "type": "integer",
            "example": 0
          },
          "completion_tokens": {
            "type": "integer",
            "example": 0
          },
          "total_tokens": {
            "type": "integer",
            "example": 0
          }
        }
      },
      "TracingData": {
        "type": "object",
        "description": "Detailed execution trace for debugging and evaluation purposes",
        "properties": {
          "final": {
            "description": "The final output of the workflow (may be string or object)"
          },
          "intermediate": {
            "type": "object",
            "description": "Outputs from intermediate workflow steps",
            "additionalProperties": {
              "type": "object",
              "properties": {
                "stepName": {
                  "type": "string"
                },
                "output": {}
              }
            }
          },
          "fullContext": {
            "type": "string",
            "description": "Full context provided to the LLM (for groundedness evaluation)"
          }
        }
      },
      "LegacyChatbotRequest": {
        "type": "object",
        "required": ["workflowId", "userInput"],
        "properties": {
          "workflowId": {
            "type": "string",
            "description": "The ID of the workflow to execute",
            "example": "customer-support-agent"
          },
          "userInput": {
            "type": "object",
            "description": "Input data for the workflow. Structure depends on workflow configuration.",
            "example": {
              "messages": [{ "role": "user", "content": "Hello" }]
            }
          },
          "asyncProcessing": {
            "type": "boolean",
            "description": "**Not currently supported.** Whether to process asynchronously.",
            "default": false
          }
        }
      },
      "LegacyChatbotResponse": {
        "type": "object",
        "description": "Legacy response format (when not using OpenAI format)",
        "properties": {
          "final": {
            "description": "The final output of the workflow"
          },
          "intermediate": {
            "type": "object",
            "description": "Intermediate step outputs"
          },
          "executionId": {
            "type": "string",
            "description": "Unique execution identifier"
          }
        }
      },
      "ErrorResponse": {
        "type": "object",
        "properties": {
          "error": {
            "type": "object",
            "properties": {
              "message": {
                "type": "string",
                "description": "Human-readable error message"
              },
              "type": {
                "type": "string",
                "enum": [
                  "invalid_request_error",
                  "authentication_error",
                  "permission_error",
                  "server_error",
                  "invalid_response_error"
                ],
                "description": "Error type"
              },
              "param": {
                "type": "string",
                "nullable": true,
                "description": "The parameter that caused the error"
              },
              "code": {
                "type": "string",
                "nullable": true,
                "description": "Error code"
              }
            }
          }
        }
      }
    }
  }
}