{
  "openapi": "3.1.0",
  "info": {
    "title": "Finikos API",
    "description": "Superficie machine-readable pubblica di Finikos: JSON-LD, NL search, MCP discovery e whitelist.",
    "version": "1.0.0",
    "contact": {
      "name": "Finikos",
      "url": "https://finikos.it",
      "email": "info@finikos.it"
    }
  },
  "servers": [
    {
      "url": "https://finikos.it",
      "description": "Production"
    }
  ],
  "tags": [
    {
      "name": "Structured Data",
      "description": "JSON-LD pubblici coerenti con il contenuto del sito."
    },
    {
      "name": "Discovery",
      "description": "Endpoint di discovery per agenti e integrazioni."
    },
    {
      "name": "Conversion",
      "description": "Endpoint di acquisizione lead e accesso anticipato."
    }
  ],
  "paths": {
    "/.well-known/mcp.json": {
      "get": {
        "tags": [
          "Discovery"
        ],
        "operationId": "getMcpDiscovery",
        "summary": "Get MCP discovery descriptor",
        "description": "Restituisce il descriptor HTTP del server MCP pubblico di Finikos.",
        "responses": {
          "200": {
            "description": "MCP discovery document",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/McpDescriptor"
                }
              }
            }
          }
        }
      }
    },
    "/llms.txt": {
      "get": {
        "tags": [
          "Discovery"
        ],
        "operationId": "getLlmsTxt",
        "summary": "Get LLMs.txt",
        "description": "Restituisce il riepilogo markdown generato dai contenuti correnti del sito.",
        "responses": {
          "200": {
            "description": "Generated markdown summary",
            "content": {
              "text/plain": {
                "schema": {
                  "type": "string"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/products.json": {
      "get": {
        "tags": [
          "Structured Data"
        ],
        "operationId": "getProducts",
        "summary": "List all products",
        "description": "Returns a Schema.org ItemList of all Finikos products with metadata.",
        "responses": {
          "200": {
            "description": "JSON-LD ItemList of products",
            "content": {
              "application/ld+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProductList"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/products/{slug}.json": {
      "get": {
        "tags": [
          "Structured Data"
        ],
        "operationId": "getProduct",
        "summary": "Get product details",
        "description": "Returns full Schema.org WebApplication data for a specific product.",
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "enum": [
                "brevita",
                "firm",
                "space-context"
              ]
            },
            "description": "Product identifier"
          }
        ],
        "responses": {
          "200": {
            "description": "JSON-LD WebApplication",
            "content": {
              "application/ld+json": {
                "schema": {
                  "$ref": "#/components/schemas/Product"
                }
              }
            }
          },
          "404": {
            "description": "Product not found"
          }
        }
      }
    },
    "/api/v1/faq.json": {
      "get": {
        "tags": [
          "Structured Data"
        ],
        "operationId": "getFAQ",
        "summary": "Get all FAQs",
        "description": "Returns Schema.org FAQPage with all frequently asked questions.",
        "responses": {
          "200": {
            "description": "JSON-LD FAQPage",
            "content": {
              "application/ld+json": {
                "schema": {
                  "$ref": "#/components/schemas/FAQPage"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/company.json": {
      "get": {
        "tags": [
          "Structured Data"
        ],
        "operationId": "getCompany",
        "summary": "Get company information",
        "description": "Returns Schema.org Organization data for Finikos.",
        "responses": {
          "200": {
            "description": "JSON-LD Organization",
            "content": {
              "application/ld+json": {
                "schema": {
                  "$ref": "#/components/schemas/Organization"
                }
              }
            }
          }
        }
      }
    },
    "/api/nlweb/ask": {
      "get": {
        "tags": [
          "Discovery"
        ],
        "operationId": "askNaturalLanguage",
        "summary": "Natural language query",
        "description": "Ask questions about Finikos products in natural language. Returns Schema.org-structured answers.",
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "maxLength": 500
            },
            "description": "Natural language question"
          }
        ],
        "responses": {
          "200": {
            "description": "Structured answer in JSON-LD",
            "content": {
              "application/ld+json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        }
      }
    },
    "/api/mcp/": {
      "post": {
        "tags": [
          "Discovery"
        ],
        "operationId": "mcpToolCall",
        "summary": "MCP JSON-RPC endpoint",
        "description": "Model Context Protocol server for AI tool integration. Supports JSON-RPC 2.0.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "jsonrpc": {
                    "type": "string",
                    "const": "2.0"
                  },
                  "id": {
                    "type": [
                      "string",
                      "number"
                    ]
                  },
                  "method": {
                    "type": "string"
                  },
                  "params": {
                    "type": "object"
                  }
                },
                "required": [
                  "jsonrpc",
                  "id",
                  "method"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "JSON-RPC response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "jsonrpc": {
                      "type": "string"
                    },
                    "id": {
                      "type": [
                        "string",
                        "number"
                      ]
                    },
                    "result": {
                      "type": "object"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/whitelist": {
      "post": {
        "tags": [
          "Conversion"
        ],
        "operationId": "joinWhitelist",
        "summary": "Join the early access whitelist",
        "description": "Submit an email to join the Finikos early access whitelist.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "email": {
                    "type": "string",
                    "format": "email"
                  },
                  "honeypot": {
                    "type": "string"
                  },
                  "turnstileToken": {
                    "type": "string"
                  }
                },
                "required": [
                  "email"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Whitelist registration result",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean"
                    },
                    "message": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "McpDescriptor": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string"
          },
          "description": {
            "type": "string"
          },
          "version": {
            "type": "string"
          },
          "protocol_version": {
            "type": "string"
          },
          "endpoint": {
            "type": "string",
            "format": "uri"
          },
          "transport": {
            "type": "string"
          },
          "capabilities": {
            "type": "object"
          }
        }
      },
      "ProductList": {
        "type": "object",
        "properties": {
          "@context": {
            "type": "string"
          },
          "@type": {
            "type": "string",
            "const": "ItemList"
          },
          "name": {
            "type": "string"
          },
          "description": {
            "type": "string"
          },
          "numberOfItems": {
            "type": "integer"
          },
          "itemListElement": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "@type": {
                  "type": "string",
                  "const": "ListItem"
                },
                "position": {
                  "type": "integer"
                },
                "item": {
                  "$ref": "#/components/schemas/Product"
                }
              }
            }
          }
        }
      },
      "Product": {
        "type": "object",
        "properties": {
          "@context": {
            "type": "string"
          },
          "@type": {
            "type": "string",
            "const": "WebApplication"
          },
          "@id": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "description": {
            "type": "string"
          },
          "abstract": {
            "type": "string"
          },
          "url": {
            "type": "string",
            "format": "uri"
          },
          "applicationCategory": {
            "type": "string"
          },
          "applicationSubCategory": {
            "type": "string"
          },
          "screenshot": {
            "type": "string",
            "format": "uri"
          },
          "featureList": {
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        }
      },
      "FAQPage": {
        "type": "object",
        "properties": {
          "@context": {
            "type": "string"
          },
          "@type": {
            "type": "string",
            "const": "FAQPage"
          },
          "mainEntity": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "@type": {
                  "type": "string",
                  "const": "Question"
                },
                "name": {
                  "type": "string"
                }
              }
            }
          }
        }
      },
      "Organization": {
        "type": "object",
        "properties": {
          "@context": {
            "type": "string"
          },
          "@type": {
            "type": "string",
            "const": "Organization"
          },
          "name": {
            "type": "string"
          },
          "legalName": {
            "type": "string"
          },
          "description": {
            "type": "string"
          },
          "url": {
            "type": "string"
          },
          "email": {
            "type": "string",
            "format": "email"
          },
          "taxID": {
            "type": "string"
          }
        }
      }
    }
  }
}