{
  "openapi": "3.1.1",
  "info": {
    "title": "Nexvra Public API — proposta MVP",
    "version": "1.0.0"
  },
  "servers": [
    {
      "url": "https://api.nexvra.ai",
      "description": "URL conceitual; não ambiente implantado"
    }
  ],
  "security": [
    {
      "apiKey": []
    }
  ],
  "paths": {
    "/v1/models": {
      "get": {
        "operationId": "listModels",
        "responses": {
          "200": {
            "description": "Modelos autorizados",
            "headers": {
              "x-nexvra-request-id": {
                "description": "ID gerado pelo gateway",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": false,
                  "properties": {
                    "object": {
                      "const": "list"
                    },
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "additionalProperties": false,
                        "properties": {
                          "id": {
                            "type": "string"
                          },
                          "object": {
                            "const": "model"
                          },
                          "created": {
                            "type": "integer",
                            "minimum": 0,
                            "maximum": 9223372036854775807
                          },
                          "owned_by": {
                            "const": "nexvra"
                          }
                        },
                        "required": [
                          "id",
                          "object",
                          "created",
                          "owned_by"
                        ]
                      }
                    }
                  },
                  "required": [
                    "object",
                    "data"
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Key inválida",
            "headers": {
              "x-nexvra-request-id": {
                "description": "ID gerado pelo gateway",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": false,
                  "properties": {
                    "error": {
                      "type": "object",
                      "additionalProperties": false,
                      "properties": {
                        "message": {
                          "type": "string"
                        },
                        "type": {
                          "type": "string",
                          "enum": [
                            "invalid_request_error",
                            "authentication_error",
                            "rate_limit_error",
                            "server_error"
                          ]
                        },
                        "param": {
                          "anyOf": [
                            {
                              "type": "string"
                            },
                            {
                              "type": "null"
                            }
                          ]
                        },
                        "code": {
                          "type": "string"
                        }
                      },
                      "required": [
                        "message",
                        "type",
                        "param",
                        "code"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "403": {
            "description": "Conta/feature desabilitada",
            "headers": {
              "x-nexvra-request-id": {
                "description": "ID gerado pelo gateway",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": false,
                  "properties": {
                    "error": {
                      "type": "object",
                      "additionalProperties": false,
                      "properties": {
                        "message": {
                          "type": "string"
                        },
                        "type": {
                          "type": "string",
                          "enum": [
                            "invalid_request_error",
                            "authentication_error",
                            "rate_limit_error",
                            "server_error"
                          ]
                        },
                        "param": {
                          "anyOf": [
                            {
                              "type": "string"
                            },
                            {
                              "type": "null"
                            }
                          ]
                        },
                        "code": {
                          "type": "string"
                        }
                      },
                      "required": [
                        "message",
                        "type",
                        "param",
                        "code"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "500": {
            "description": "Erro interno",
            "headers": {
              "x-nexvra-request-id": {
                "description": "ID gerado pelo gateway",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": false,
                  "properties": {
                    "error": {
                      "type": "object",
                      "additionalProperties": false,
                      "properties": {
                        "message": {
                          "type": "string"
                        },
                        "type": {
                          "type": "string",
                          "enum": [
                            "invalid_request_error",
                            "authentication_error",
                            "rate_limit_error",
                            "server_error"
                          ]
                        },
                        "param": {
                          "anyOf": [
                            {
                              "type": "string"
                            },
                            {
                              "type": "null"
                            }
                          ]
                        },
                        "code": {
                          "type": "string"
                        }
                      },
                      "required": [
                        "message",
                        "type",
                        "param",
                        "code"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "503": {
            "description": "Dependência indisponível",
            "headers": {
              "x-nexvra-request-id": {
                "description": "ID gerado pelo gateway",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": false,
                  "properties": {
                    "error": {
                      "type": "object",
                      "additionalProperties": false,
                      "properties": {
                        "message": {
                          "type": "string"
                        },
                        "type": {
                          "type": "string",
                          "enum": [
                            "invalid_request_error",
                            "authentication_error",
                            "rate_limit_error",
                            "server_error"
                          ]
                        },
                        "param": {
                          "anyOf": [
                            {
                              "type": "string"
                            },
                            {
                              "type": "null"
                            }
                          ]
                        },
                        "code": {
                          "type": "string"
                        }
                      },
                      "required": [
                        "message",
                        "type",
                        "param",
                        "code"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/v1/chat/completions": {
      "post": {
        "operationId": "createChatCompletion",
        "description": "Texto n=1. Campos fora deste contrato são rejeitados; SSE conforme docs/contracts.md. Limites máximos efetivos dependem do entitlement/model version/deployment.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "additionalProperties": false,
                "properties": {
                  "model": {
                    "type": "string",
                    "pattern": "^nexvra/[a-z0-9-]+$"
                  },
                  "messages": {
                    "type": "array",
                    "minItems": 1,
                    "items": {
                      "type": "object",
                      "additionalProperties": false,
                      "properties": {
                        "role": {
                          "type": "string",
                          "enum": [
                            "system",
                            "user",
                            "assistant"
                          ]
                        },
                        "content": {
                          "type": "string",
                          "minLength": 1
                        }
                      },
                      "required": [
                        "role",
                        "content"
                      ]
                    }
                  },
                  "temperature": {
                    "type": "number",
                    "minimum": 0,
                    "maximum": 2
                  },
                  "top_p": {
                    "type": "number",
                    "exclusiveMinimum": 0,
                    "maximum": 1
                  },
                  "max_tokens": {
                    "type": "integer",
                    "minimum": 1,
                    "maximum": 9223372036854775807
                  },
                  "max_completion_tokens": {
                    "type": "integer",
                    "minimum": 1,
                    "maximum": 9223372036854775807
                  },
                  "stream": {
                    "type": "boolean"
                  },
                  "stream_options": {
                    "type": "object",
                    "additionalProperties": false,
                    "properties": {
                      "include_usage": {
                        "type": "boolean"
                      }
                    },
                    "required": [
                      "include_usage"
                    ]
                  },
                  "stop": {
                    "oneOf": [
                      {
                        "type": "string",
                        "minLength": 1
                      },
                      {
                        "type": "array",
                        "minItems": 1,
                        "maxItems": 4,
                        "items": {
                          "type": "string",
                          "minLength": 1
                        }
                      }
                    ]
                  },
                  "n": {
                    "const": 1
                  }
                },
                "required": [
                  "model",
                  "messages"
                ],
                "not": {
                  "required": [
                    "max_tokens",
                    "max_completion_tokens"
                  ]
                },
                "allOf": [
                  {
                    "if": {
                      "required": [
                        "stream_options"
                      ]
                    },
                    "then": {
                      "required": [
                        "stream"
                      ],
                      "properties": {
                        "stream": {
                          "const": true
                        }
                      }
                    }
                  }
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "JSON final ou stream SSE incremental. Usage pode estar ausente quando desconhecido.",
            "headers": {
              "x-nexvra-request-id": {
                "description": "ID gerado pelo gateway",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": false,
                  "properties": {
                    "id": {
                      "type": "string"
                    },
                    "object": {
                      "const": "chat.completion"
                    },
                    "created": {
                      "type": "integer",
                      "minimum": 0,
                      "maximum": 9223372036854775807
                    },
                    "model": {
                      "type": "string"
                    },
                    "choices": {
                      "type": "array",
                      "minItems": 1,
                      "maxItems": 1,
                      "items": {
                        "type": "object",
                        "additionalProperties": false,
                        "properties": {
                          "index": {
                            "const": 0
                          },
                          "message": {
                            "type": "object",
                            "additionalProperties": false,
                            "properties": {
                              "role": {
                                "const": "assistant"
                              },
                              "content": {
                                "type": "string"
                              }
                            },
                            "required": [
                              "role",
                              "content"
                            ]
                          },
                          "finish_reason": {
                            "type": "string",
                            "enum": [
                              "stop",
                              "length",
                              "content_filter"
                            ]
                          }
                        },
                        "required": [
                          "index",
                          "message",
                          "finish_reason"
                        ]
                      }
                    },
                    "usage": {
                      "type": "object",
                      "additionalProperties": false,
                      "properties": {
                        "prompt_tokens": {
                          "type": "integer",
                          "minimum": 0,
                          "maximum": 9223372036854775807
                        },
                        "completion_tokens": {
                          "type": "integer",
                          "minimum": 0,
                          "maximum": 9223372036854775807
                        },
                        "total_tokens": {
                          "type": "integer",
                          "minimum": 0,
                          "maximum": 9223372036854775807
                        },
                        "prompt_tokens_details": {
                          "type": "object",
                          "additionalProperties": false,
                          "properties": {
                            "cached_tokens": {
                              "type": "integer",
                              "minimum": 0,
                              "maximum": 9223372036854775807
                            }
                          },
                          "required": [
                            "cached_tokens"
                          ]
                        },
                        "completion_tokens_details": {
                          "type": "object",
                          "additionalProperties": false,
                          "properties": {
                            "reasoning_tokens": {
                              "type": "integer",
                              "minimum": 0,
                              "maximum": 9223372036854775807
                            }
                          },
                          "required": [
                            "reasoning_tokens"
                          ]
                        }
                      },
                      "required": [
                        "prompt_tokens",
                        "completion_tokens",
                        "total_tokens"
                      ]
                    }
                  },
                  "required": [
                    "id",
                    "object",
                    "created",
                    "model",
                    "choices"
                  ]
                }
              },
              "text/event-stream": {
                "schema": {
                  "type": "string"
                },
                "example": "data: {\"id\":\"chatcmpl_example\",\"object\":\"chat.completion.chunk\",\"created\":0,\"model\":\"nexvra/qwen-chat\",\"choices\":[{\"index\":0,\"delta\":{\"content\":\"Olá\"},\"finish_reason\":null}]}\n\ndata: {\"id\":\"chatcmpl_example\",\"object\":\"chat.completion.chunk\",\"created\":0,\"model\":\"nexvra/qwen-chat\",\"choices\":[{\"index\":0,\"delta\":{},\"finish_reason\":\"stop\"}]}\n\ndata: [DONE]\n\n"
              }
            }
          },
          "400": {
            "description": "Entrada inválida",
            "headers": {
              "x-nexvra-request-id": {
                "description": "ID gerado pelo gateway",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": false,
                  "properties": {
                    "error": {
                      "type": "object",
                      "additionalProperties": false,
                      "properties": {
                        "message": {
                          "type": "string"
                        },
                        "type": {
                          "type": "string",
                          "enum": [
                            "invalid_request_error",
                            "authentication_error",
                            "rate_limit_error",
                            "server_error"
                          ]
                        },
                        "param": {
                          "anyOf": [
                            {
                              "type": "string"
                            },
                            {
                              "type": "null"
                            }
                          ]
                        },
                        "code": {
                          "type": "string"
                        }
                      },
                      "required": [
                        "message",
                        "type",
                        "param",
                        "code"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Key inválida",
            "headers": {
              "x-nexvra-request-id": {
                "description": "ID gerado pelo gateway",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": false,
                  "properties": {
                    "error": {
                      "type": "object",
                      "additionalProperties": false,
                      "properties": {
                        "message": {
                          "type": "string"
                        },
                        "type": {
                          "type": "string",
                          "enum": [
                            "invalid_request_error",
                            "authentication_error",
                            "rate_limit_error",
                            "server_error"
                          ]
                        },
                        "param": {
                          "anyOf": [
                            {
                              "type": "string"
                            },
                            {
                              "type": "null"
                            }
                          ]
                        },
                        "code": {
                          "type": "string"
                        }
                      },
                      "required": [
                        "message",
                        "type",
                        "param",
                        "code"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "403": {
            "description": "Conta/feature desabilitada",
            "headers": {
              "x-nexvra-request-id": {
                "description": "ID gerado pelo gateway",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": false,
                  "properties": {
                    "error": {
                      "type": "object",
                      "additionalProperties": false,
                      "properties": {
                        "message": {
                          "type": "string"
                        },
                        "type": {
                          "type": "string",
                          "enum": [
                            "invalid_request_error",
                            "authentication_error",
                            "rate_limit_error",
                            "server_error"
                          ]
                        },
                        "param": {
                          "anyOf": [
                            {
                              "type": "string"
                            },
                            {
                              "type": "null"
                            }
                          ]
                        },
                        "code": {
                          "type": "string"
                        }
                      },
                      "required": [
                        "message",
                        "type",
                        "param",
                        "code"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "404": {
            "description": "Modelo não encontrado/autorizado",
            "headers": {
              "x-nexvra-request-id": {
                "description": "ID gerado pelo gateway",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": false,
                  "properties": {
                    "error": {
                      "type": "object",
                      "additionalProperties": false,
                      "properties": {
                        "message": {
                          "type": "string"
                        },
                        "type": {
                          "type": "string",
                          "enum": [
                            "invalid_request_error",
                            "authentication_error",
                            "rate_limit_error",
                            "server_error"
                          ]
                        },
                        "param": {
                          "anyOf": [
                            {
                              "type": "string"
                            },
                            {
                              "type": "null"
                            }
                          ]
                        },
                        "code": {
                          "type": "string"
                        }
                      },
                      "required": [
                        "message",
                        "type",
                        "param",
                        "code"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "413": {
            "description": "Payload excedido",
            "headers": {
              "x-nexvra-request-id": {
                "description": "ID gerado pelo gateway",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": false,
                  "properties": {
                    "error": {
                      "type": "object",
                      "additionalProperties": false,
                      "properties": {
                        "message": {
                          "type": "string"
                        },
                        "type": {
                          "type": "string",
                          "enum": [
                            "invalid_request_error",
                            "authentication_error",
                            "rate_limit_error",
                            "server_error"
                          ]
                        },
                        "param": {
                          "anyOf": [
                            {
                              "type": "string"
                            },
                            {
                              "type": "null"
                            }
                          ]
                        },
                        "code": {
                          "type": "string"
                        }
                      },
                      "required": [
                        "message",
                        "type",
                        "param",
                        "code"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "429": {
            "description": "Limite confirmado excedido",
            "headers": {
              "x-nexvra-request-id": {
                "description": "ID gerado pelo gateway",
                "schema": {
                  "type": "string"
                }
              },
              "Retry-After": {
                "description": "Segundos até nova tentativa quando espera calculável",
                "schema": {
                  "type": "integer",
                  "minimum": 1
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": false,
                  "properties": {
                    "error": {
                      "type": "object",
                      "additionalProperties": false,
                      "properties": {
                        "message": {
                          "type": "string"
                        },
                        "type": {
                          "type": "string",
                          "enum": [
                            "invalid_request_error",
                            "authentication_error",
                            "rate_limit_error",
                            "server_error"
                          ]
                        },
                        "param": {
                          "anyOf": [
                            {
                              "type": "string"
                            },
                            {
                              "type": "null"
                            }
                          ]
                        },
                        "code": {
                          "type": "string"
                        }
                      },
                      "required": [
                        "message",
                        "type",
                        "param",
                        "code"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "500": {
            "description": "Erro interno",
            "headers": {
              "x-nexvra-request-id": {
                "description": "ID gerado pelo gateway",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": false,
                  "properties": {
                    "error": {
                      "type": "object",
                      "additionalProperties": false,
                      "properties": {
                        "message": {
                          "type": "string"
                        },
                        "type": {
                          "type": "string",
                          "enum": [
                            "invalid_request_error",
                            "authentication_error",
                            "rate_limit_error",
                            "server_error"
                          ]
                        },
                        "param": {
                          "anyOf": [
                            {
                              "type": "string"
                            },
                            {
                              "type": "null"
                            }
                          ]
                        },
                        "code": {
                          "type": "string"
                        }
                      },
                      "required": [
                        "message",
                        "type",
                        "param",
                        "code"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "503": {
            "description": "Backend indisponível, timeout de inferência ou dependência indisponível (503 em vez de 502/504: a CDN troca o corpo desses dois)",
            "headers": {
              "x-nexvra-request-id": {
                "description": "ID gerado pelo gateway",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": false,
                  "properties": {
                    "error": {
                      "type": "object",
                      "additionalProperties": false,
                      "properties": {
                        "message": {
                          "type": "string"
                        },
                        "type": {
                          "type": "string",
                          "enum": [
                            "invalid_request_error",
                            "authentication_error",
                            "rate_limit_error",
                            "server_error"
                          ]
                        },
                        "param": {
                          "anyOf": [
                            {
                              "type": "string"
                            },
                            {
                              "type": "null"
                            }
                          ]
                        },
                        "code": {
                          "type": "string"
                        }
                      },
                      "required": [
                        "message",
                        "type",
                        "param",
                        "code"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "apiKey": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "nxv_<id>_<secret>"
      }
    },
    "schemas": {
      "ChatCompletionChunk": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "id": {
            "type": "string"
          },
          "object": {
            "const": "chat.completion.chunk"
          },
          "created": {
            "type": "integer",
            "minimum": 0,
            "maximum": 9223372036854775807
          },
          "model": {
            "type": "string"
          },
          "choices": {
            "type": "array",
            "maxItems": 1,
            "items": {
              "type": "object",
              "additionalProperties": false,
              "properties": {
                "index": {
                  "const": 0
                },
                "delta": {
                  "type": "object",
                  "additionalProperties": false,
                  "properties": {
                    "role": {
                      "const": "assistant"
                    },
                    "content": {
                      "type": "string"
                    }
                  },
                  "required": []
                },
                "finish_reason": {
                  "anyOf": [
                    {
                      "type": "string",
                      "enum": [
                        "stop",
                        "length",
                        "content_filter"
                      ]
                    },
                    {
                      "type": "null"
                    }
                  ]
                }
              },
              "required": [
                "index",
                "delta",
                "finish_reason"
              ]
            }
          },
          "usage": {
            "anyOf": [
              {
                "type": "object",
                "additionalProperties": false,
                "properties": {
                  "prompt_tokens": {
                    "type": "integer",
                    "minimum": 0,
                    "maximum": 9223372036854775807
                  },
                  "completion_tokens": {
                    "type": "integer",
                    "minimum": 0,
                    "maximum": 9223372036854775807
                  },
                  "total_tokens": {
                    "type": "integer",
                    "minimum": 0,
                    "maximum": 9223372036854775807
                  },
                  "prompt_tokens_details": {
                    "type": "object",
                    "additionalProperties": false,
                    "properties": {
                      "cached_tokens": {
                        "type": "integer",
                        "minimum": 0,
                        "maximum": 9223372036854775807
                      }
                    },
                    "required": [
                      "cached_tokens"
                    ]
                  },
                  "completion_tokens_details": {
                    "type": "object",
                    "additionalProperties": false,
                    "properties": {
                      "reasoning_tokens": {
                        "type": "integer",
                        "minimum": 0,
                        "maximum": 9223372036854775807
                      }
                    },
                    "required": [
                      "reasoning_tokens"
                    ]
                  }
                },
                "required": [
                  "prompt_tokens",
                  "completion_tokens",
                  "total_tokens"
                ]
              },
              {
                "type": "null"
              }
            ]
          }
        },
        "required": [
          "id",
          "object",
          "created",
          "model",
          "choices"
        ]
      },
      "Error": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "error": {
            "type": "object",
            "additionalProperties": false,
            "properties": {
              "message": {
                "type": "string"
              },
              "type": {
                "type": "string",
                "enum": [
                  "invalid_request_error",
                  "authentication_error",
                  "rate_limit_error",
                  "server_error"
                ]
              },
              "param": {
                "anyOf": [
                  {
                    "type": "string"
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "code": {
                "type": "string"
              }
            },
            "required": [
              "message",
              "type",
              "param",
              "code"
            ]
          }
        },
        "required": [
          "error"
        ]
      }
    }
  }
}