{
  "openapi": "3.1.0",
  "info": {
    "title": "Netter Intelligence Inference API",
    "version": "0.1.0",
    "description": "Contratti nativi inoltrati a route compatibili. Il catalogo espone nomi upstream reali o alias pubblici configurati; switchyard è il nome riservato al routing intelligente."
  },
  "servers": [
    {
      "url": "https://api.llm.netter.io/v1"
    }
  ],
  "security": [
    {
      "bearer": []
    },
    {
      "anthropicKey": []
    }
  ],
  "paths": {
    "/models": {
      "get": {
        "operationId": "get_models",
        "responses": {
          "200": {
            "description": "Risposta nel protocollo richiesto, con casting PII applicato",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              },
              "text/event-stream": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "402": {
            "description": "Plafond insufficiente"
          },
          "403": {
            "description": "Profilo non autorizzato"
          },
          "503": {
            "description": "Servizio richiesto non disponibile; nessun bypass della protezione"
          }
        }
      }
    },
    "/models/{id}": {
      "get": {
        "operationId": "get_models_id",
        "responses": {
          "200": {
            "description": "Risposta nel protocollo richiesto, con casting PII applicato",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              },
              "text/event-stream": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "402": {
            "description": "Plafond insufficiente"
          },
          "403": {
            "description": "Profilo non autorizzato"
          },
          "503": {
            "description": "Servizio richiesto non disponibile; nessun bypass della protezione"
          }
        },
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ]
      }
    },
    "/chat/completions": {
      "post": {
        "operationId": "post_chat_completions",
        "responses": {
          "200": {
            "description": "Risposta nel protocollo richiesto, con casting PII applicato",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              },
              "text/event-stream": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "402": {
            "description": "Plafond insufficiente"
          },
          "403": {
            "description": "Profilo non autorizzato"
          },
          "503": {
            "description": "Servizio richiesto non disponibile; nessun bypass della protezione"
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "model": {
                    "$ref": "#/components/schemas/Profile"
                  },
                  "stream": {
                    "type": "boolean"
                  },
                  "reasoning_effort": {
                    "$ref": "#/components/schemas/ReasoningEffort"
                  }
                },
                "additionalProperties": true,
                "description": "Con model=switchyard la selezione genera un consumo distinto dalla risposta, entro il budget complessivo. I target e le tariffe sono controllati dal server."
              }
            }
          }
        }
      }
    },
    "/responses": {
      "post": {
        "operationId": "post_responses",
        "responses": {
          "200": {
            "description": "Risposta nel protocollo richiesto, con casting PII applicato",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              },
              "text/event-stream": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "402": {
            "description": "Plafond insufficiente"
          },
          "403": {
            "description": "Profilo non autorizzato"
          },
          "503": {
            "description": "Servizio richiesto non disponibile; nessun bypass della protezione"
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "model": {
                    "$ref": "#/components/schemas/Profile"
                  },
                  "stream": {
                    "type": "boolean"
                  },
                  "reasoning_effort": {
                    "$ref": "#/components/schemas/ReasoningEffort"
                  }
                },
                "additionalProperties": true,
                "description": "Con model=switchyard la selezione genera un consumo distinto dalla risposta, entro il budget complessivo. I target e le tariffe sono controllati dal server."
              }
            }
          }
        }
      }
    },
    "/responses/{id}": {
      "get": {
        "operationId": "get_responses_id",
        "responses": {
          "200": {
            "description": "Risposta nel protocollo richiesto, con casting PII applicato",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              },
              "text/event-stream": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "402": {
            "description": "Plafond insufficiente"
          },
          "403": {
            "description": "Profilo non autorizzato"
          },
          "503": {
            "description": "Servizio richiesto non disponibile; nessun bypass della protezione"
          }
        },
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ]
      },
      "delete": {
        "operationId": "delete_responses_id",
        "responses": {
          "200": {
            "description": "Risposta nel protocollo richiesto, con casting PII applicato",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              },
              "text/event-stream": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "402": {
            "description": "Plafond insufficiente"
          },
          "403": {
            "description": "Profilo non autorizzato"
          },
          "503": {
            "description": "Servizio richiesto non disponibile; nessun bypass della protezione"
          }
        },
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ]
      }
    },
    "/messages": {
      "post": {
        "operationId": "post_messages",
        "responses": {
          "200": {
            "description": "Risposta nel protocollo richiesto, con casting PII applicato",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              },
              "text/event-stream": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "402": {
            "description": "Plafond insufficiente"
          },
          "403": {
            "description": "Profilo non autorizzato"
          },
          "503": {
            "description": "Servizio richiesto non disponibile; nessun bypass della protezione"
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "model": {
                    "$ref": "#/components/schemas/Profile"
                  },
                  "stream": {
                    "type": "boolean"
                  },
                  "reasoning_effort": {
                    "$ref": "#/components/schemas/ReasoningEffort"
                  }
                },
                "additionalProperties": true,
                "description": "Con model=switchyard la selezione genera un consumo distinto dalla risposta, entro il budget complessivo. I target e le tariffe sono controllati dal server."
              }
            }
          }
        }
      }
    },
    "/messages/count_tokens": {
      "post": {
        "operationId": "post_messages_count_tokens",
        "responses": {
          "200": {
            "description": "Risposta nel protocollo richiesto, con casting PII applicato",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              },
              "text/event-stream": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "402": {
            "description": "Plafond insufficiente"
          },
          "403": {
            "description": "Profilo non autorizzato"
          },
          "503": {
            "description": "Servizio richiesto non disponibile; nessun bypass della protezione"
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "model": {
                    "$ref": "#/components/schemas/Profile"
                  },
                  "stream": {
                    "type": "boolean"
                  }
                },
                "additionalProperties": true
              }
            }
          }
        }
      }
    },
    "/embeddings": {
      "post": {
        "operationId": "post_embeddings",
        "responses": {
          "200": {
            "description": "Risposta nel protocollo richiesto, con casting PII applicato",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              },
              "text/event-stream": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "402": {
            "description": "Plafond insufficiente"
          },
          "403": {
            "description": "Profilo non autorizzato"
          },
          "503": {
            "description": "Servizio richiesto non disponibile; nessun bypass della protezione"
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "model": {
                    "$ref": "#/components/schemas/Profile"
                  },
                  "stream": {
                    "type": "boolean"
                  }
                },
                "additionalProperties": true
              }
            }
          }
        }
      }
    },
    "/systemone": {
      "post": {
        "operationId": "post_systemone",
        "responses": {
          "200": {
            "description": "Risposta nel protocollo richiesto, con casting PII applicato",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              },
              "text/event-stream": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "402": {
            "description": "Plafond insufficiente"
          },
          "403": {
            "description": "Profilo non autorizzato"
          },
          "503": {
            "description": "Servizio richiesto non disponibile; nessun bypass della protezione"
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "model": {
                    "$ref": "#/components/schemas/Profile"
                  },
                  "stream": {
                    "type": "boolean"
                  }
                },
                "additionalProperties": true
              }
            }
          }
        }
      }
    },
    "/audio/speech": {
      "post": {
        "operationId": "post_audio_speech",
        "responses": {
          "200": {
            "description": "Risposta nel protocollo richiesto, con casting PII applicato",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              },
              "text/event-stream": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "402": {
            "description": "Plafond insufficiente"
          },
          "403": {
            "description": "Profilo non autorizzato"
          },
          "503": {
            "description": "Servizio richiesto non disponibile; nessun bypass della protezione"
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "model": {
                    "$ref": "#/components/schemas/Profile"
                  },
                  "stream": {
                    "type": "boolean"
                  }
                },
                "additionalProperties": true
              }
            }
          }
        }
      }
    },
    "/audio/transcriptions": {
      "post": {
        "operationId": "post_audio_transcriptions",
        "responses": {
          "200": {
            "description": "Risposta nel protocollo richiesto, con casting PII applicato",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              },
              "text/event-stream": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "402": {
            "description": "Plafond insufficiente"
          },
          "403": {
            "description": "Profilo non autorizzato"
          },
          "503": {
            "description": "Servizio richiesto non disponibile; nessun bypass della protezione"
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "multipart/form-data": {
              "schema": {
                "type": "object",
                "required": [
                  "file"
                ],
                "properties": {
                  "model": {
                    "$ref": "#/components/schemas/Profile"
                  },
                  "file": {
                    "type": "string",
                    "format": "binary"
                  }
                }
              }
            }
          }
        }
      }
    },
    "/audio/translations": {
      "post": {
        "operationId": "post_audio_translations",
        "responses": {
          "200": {
            "description": "Risposta nel protocollo richiesto, con casting PII applicato",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              },
              "text/event-stream": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "402": {
            "description": "Plafond insufficiente"
          },
          "403": {
            "description": "Profilo non autorizzato"
          },
          "503": {
            "description": "Servizio richiesto non disponibile; nessun bypass della protezione"
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "multipart/form-data": {
              "schema": {
                "type": "object",
                "required": [
                  "file"
                ],
                "properties": {
                  "model": {
                    "$ref": "#/components/schemas/Profile"
                  },
                  "file": {
                    "type": "string",
                    "format": "binary"
                  }
                }
              }
            }
          }
        }
      }
    },
    "/files": {
      "get": {
        "operationId": "get_files",
        "responses": {
          "200": {
            "description": "Risposta nel protocollo richiesto, con casting PII applicato",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              },
              "text/event-stream": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "402": {
            "description": "Plafond insufficiente"
          },
          "403": {
            "description": "Profilo non autorizzato"
          },
          "503": {
            "description": "Servizio richiesto non disponibile; nessun bypass della protezione"
          }
        }
      },
      "post": {
        "operationId": "post_files",
        "responses": {
          "200": {
            "description": "Risposta nel protocollo richiesto, con casting PII applicato",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              },
              "text/event-stream": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "402": {
            "description": "Plafond insufficiente"
          },
          "403": {
            "description": "Profilo non autorizzato"
          },
          "503": {
            "description": "Servizio richiesto non disponibile; nessun bypass della protezione"
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "multipart/form-data": {
              "schema": {
                "type": "object",
                "required": [
                  "file"
                ],
                "properties": {
                  "model": {
                    "$ref": "#/components/schemas/Profile"
                  },
                  "file": {
                    "type": "string",
                    "format": "binary"
                  }
                }
              }
            }
          }
        }
      }
    },
    "/files/{id}": {
      "get": {
        "operationId": "get_files_id",
        "responses": {
          "200": {
            "description": "Risposta nel protocollo richiesto, con casting PII applicato",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              },
              "text/event-stream": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "402": {
            "description": "Plafond insufficiente"
          },
          "403": {
            "description": "Profilo non autorizzato"
          },
          "503": {
            "description": "Servizio richiesto non disponibile; nessun bypass della protezione"
          }
        },
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ]
      },
      "delete": {
        "operationId": "delete_files_id",
        "responses": {
          "200": {
            "description": "Risposta nel protocollo richiesto, con casting PII applicato",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              },
              "text/event-stream": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "402": {
            "description": "Plafond insufficiente"
          },
          "403": {
            "description": "Profilo non autorizzato"
          },
          "503": {
            "description": "Servizio richiesto non disponibile; nessun bypass della protezione"
          }
        },
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ]
      }
    },
    "/files/{id}/content": {
      "get": {
        "operationId": "get_files_id_content",
        "responses": {
          "200": {
            "description": "Risposta nel protocollo richiesto, con casting PII applicato",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              },
              "text/event-stream": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "402": {
            "description": "Plafond insufficiente"
          },
          "403": {
            "description": "Profilo non autorizzato"
          },
          "503": {
            "description": "Servizio richiesto non disponibile; nessun bypass della protezione"
          }
        },
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ]
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearer": {
        "type": "http",
        "scheme": "bearer"
      },
      "anthropicKey": {
        "type": "apiKey",
        "in": "header",
        "name": "x-api-key"
      }
    },
    "schemas": {
      "Profile": {
        "type": "string",
        "minLength": 1,
        "maxLength": 200,
        "pattern": "^[A-Za-z0-9][A-Za-z0-9._:/+@-]*$",
        "description": "Nome pubblico esatto del modello o alias configurato; switchyard è riservato al routing intelligente."
      },
      "Money": {
        "type": "string",
        "pattern": "^\\d+(\\.\\d{1,9})?$",
        "description": "Importo decimale esatto in euro; non usare floating point."
      },
      "Error": {
        "type": "object",
        "required": [
          "error"
        ],
        "properties": {
          "error": {
            "type": "object",
            "properties": {
              "type": {
                "type": "string"
              },
              "message": {
                "type": "string"
              },
              "code": {
                "type": "string"
              }
            }
          }
        }
      },
      "Principal": {
        "type": "object",
        "required": [
          "user_id",
          "tenant_id",
          "wallet_id",
          "role",
          "allowed_profiles",
          "pii_enabled"
        ],
        "properties": {
          "user_id": {
            "type": "string",
            "format": "uuid"
          },
          "tenant_id": {
            "type": "string",
            "format": "uuid"
          },
          "wallet_id": {
            "type": "string",
            "format": "uuid"
          },
          "role": {
            "type": "string"
          },
          "netter_role": {
            "type": [
              "string",
              "null"
            ]
          },
          "allowed_profiles": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Profile"
            }
          },
          "pii_enabled": {
            "type": "boolean"
          }
        }
      },
      "TopupRequest": {
        "type": "object",
        "required": [
          "amount_eur"
        ],
        "properties": {
          "amount_eur": {
            "$ref": "#/components/schemas/Money"
          }
        }
      },
      "PaymentConfirmation": {
        "type": "object",
        "required": [
          "bank_reference",
          "bank_date",
          "received_eur"
        ],
        "properties": {
          "bank_reference": {
            "type": "string",
            "minLength": 6,
            "maxLength": 120
          },
          "bank_date": {
            "type": "string",
            "format": "date"
          },
          "received_eur": {
            "$ref": "#/components/schemas/Money"
          }
        }
      },
      "APIKeyRequest": {
        "type": "object",
        "required": [
          "name"
        ],
        "properties": {
          "name": {
            "type": "string"
          },
          "allowed_profiles": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Profile"
            }
          },
          "max_request_eur": {
            "$ref": "#/components/schemas/Money"
          },
          "budget_eur": {
            "$ref": "#/components/schemas/Money"
          },
          "expires_in_days": {
            "type": "integer",
            "minimum": 1,
            "maximum": 365
          },
          "wallet_id": {
            "type": "string",
            "format": "uuid"
          },
          "allow_all_models": {
            "type": "boolean",
            "default": false,
            "description": "Consente anche i modelli pubblicati in futuro, sempre entro le policy superiori."
          }
        }
      },
      "Policy": {
        "type": "object",
        "required": [
          "scope_kind",
          "scope_id",
          "allowed_profiles",
          "default_profile",
          "pii_required",
          "max_request_eur"
        ],
        "properties": {
          "scope_kind": {
            "type": "string",
            "enum": [
              "netter",
              "reseller",
              "tenant",
              "group",
              "user"
            ]
          },
          "scope_id": {
            "type": "string",
            "format": "uuid"
          },
          "allowed_profiles": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Profile"
            },
            "minItems": 1
          },
          "default_profile": {
            "$ref": "#/components/schemas/Profile"
          },
          "pii_required": {
            "type": "boolean"
          },
          "max_request_eur": {
            "$ref": "#/components/schemas/Money"
          },
          "allow_all_models": {
            "type": "boolean",
            "default": false,
            "description": "Consente anche i modelli pubblicati in futuro, sempre entro le policy superiori."
          }
        }
      },
      "Transfer": {
        "type": "object",
        "required": [
          "id",
          "source_id",
          "destination_id",
          "amount_eur"
        ],
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "source_id": {
            "type": "string",
            "format": "uuid"
          },
          "destination_id": {
            "type": "string",
            "format": "uuid"
          },
          "amount_eur": {
            "$ref": "#/components/schemas/Money"
          }
        }
      },
      "Allocation": {
        "type": "object",
        "required": [
          "id",
          "parent_id",
          "allocations"
        ],
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "parent_id": {
            "type": "string",
            "format": "uuid"
          },
          "allocations": {
            "type": "array",
            "items": {
              "type": "object",
              "required": [
                "wallet_id",
                "basis_points"
              ],
              "properties": {
                "wallet_id": {
                  "type": "string",
                  "format": "uuid"
                },
                "basis_points": {
                  "type": "integer",
                  "minimum": 1,
                  "maximum": 10000
                }
              }
            }
          },
          "frequency": {
            "type": "string",
            "enum": [
              "daily",
              "weekly",
              "monthly"
            ]
          }
        }
      },
      "ReasoningEffort": {
        "type": "string",
        "enum": [
          "none",
          "minimal",
          "low",
          "medium",
          "high",
          "xhigh",
          "max"
        ],
        "default": "medium",
        "description": "Switchyard cerca il livello più vicino, preferendo quello superiore a parità di distanza."
      }
    }
  }
}