{
  "openapi": "3.1.0",
  "info": {
    "title": "Nexdge Review API",
    "version": "1.0.0",
    "summary": "Submit code for review by five specialists and receive severity-graded findings.",
    "description": "Nexdge reviews code for security, reliability, business logic, performance and quality problems, rewrites what fails, and re-reviews the rewrite before returning it. Security and reliability run on every request regardless of the checks array. Code is processed in memory and never stored. API access requires a Pro plan or above.",
    "contact": {
      "name": "Nexdge support",
      "email": "support@nexdge.com",
      "url": "https://www.nexdge.com/contact"
    },
    "termsOfService": "https://www.nexdge.com/terms",
    "license": {
      "name": "Proprietary",
      "url": "https://www.nexdge.com/terms"
    }
  },
  "servers": [
    {
      "url": "https://www.nexdge.com"
    }
  ],
  "externalDocs": {
    "description": "API reference",
    "url": "https://www.nexdge.com/docs/api"
  },
  "security": [
    {
      "bearerAuth": []
    },
    {
      "apiKeyHeader": []
    }
  ],
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer"
      },
      "apiKeyHeader": {
        "type": "apiKey",
        "in": "header",
        "name": "x-api-key"
      }
    },
    "schemas": {
      "AnalyzeRequest": {
        "type": "object",
        "required": [
          "code"
        ],
        "properties": {
          "code": {
            "type": "string",
            "minLength": 1,
            "maxLength": 50000,
            "description": "The code to review. 50,000 characters maximum."
          },
          "filename": {
            "type": "string",
            "maxLength": 255,
            "description": "Optional filename, echoed back in the response."
          },
          "language": {
            "type": "string",
            "enum": [
              "javascript",
              "typescript",
              "python",
              "go",
              "rust",
              "java",
              "csharp",
              "cpp",
              "ruby",
              "php",
              "swift",
              "kotlin",
              "sql",
              "html",
              "css",
              "shell",
              "yaml",
              "json",
              "other"
            ],
            "description": "Omitted, the response reports \"unknown\" rather than guessing."
          },
          "checks": {
            "type": "array",
            "items": {
              "type": "string",
              "enum": [
                "security",
                "reliability",
                "business_logic",
                "performance",
                "quality"
              ]
            },
            "description": "Which specialists to run. Defaults to all five. Security and reliability run regardless of what is listed here."
          },
          "business_context": {
            "type": "string",
            "maxLength": 2000,
            "description": "What the code is supposed to do, in business terms. This is what lets the business logic specialist find errors that are valid code, such as a discount applied after tax rather than before."
          },
          "label": {
            "type": "string",
            "maxLength": 80,
            "description": "An optional name for the review."
          },
          "apply_all_fixes": {
            "type": "boolean",
            "description": "Attempt a full rewrite addressing every finding, not only the subset that can be verified clean."
          }
        }
      },
      "AnalyzeResponse": {
        "type": "object",
        "properties": {
          "status": {
            "type": "string",
            "enum": [
              "complete"
            ]
          },
          "request_id": {
            "type": "string"
          },
          "filename": {
            "type": "string",
            "nullable": true
          },
          "language": {
            "type": "string"
          },
          "line_count": {
            "type": "integer"
          },
          "label": {
            "type": "string",
            "nullable": true
          },
          "score": {
            "type": "integer",
            "minimum": 0,
            "maximum": 100
          },
          "risk_level": {
            "type": "string",
            "enum": [
              "critical",
              "high",
              "medium",
              "low"
            ]
          },
          "credits_used": {
            "type": "integer"
          },
          "credits_remaining": {
            "type": "integer"
          },
          "partial": {
            "type": "boolean",
            "description": "True if one or more specialists failed."
          },
          "summary": {
            "type": "string",
            "description": "Plain-English synopsis, at most three sentences."
          },
          "specialists": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "name": {
                  "type": "string",
                  "enum": [
                    "security",
                    "reliability",
                    "business_logic",
                    "performance",
                    "quality"
                  ]
                },
                "score": {
                  "type": "integer"
                },
                "risk_level": {
                  "type": "string",
                  "enum": [
                    "critical",
                    "high",
                    "medium",
                    "low"
                  ]
                },
                "issue_count": {
                  "type": "integer"
                },
                "pass_count": {
                  "type": "integer"
                }
              }
            }
          },
          "findings": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "severity": {
                  "type": "string",
                  "enum": [
                    "critical",
                    "high",
                    "medium",
                    "low"
                  ]
                },
                "category": {
                  "type": "string",
                  "enum": [
                    "security",
                    "reliability",
                    "business_logic",
                    "performance",
                    "quality"
                  ]
                },
                "line": {
                  "type": "integer",
                  "nullable": true
                },
                "title": {
                  "type": "string"
                },
                "description": {
                  "type": "string"
                },
                "suggestion": {
                  "type": "string"
                }
              }
            }
          },
          "passed": {
            "type": "boolean"
          },
          "fully_rewritten": {
            "type": "boolean"
          },
          "certified_clean": {
            "type": "boolean",
            "description": "The rewrite was re-reviewed and came back clean."
          },
          "findings_addressed": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "findings_out_of_scope": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Findings a rewrite is structurally unable to fix, such as missing rate limiting or email verification. Reported separately rather than counted as resolved."
          },
          "findings_unresolved": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "requires_human_review": {
            "type": "boolean"
          },
          "alternate_available": {
            "type": "boolean"
          }
        }
      },
      "Error": {
        "type": "object",
        "properties": {
          "error": {
            "type": "string"
          },
          "retry_after": {
            "type": "integer",
            "description": "Seconds. Present on 429."
          },
          "credits_required": {
            "type": "integer",
            "description": "Present on 402."
          },
          "credits_remaining": {
            "type": "integer",
            "description": "Present on 402."
          },
          "valid_checks": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Present on 400 when an unrecognised specialist was requested."
          }
        }
      }
    }
  },
  "paths": {
    "/api/v1/analyze": {
      "post": {
        "operationId": "analyzeCode",
        "summary": "Review a piece of code",
        "description": "Runs the specialists in parallel and returns severity-graded findings. Credits are deducted only after a successful analysis; a failed request is never charged.",
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "schema": {
              "type": "string",
              "maxLength": 128,
              "pattern": "^[A-Za-z0-9_-]+$"
            },
            "description": "A repeated request carrying the same key within five minutes replays the cached response without running or re-billing the review."
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/AnalyzeRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Review complete.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AnalyzeResponse"
                }
              }
            }
          },
          "400": {
            "description": "Invalid JSON body, or an unrecognised value in checks.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Invalid or expired API key.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "402": {
            "description": "Insufficient credits.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "API access requires a Pro plan or above.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "413": {
            "description": "Request body or code exceeds the size limit.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit exceeded: 60 requests per minute per account. Includes a Retry-After header.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Temporarily unavailable. Credits are never charged for a failed attempt.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    }
  }
}