openapi.json

{
  "openapi": "3.1.0",
  "info": {
    "title": "nuanced-lsp",
    "description": "",
    "license": {
      "name": "MIT",
      "url": "https://opensource.org/licenses/MIT"
    },
    "version": "0.5.0"
  },
  "servers": [
    {
      "url": "http://localhost:4444/v1",
      "description": "API server v1"
    }
  ],
  "paths": {
    "/symbol/definitions-in-file": {
      "get": {
        "tags": [
          "symbol"
        ],
        "summary": "Get all symbol definitions in a file",
        "operationId": "definitions_in_file",
        "parameters": [
          {
            "name": "file_path",
            "in": "query",
            "description": "The path to the file to get the symbols for, relative to the root of the workspace.",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Symbols retrieved successfully",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/Symbol"
                  }
                }
              }
            }
          },
          "400": {
            "description": "Bad request"
          },
          "500": {
            "description": "Internal server error"
          }
        }
      }
    },
    "/symbol/find-definition": {
      "post": {
        "tags": [
          "symbol"
        ],
        "summary": "Get the definition of a symbol at a specific position in a file",
        "operationId": "find_definition",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/FindDefinitionRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "Definition retrieved successfully",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/FindDefinitionResponse"
                }
              }
            }
          },
          "400": {
            "description": "Bad request"
          },
          "500": {
            "description": "Internal server error"
          }
        }
      }
    },
    "/symbol/find-identifier": {
      "post": {
        "tags": [
          "symbol"
        ],
        "summary": "Find an identifier by name",
        "operationId": "find_identifier",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/FindIdentifierRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "Identifier found successfully",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/FindIdentifierResponse"
                }
              }
            }
          },
          "400": {
            "description": "Bad request"
          },
          "500": {
            "description": "Internal server error"
          }
        }
      }
    },
    "/symbol/find-referenced-symbols": {
      "post": {
        "tags": [
          "symbol"
        ],
        "summary": "Find all symbols referenced within a given symbol",
        "operationId": "find_referenced_symbols",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/FindReferencedSymbolsRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "Referenced symbols retrieved successfully",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/FindReferencedSymbolsResponse"
                }
              }
            }
          },
          "400": {
            "description": "Bad request"
          },
          "500": {
            "description": "Internal server error"
          }
        }
      }
    },
    "/symbol/find-references": {
      "post": {
        "tags": [
          "symbol"
        ],
        "summary": "Get all references to a symbol",
        "operationId": "find_references",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/FindReferencesRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "References retrieved successfully",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/FindReferencesResponse"
                }
              }
            }
          },
          "400": {
            "description": "Bad request"
          },
          "500": {
            "description": "Internal server error"
          }
        }
      }
    },
    "/system/health": {
      "get": {
        "tags": [
          "system"
        ],
        "summary": "Get health status of the LSP proxy service",
        "description": "Returns the service status, version and language server availability\nReturns 503 Service Unavailable while initialization is in progress",
        "operationId": "health_check",
        "responses": {
          "200": {
            "description": "Service is healthy and initialized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HealthResponse"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error"
          },
          "503": {
            "description": "Service is initializing",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HealthResponse"
                }
              }
            }
          }
        }
      }
    },
    "/workspace/list-files": {
      "get": {
        "tags": [
          "file"
        ],
        "summary": "List all files in the workspace",
        "operationId": "list_files",
        "responses": {
          "200": {
            "description": "Files listed successfully",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "type": "string"
                  }
                }
              }
            }
          },
          "500": {
            "description": "Internal server error"
          }
        }
      }
    },
    "/workspace/read-source-code": {
      "post": {
        "tags": [
          "file"
        ],
        "summary": "Read source code from a file",
        "operationId": "read_source_code",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ReadSourceCodeRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "Source code retrieved successfully",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ReadSourceCodeResponse"
                }
              }
            }
          },
          "400": {
            "description": "Bad request"
          },
          "500": {
            "description": "Internal server error"
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "CodeContext": {
        "type": "object",
        "required": [
          "range",
          "source_code"
        ],
        "properties": {
          "range": {
            "$ref": "#/components/schemas/FileRange"
          },
          "source_code": {
            "type": "string"
          }
        }
      },
      "DefinitionsInFileRequest": {
        "type": "object",
        "description": "Request to get the symbols in a file.",
        "required": [
          "file_path"
        ],
        "properties": {
          "file_path": {
            "type": "string",
            "description": "The path to the file to get the symbols for, relative to the root of the workspace.",
            "example": "src/main.py"
          }
        }
      },
      "ErrorResponse": {
        "type": "object",
        "description": "Response returned when an API error occurs",
        "required": [
          "error"
        ],
        "properties": {
          "error": {
            "type": "string",
            "description": "Description of the error that occurred"
          }
        }
      },
      "FilePosition": {
        "type": "object",
        "description": "A position within a specific file in the workspace",
        "required": [
          "path",
          "position"
        ],
        "properties": {
          "path": {
            "type": "string",
            "description": "Path to the file, relative to the workspace root",
            "example": "src/main.py"
          },
          "position": {
            "$ref": "#/components/schemas/Position",
            "description": "Position within the file"
          }
        }
      },
      "FileRange": {
        "type": "object",
        "description": "A range within a specific file, defined by start and end positions",
        "required": [
          "path",
          "range"
        ],
        "properties": {
          "path": {
            "type": "string",
            "description": "The path to the file.",
            "example": "src/main.py"
          },
          "range": {
            "$ref": "#/components/schemas/Range",
            "description": "The range within the file"
          }
        }
      },
      "FindDefinitionRequest": {
        "type": "object",
        "required": [
          "position"
        ],
        "properties": {
          "include_raw_response": {
            "type": "boolean",
            "description": "Whether to include the raw response from the langserver in the response.\nDefaults to false.",
            "example": false
          },
          "include_source_code": {
            "type": "boolean",
            "description": "Whether to include the source code around the symbol's identifier in the response.\nDefaults to false.\nTODO: Implement this",
            "example": false
          },
          "position": {
            "$ref": "#/components/schemas/FilePosition"
          }
        }
      },
      "FindDefinitionResponse": {
        "type": "object",
        "description": "Response to a definition request.\n\nThe definition(s) of the symbol.\nPoints to the start position of the symbol's identifier.\n\ne.g. for the definition of `User` on line 5 of `src/main.py` with the code:\n```text\n0: class User:\n_________^\n1:     def __init__(self, name, age):\n2:         self.name = name\n3:         self.age = age\n4:\n5: user = User(\"John\", 30)\n__________^\n```\nThe definition(s) will be `[{\"path\": \"src/main.py\", \"line\": 0, \"character\": 6}]`.",
        "required": [
          "definitions",
          "selected_identifier"
        ],
        "properties": {
          "definitions": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/FilePosition"
            }
          },
          "raw_response": {
            "description": "The raw response from the langserver.\n\nhttps://microsoft.github.io/language-server-protocol/specifications/lsp/3.17/specification/#textDocument_definition"
          },
          "selected_identifier": {
            "$ref": "#/components/schemas/Identifier",
            "description": "The identifier that was \"clicked-on\" to get the definition."
          },
          "source_code_context": {
            "type": [
              "array",
              "null"
            ],
            "items": {
              "$ref": "#/components/schemas/CodeContext"
            },
            "description": "The source code of symbol definitions."
          }
        }
      },
      "FindIdentifierRequest": {
        "type": "object",
        "required": [
          "name",
          "path"
        ],
        "properties": {
          "name": {
            "type": "string",
            "description": "The name of the identifier to search for.",
            "example": "User"
          },
          "path": {
            "type": "string",
            "description": "The path to the file to search for identifiers.",
            "example": "src/main.py"
          },
          "position": {
            "oneOf": [
              {
                "type": "null"
              },
              {
                "$ref": "#/components/schemas/Position",
                "description": "The position hint to search for identifiers. If not provided."
              }
            ]
          }
        }
      },
      "FindIdentifierResponse": {
        "type": "object",
        "required": [
          "identifiers"
        ],
        "properties": {
          "identifiers": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Identifier"
            }
          }
        }
      },
      "FindReferencedSymbolsRequest": {
        "type": "object",
        "description": "Request to get all symbols that are referenced from a symbol at the given position, either\nfocusing on function calls, or more permissively finding all references\n\nThe input position must point to a symbol (e.g. function name, class name, variable name).\nThe response will include all symbols that are referenced from that input symbol.\nFor example, if the position points to a function name, the response will include\nall symbols referenced within that function's implementation.",
        "required": [
          "identifier_position"
        ],
        "properties": {
          "full_scan": {
            "type": "boolean",
            "description": "Whether to use the more permissive rules to find referenced symbols. This will be not just\ncode that is executed but also things like type hints and chained indirection.\nDefaults to false.",
            "example": false
          },
          "identifier_position": {
            "$ref": "#/components/schemas/FilePosition",
            "description": "The identifier position of the symbol to find references within"
          }
        }
      },
      "FindReferencedSymbolsResponse": {
        "type": "object",
        "description": "Response containing symbols referenced from the requested position\n\nThe symbols are categorized into:\n- workspace_symbols: References to symbols that were found and have definitions in the workspace\n- external_symbols: References to symbols from outside the workspace (built-in functions, external libraries)\n- not_found: References where the symbol definition could not be found",
        "required": [
          "workspace_symbols",
          "external_symbols",
          "not_found"
        ],
        "properties": {
          "external_symbols": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Identifier"
            }
          },
          "not_found": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Identifier"
            }
          },
          "workspace_symbols": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ReferenceWithSymbolDefinitions"
            }
          }
        }
      },
      "FindReferencesRequest": {
        "type": "object",
        "required": [
          "identifier_position"
        ],
        "properties": {
          "identifier_position": {
            "$ref": "#/components/schemas/FilePosition"
          },
          "include_code_context_lines": {
            "type": [
              "integer",
              "null"
            ],
            "format": "int32",
            "description": "Whether to include the source code of the symbol in the response.\nDefaults to none.",
            "example": 5,
            "minimum": 0
          },
          "include_raw_response": {
            "type": "boolean",
            "description": "Whether to include the raw response from the langserver in the response.\nDefaults to false.",
            "example": false
          }
        }
      },
      "FindReferencesResponse": {
        "type": "object",
        "description": "Response to a references request.\n\nPoints to the start position of the symbol's identifier.\n\ne.g. for the references of `User` on line 0 character 6 of `src/main.py` with the code:\n```text\n0: class User:\n1:     def __init__(self, name, age):\n2:         self.name = name\n3:         self.age = age\n4:\n5: user = User(\"John\", 30)\n_________^\n6:\n7: print(user.name)\n```\nThe references will be `[{\"path\": \"src/main.py\", \"line\": 5, \"character\": 7}]`.",
        "required": [
          "references",
          "selected_identifier"
        ],
        "properties": {
          "context": {
            "type": [
              "array",
              "null"
            ],
            "items": {
              "$ref": "#/components/schemas/CodeContext"
            },
            "description": "The source code around the references."
          },
          "raw_response": {
            "description": "The raw response from the langserver.\n\nhttps://microsoft.github.io/language-server-protocol/specifications/lsp/3.17/specification/#textDocument_references"
          },
          "references": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/FilePosition"
            }
          },
          "selected_identifier": {
            "$ref": "#/components/schemas/Identifier",
            "description": "The identifier that was \"clicked-on\" to get the references."
          }
        }
      },
      "HealthResponse": {
        "type": "object",
        "description": "Response returned by the health check endpoint",
        "required": [
          "status",
          "version",
          "languages"
        ],
        "properties": {
          "languages": {
            "type": "object",
            "description": "Map of supported languages and whether they are currently available (healthy)",
            "additionalProperties": {
              "type": "boolean"
            },
            "propertyNames": {
              "oneOf": [
                {
                  "type": "string",
                  "enum": [
                    "Python"
                  ]
                },
                {
                  "type": "string",
                  "description": "TypeScript and JavaScript are handled by the same langserver",
                  "enum": [
                    "TypeScriptJavaScript"
                  ]
                },
                {
                  "type": "string",
                  "enum": [
                    "Rust"
                  ]
                },
                {
                  "type": "string",
                  "enum": [
                    "CPP"
                  ]
                },
                {
                  "type": "string",
                  "enum": [
                    "CSharp"
                  ]
                },
                {
                  "type": "string",
                  "enum": [
                    "Java"
                  ]
                },
                {
                  "type": "string",
                  "enum": [
                    "Golang"
                  ]
                },
                {
                  "type": "string",
                  "enum": [
                    "PHP"
                  ]
                },
                {
                  "type": "object",
                  "description": "Ruby with version and optional Sorbet variant",
                  "required": [
                    "Ruby"
                  ],
                  "properties": {
                    "Ruby": {
                      "type": "object",
                      "description": "Ruby with version and optional Sorbet variant",
                      "required": [
                        "version",
                        "variant"
                      ],
                      "properties": {
                        "sorbet_config_dir": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "description": "For Sorbet variant: the directory containing sorbet/config (relative to workspace root)\nThis is used to pass --dir to Sorbet so it can find its config in nested projects\nThis field is runtime-only and not exposed in the API schema"
                        },
                        "variant": {
                          "$ref": "#/components/schemas/LanguageVariant"
                        },
                        "version": {
                          "$ref": "#/components/schemas/LanguageVersion"
                        }
                      }
                    }
                  }
                }
              ],
              "description": "Supported programming languages with optional version information\n\nThis enum represents languages that can be analyzed by the LSP proxy.\nLanguages with version detection (like Ruby) carry version information,\nwhile others use a single unversioned container."
            }
          },
          "status": {
            "type": "string",
            "description": "Current status of the service (\"ok\" or error description)"
          },
          "version": {
            "type": "string",
            "description": "Version of the service"
          }
        }
      },
      "Identifier": {
        "type": "object",
        "required": [
          "name",
          "file_range"
        ],
        "properties": {
          "file_range": {
            "$ref": "#/components/schemas/FileRange"
          },
          "kind": {
            "type": [
              "string",
              "null"
            ]
          },
          "name": {
            "type": "string"
          }
        }
      },
      "LanguageVariant": {
        "type": "string",
        "description": "Language variant for languages that have multiple type system modes\n\nSome languages support different type-checking modes that require different\nlanguage servers or configurations. This enum captures those variants.",
        "enum": [
          "standard",
          "sorbet"
        ]
      },
      "LanguageVersion": {
        "type": "string",
        "description": "Language version string (e.g., \"3.4.4\" for Ruby, \"3.12\" for Python)\n\nThis represents the runtime/compiler version of a language, not the container image version.\nFor languages without version detection, this may be None."
      },
      "Position": {
        "type": "object",
        "description": "A position within a text document, using 0-based indexing",
        "required": [
          "line",
          "character"
        ],
        "properties": {
          "character": {
            "type": "integer",
            "format": "int32",
            "description": "0-indexed character index within the line.",
            "example": 5,
            "minimum": 0
          },
          "line": {
            "type": "integer",
            "format": "int32",
            "description": "0-indexed line number.",
            "example": 10,
            "minimum": 0
          }
        }
      },
      "Range": {
        "type": "object",
        "required": [
          "start",
          "end"
        ],
        "properties": {
          "end": {
            "$ref": "#/components/schemas/Position",
            "description": "The end position of the range."
          },
          "start": {
            "$ref": "#/components/schemas/Position",
            "description": "The start position of the range."
          }
        }
      },
      "ReadSourceCodeRequest": {
        "type": "object",
        "required": [
          "path"
        ],
        "properties": {
          "path": {
            "type": "string",
            "description": "Path to the file, relative to the workspace root",
            "example": "src/main.py"
          },
          "range": {
            "oneOf": [
              {
                "type": "null"
              },
              {
                "$ref": "#/components/schemas/Range",
                "description": "Optional range within the file to read"
              }
            ]
          }
        }
      },
      "ReadSourceCodeResponse": {
        "type": "object",
        "required": [
          "source_code"
        ],
        "properties": {
          "source_code": {
            "type": "string"
          }
        }
      },
      "ReferenceWithSymbolDefinitions": {
        "type": "object",
        "description": "A reference to a symbol along with its definition(s) found in the workspace\n\ne.g. for a reference to `User` in `main.py`:\n```python\nuser = User(\"John\", 30)\n_______^\n```\nThis would contain:\n- The reference location and name (\"User\" at line 0)\n- The symbol definition(s) (e.g. \"class User\" in models.py)",
        "required": [
          "reference",
          "definitions"
        ],
        "properties": {
          "definitions": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Symbol"
            }
          },
          "reference": {
            "$ref": "#/components/schemas/Identifier"
          }
        }
      },
      "SupportedLanguages": {
        "oneOf": [
          {
            "type": "string",
            "enum": [
              "Python"
            ]
          },
          {
            "type": "string",
            "description": "TypeScript and JavaScript are handled by the same langserver",
            "enum": [
              "TypeScriptJavaScript"
            ]
          },
          {
            "type": "string",
            "enum": [
              "Rust"
            ]
          },
          {
            "type": "string",
            "enum": [
              "CPP"
            ]
          },
          {
            "type": "string",
            "enum": [
              "CSharp"
            ]
          },
          {
            "type": "string",
            "enum": [
              "Java"
            ]
          },
          {
            "type": "string",
            "enum": [
              "Golang"
            ]
          },
          {
            "type": "string",
            "enum": [
              "PHP"
            ]
          },
          {
            "type": "object",
            "description": "Ruby with version and optional Sorbet variant",
            "required": [
              "Ruby"
            ],
            "properties": {
              "Ruby": {
                "type": "object",
                "description": "Ruby with version and optional Sorbet variant",
                "required": [
                  "version",
                  "variant"
                ],
                "properties": {
                  "sorbet_config_dir": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "description": "For Sorbet variant: the directory containing sorbet/config (relative to workspace root)\nThis is used to pass --dir to Sorbet so it can find its config in nested projects\nThis field is runtime-only and not exposed in the API schema"
                  },
                  "variant": {
                    "$ref": "#/components/schemas/LanguageVariant"
                  },
                  "version": {
                    "$ref": "#/components/schemas/LanguageVersion"
                  }
                }
              }
            }
          }
        ],
        "description": "Supported programming languages with optional version information\n\nThis enum represents languages that can be analyzed by the LSP proxy.\nLanguages with version detection (like Ruby) carry version information,\nwhile others use a single unversioned container."
      },
      "Symbol": {
        "type": "object",
        "required": [
          "name",
          "kind",
          "identifier_position",
          "file_range"
        ],
        "properties": {
          "file_range": {
            "$ref": "#/components/schemas/FileRange",
            "description": "The full range of the symbol."
          },
          "identifier_position": {
            "$ref": "#/components/schemas/FilePosition",
            "description": "The start position of the symbol's identifier."
          },
          "kind": {
            "type": "string",
            "description": "The kind of the symbol (e.g., function, class).",
            "example": "class"
          },
          "name": {
            "type": "string",
            "description": "The name of the symbol.",
            "example": "User"
          }
        }
      }
    },
    "securitySchemes": {
      "bearer_auth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "JWT"
      }
    }
  },
  "security": [
    {
      "bearer_auth": []
    }
  ],
  "tags": [
    {
      "name": "nuanced-lsp-api",
      "description": "Nuanced LSP API"
    }
  ]
}