# ycmd

Version: 0.3.0, ycmd GitHub page

ycmd is a code-completion & code-comprehension server.

ycmd presents a JSON/REST interface to clients over HTTP, validated by HMAC. An instance of ycmd is started for each client application.

## General Notes

The REST interface typically uses HTTP POST requests and expects the payload data to be a valid JSON document. The following general principles are applied:

- All strings going into and out of the server are UTF-8 encoded.
- All lines end with `\n`.
- All line and column numbers are 1-based, not 0-based. They are also byte offsets, not Unicode codepoint offsets.
- All file paths are full, absolute paths. If a file has not been written to disk yet, supply a temporary path.
- All requests to the server must include an HMAC in the x-ycm-hmac HTTP header.
- All responses from the server must be validated using the x-ycm-hmac header.

## The example client

ycmd contains a simple example client in the `example` directory of the source tree. It is written in pure Python with only minimal dependencies. It contains trivial implementations of most endpoints and serves to supplement this API documentation.

Consult `example/README.md` for instructions on getting it running.

## Starting the server

The ycmd server is typically started by a client in order to provide services to it. Briefly, starting the server requires supplying some configuration and initializing some security features (HMAC).

The server should be started with a supported version of Python.

The full list of command line options can be obtained by passing `--help` to ycmd (e.g. `python -m ycmd --help`). However, the following options warrant further discussion:

### `--options_file`

This mandatory option supplies the name of a file containing user options data. This option (and thus the file) are mandatory, as they are required to set the shared HMAC secret.

Once the server has read the options, the server deletes the options file. Therefore, the client should typically create a secure temporary file (e.g. `mkstemp`) which contains the options to be used.

The default options and their values are found in `default_settings.json` within the ycmd codebase.

The file contains a JSON-formatted object, where the keys are the names of options (with any `ycm_` prefix removed) and the values are the option values.

The canonical list of supported user options can be found in YouCompleteMe's `README.md`. The option values should have the `ycm_` prefix removed.

The following additional options are required to be set by the client application and should not be visible to the user:

- `hmac_secret`: The shared secret for HMAC authentication. This should be 16 bytes of random data with as much entropy as possible, encoded as a base-64 UTF-8 string. Code for generating this in Python can be found in the ycmd example client.

## HMAC

All requests to the server must include an HMAC in the x-ycm-hmac HTTP header. The HMAC is computed from the shared secret passed to the server on startup and the request/response body. The digest algorithm is SHA-256. The server will also include the HMAC in its responses; you must verify it before using the response. See the example client to see how it's done.

## Filetypes

ycmd uses `filetypes` to identify the "language" of a given buffer. These filetype values are strictly the values understood by Vim. Please see the YCM README.md for the list of filetypes recognized by ycmd for semantic completion.

Schemes:

## Summary

Path | Operation | Description
--- | --- | ---
/completions | POST | Get completion suggestions for the current file context.
/debug_info | POST | Return server and semantic engine debug information.
/defined_subcommands | POST | Get the list of subcommands which are available for a completer.
/detailed_diagnostic | POST | Get additional information about diagnostic under cursor.
/event_notification | POST | Notify the server of various client events.
/filter_and_sort_candidates | POST | Filter and sort a set of candidates using ycmd's fuzzy matching.
/healthy | GET | Check if the server is healthy.
/ignore_extra_conf_file | POST | Forcefully ignore the config for the current buffer.
/inlay_hints | POST | Compute inlay hints for a range
/load_extra_conf_file | POST | Forcefully load the config for the current buffer.
/ready | GET | Check if the server is ready.
/receive_messages | POST | Long poll for asynchronous server messages.
/resolve_completion | POST | Resolve detailed_info for a completion item
/resolve_fixit | POST | Resolve an incomplete FixIt.
/run_completer_command | POST | Run a semantic completer subcommand.
/semantic_completion_available | POST | Determine if semantic completion is available for current buffer.
/semantic_tokens | POST | Compute semantic tokens for a range, or the whole document
/shutdown | POST | Request ycmd to shut down.
/signature_help | POST | Get signature help (argument hints) for current file context.
/signature_help_available | GET | Is /signature_help supported for some filetype

## Paths

Get completion suggestions for the current file context.

### POST /completions

Returns the autocompletion suggestions for the current cursor position. Typically, the server determines whether or not to use semantic completion or general (i.e. identifier-based) completion based on the language (filetype) and the context. Clients can force the use of semantic completion by setting the `force_semantic` property to `true`.

Note that if `force_semantic` is not set to `true` and the completion engine returns an error, the server still tries to fall back to general completion, so this endpoint will typically always return successfully. Any semantic completer error raised is included in the response to be dealt with by the client.

When `force_semantic` is `true`, any error returned by the semantic engine is returned via a 500 response.

The context data, including the current cursor position, and details of dirty buffers.

SimpleRequest

application/json

200 OK

  The list of completion suggestions.

  CompletionResponse
500 Internal Server Error

  An error occurred.

  ExceptionResponse

Return server and semantic engine debug information.

### POST /debug_info

Returns debugging information about the server itself and the semantic completer for the current buffer (if there is one).

This data includes things like the versions of linked-in libraries, log file locations, etc.

The context data, including the current cursor position, and details of dirty buffers.

SimpleRequest

application/json

200 OK

  A dictionary of debugging information.

  Example for application/json

      {
          "clang": {
              "has_support": true,
              "version": "clang version"
          },
          "completer": {
              "items": [
                  {
                      "description": "description",
                      "value": "value"
                  }
              ],
              "name": "completer name",
              "servers": [
                  {
                      "address": "127.0.0.1",
                      "executable": "/path/to/executable",
                      "extras": [
                          {
                              "description": "description"
                          },
                          {
                              "value": "value"
                          }
                      ],
                      "is_running": true,
                      "logfiles": [
                          "/path/to/stdout/logfile",
                          "/path/to/stderr/logfile"
                      ],
                      "name": "server name",
                      "pid": 12345,
                      "port": 1234
                  }
              ]
          },
          "extra_conf": {
              "is_loaded": false,
              "path": "/path/to/extra/conf"
          },
          "python": {
              "executable": "/path/to/python/interpreter",
              "version": "python version"
          }
      }

  python: object

    Debugging information on the Python interpreter in which the server is running.

    executable: string

      Python interpreter path.

    version: string

      Python interpreter version.

  clang: object

    Debugging information on Clang.

    has_support: boolean

      `true` if the ycmd server was built with Clang support, `false` otherwise.

    version: string

      if `has_support` is `true`, return the version of Clang. Otherwise, return `null`.

  extra_conf: object

    Debugging information on the extra configuration file for the current buffer.

    path: string

      Path of the found extra configuration file, loaded or not.

    is_loaded: boolean

      `true` if the extra configuration file is loaded, `false` otherwise.

  completer: DebugInfoResponse

    Contains debugging information on the completer for the given filetypes. `null` if no completer is available.

500 Internal Server Error

  An error occurred.

  ExceptionResponse

Get the list of subcommands which are available for a completer.

### POST /defined_subcommands

Returns the list of completer subcommands for a given completer.

See also: `/run_completer_command`

The context data, including the current cursor position, and details of dirty buffers.

SimpleRequest

application/json

200 OK

  The list of available subcommands.

  string
500 Internal Server Error

  An error occurred

  ExceptionResponse

Get additional information about diagnostic under cursor.

### POST /detailed_diagnostic

Where available returns addition information about the diagnostic, such as the full text of the compile error, suggestions, etc.

Typically, details are returned for the diagnostic nearest to the current cursor position.

The context data, including the current cursor position, and details of dirty buffers.

SimpleRequest

application/json

200 OK

  The detailed diagnostic

  message: string
500 Internal Server Error

  An error occurred, or no diagnostic was available

  ExceptionResponse

Notify the server of various client events.

### POST /event_notification

The server needs to react to a number of client events in order to provide things like diagnostics and to handle downstream server states etc. The client must inform the server of the following events, populating the event name in the `event_name` property:

- `FileReadyToParse` Call when a new buffer is opened or after the user has stopped typing for some time, or at any other time when the client believes that it is worthwhile reparsing the current file and updating semantic engines' ASTs and reporting things like updated diagnostics.
- `BufferUnload` Call when the user closes a buffer that was previously known to be open. Closing buffers is important to limit resource usage.
- `BufferVisit` (optional) Call when the user focuses on a buffer that is already known. Note: The `ultisnips_snippets` property is optional when firing calling this event. Otherwise it is ignored.
- `InsertLeave` (optional) For modal editors, call when exiting insert mode. It is equivalent to `CurrentIdentifierFinished`.
- `CurrentIdentifierFinished` (optional) Call when the user finishes typing what appears to the client to be an identifier.
- `FileSave` Call when the user writes to a file on disk. (optional)

The notification data. The line and column are typically not used, but the `filepath` and file data properties are used to perform semantic analysis (e.g. in the `FileReadyToParse` handler).

    {
        "column_num": 20,
        "event_name": "FileReadyToParse",
        "file_data": {
            "/home/test/dev/test.cc": {
                "contents": "<file contents>",
                "filetypes": [
                    "cpp"
                ]
            }
        },
        "filepath": "/home/test/dev/test.js",
        "line_num": 10
    }

line_num: LineNumber
column_num: ColumnNumber
filepath: FilePath
file_data: FileDataMap
completer_target: CompleterTarget
working_dir: WorkingDirectory
extra_conf_data: ExtraConfData
event_name: string , x ∈ { FileReadyToParse , BufferUnload , BufferVisit , InsertLeave , CurrentIdentifierFinished }

  The event that occurred.

ultisnips_snippets: object[]
  object

  Optional when `event_name` is BufferVisit Supplies the ultisips snippets known for the current filetypes. Can be used to supply any other type of additional completion suggestions generated by the client.

  trigger: string

    The text to insert in order to trigger the snippet. When supplying non-ultisnips suggestions, this is the text to be inserted.

  description: string

    Additional text to display in the completion menu, such as a summary of the snippet to be inserted.

application/json

200 OK

  Optional set of diagnostics for the current buffer.

  DiagnosticResponse
500 Internal Server Error

  An error occurred.

  ExceptionResponse

Filter and sort a set of candidates using ycmd's fuzzy matching.

### POST /filter_and_sort_candidates

For filetypes not natively supported by ycmd, clients can often determine a set of suitable candidate completion suggestions by other means. In Vim this is typically from the `omnifunc` and other clients will have equivalents.

This endpoint allows clients to use ycmd's powerful filtering and ranking capabilities (including longest-common-subsequence and word-boundary-character ranking) on arbitrary sets of identifiers.

NOTE: This API is primarily intended for use when subclassing the `Completer` class outside of ycmd which is a very niche case, specific to the `OmniCompleter` in the Vim client. It is not expected that this API be used elsewhere.

The set of candidates to sort of the query parameters.

NOTE: This `request_data` object is different from most other ycmd requests as it does not contain buffer data or cursor locations.

candidates: object[]

  The candidates to filter and sort

  Candidate
sort_property: string , x ∈ { word , insertion_text }

  Typically set to `insertion_text`, but can be set to `word` when the candidates are in the form of a simple list of words. In the latter case, `candidates` must be a list of strings.

query: string

  The text the user has typed so far for the current identifier. This is to filter against the suggestions in `candidates`.

application/json

200 OK

  The filtered list of candidated

  Candidate
500 Internal Server Error

  An error occurred

  ExceptionResponse

Check if the server is healthy.

### GET /healthy

Return `true` if the server is healthy, `false` otherwise. The client should use this endpoint to keep the server alive.

application/json

200 OK

  Server is healthy.

  AlwaysYes
500 Internal Server Error

  An error occurred.

  ExceptionResponse

Forcefully ignore the config for the current buffer.

### POST /ignore_extra_conf_file

As opposed to `/load_extra_conf_file`, this API endpoint must be called when the user declines to load the associated `.ycm_extra_conf.py` file.

The context data, including the current cursor position, and details of dirty buffers.

SimpleRequest

application/json

200 OK

  Configuration file ignored.

  AlwaysYes
500 Internal Server Error

  An error occurred ignoring the configuration file.

  ExceptionResponse

Compute inlay hints for a range

### POST /inlay_hints

Compute and return inlay hints for a document range.

The context data, including the current cursor position, and details of dirty buffers.

filepath: FilePath
file_data: FileDataMap
range: Range

200 OK

  Hints created, or not supported (emtpy list)

  inlay_hints: object[]
    InlayHint
  errors: object[]
    Exception
500 Internal Server Error

  An error occurred

  ExceptionResponse

Forcefully load the config for the current buffer.

### POST /load_extra_conf_file

By default, ycmd will not load `.ycm_extra_conf.py` files for security reasons and instead raises an exception the first time it requires loading.

In the case that exception is raised, the client should call this API endpoint after confirming with the user that it is safe to load the reported `.ycm_extra_conf.py` file.

The context data, including the current cursor position, and details of dirty buffers.

SimpleRequest

application/json

200 OK

  Configuration file loaded.

  AlwaysYes
500 Internal Server Error

  An error occurred loading the configuration file.

  ExceptionResponse

Check if the server is ready.

### GET /ready

Return `true` if the (sub)server is ready, `false` otherwise. The client should use this endpoint to keep the server alive.

subserver | Subserver filetype for which the request is made. If a subserver supports multiple filetypes, the parameter may hold any one of them. | query | string |

application/json

200 OK

  Server is ready.

  YesNo

Long poll for asynchronous server messages.

### POST /receive_messages

Return asynchronous messages from the server. This request is used by clients in a "long poll" style, and does not return until either:

- A message (or messages) becomes available, in which case a list of messages is returned, or
- a timeout occurs (after 60s), in which case `true` is returned and the client should re-send this request, or
- for some reason the server determined that the client should stop sending `receive_messages` requests, in which case `false` is returned, and the client should only send the request again when something substantial changes such as a new file type is opened, or the completer server is manually restarted.

The following types of event are delivered asynchronously for certain filetypes:

- Status messages to be displayed unobtrusively to the user.
- Diagnostics (for Java only).

This message is optional. Clients do not require to implement this method, but it is strongly recommended for certain languages to offer the best user experience.

The context data, including the current cursor position, and details of dirty buffers.

SimpleRequest

application/json

200 OK

  Messages are ready, the request timed out, or the request is not supported and should not be retried.

  The response may be one of `MessagePollResponse` or `MessagesList`.

  Example for application/json

      [
          {
              "message": "Initializing: 19% complete"
          },
          {
              "message": "Initializing: Done."
          },
          {
              "diagonostics": {
                  "diagnostics": [
                      {
                          "fixit_available": false,
                          "kind": "WARNING",
                          "location": {
                              "column_num": 11,
                              "filepath": "/file",
                              "line_num": 10
                          },
                          "location_extent": {
                              "end": {
                                  "column_num": 11,
                                  "filepath": "/file",
                                  "line_num": 10
                              },
                              "start": {
                                  "column_num": 11,
                                  "filepath": "/file",
                                  "line_num": 10
                              }
                          },
                          "ranges": [
                              {
                                  "end": {
                                      "column_num": 20,
                                      "filepath": "/file",
                                      "line_num": 10
                                  },
                                  "start": {
                                      "column_num": 11,
                                      "filepath": "/file",
                                      "line_num": 10
                                  }
                              }
                          ],
                          "text": "Very naughty code!"
                      },
                      {
                          "fixit_available": true,
                          "kind": "ERROR",
                          "location": {
                              "column_num": 11,
                              "filepath": "/file",
                              "line_num": 19
                          },
                          "location_extent": {
                              "end": {
                                  "column_num": 11,
                                  "filepath": "/file",
                                  "line_num": 19
                              },
                              "start": {
                                  "column_num": 11,
                                  "filepath": "/file",
                                  "line_num": 19
                              }
                          },
                          "ranges": [
                              {
                                  "end": {
                                      "column_num": 20,
                                      "filepath": "/file",
                                      "line_num": 19
                                  },
                                  "start": {
                                      "column_num": 11,
                                      "filepath": "/file",
                                      "line_num": 19
                                  }
                              }
                          ],
                          "text": "Very dangerous code!"
                      }
                  ],
                  "filepath": "/file"
              }
          }
      ]

  MessagePollResponse MessageList
500 Internal Server Error

  An error occurred.

  ExceptionResponse

Resolve detailed_info for a completion item

### POST /resolve_completion

Given the `resolve` ID for a completion item, returns the item with additional data filled in.

Note, the supplied `request_data` must match exactly the `request_data` for the corresponding completion request, except with the `resolve` key filled in with the `resolve` ID from the completion item's `extra_data`.

The context data, including the current cursor position, and details of dirty buffers.

line_num: LineNumber
column_num: ColumnNumber
filepath: FilePath
file_data: FileDataMap
completer_target: CompleterTarget
working_dir: WorkingDirectory
extra_conf_data: ExtraConfData
resolve: object

  The 'resolve' key from the 'extra_data' in the completion item to resolve.

application/json

200 OK

  The list of completion suggestions.

  ResolveCompletionResponse
500 Internal Server Error

  An error occurred.

  ExceptionResponse

Resolve an incomplete FixIt.

### POST /resolve_fixit

Resolves an incomplete fixit, indicated by `'resolve'` fixit property. Some completers return incomplete fixits in order to avoid blocking on expensive fixit calculations.

When a client wishes to resolve a fixit, the entire `FixIt` object should be sent in the `fixit` property.

If a client tries to resolve an already resolved fixit, the same fixit is returned in a SubcommandResponse.

The context data, including the current cursor position, and details of dirty buffers.

    {
        "file_data": {
            "/home/test/dev/test.c": {
                "contents": "<file contents>",
                "filetypes": [
                    "c"
                ]
            }
        },
        "filepath": "/home/test/dev/test.c",
        "fixit": {
            "$ref": "#/definitions/UnresolvedFixIt"
        }
    }

filepath: FilePath
file_data: FileDataMap
fixit: FixIt

200 OK

  The fixit has been resolved and a FixIt response is returned.

  SubcommandResponse
500 Internal Server Error

  An error occurred

  ExceptionResponse

Run a semantic completer subcommand.

### POST /run_completer_command

Semantic completers offer additional engine-specific commands, known as completer subcommands. This endpoint requests a specific command to be executed. Typically the "default" semantic completer for the current filetype is used, but it is possible to force the use of a particular completer, using the `completer_target` property.

The command to execute is passed as a list of arguments, the first of which is the command name followed by any command- and completer-specific additional arguments. This "command line" is passed in the `command_arguments` property.

The list of available subcommands for a particular semantic completer can be queried using the `/defined_subcommands` endpoint.

Subcommands may return one of a number of actions, depending on the type of command. The following types of response are returned:

- A simple display message response. This is identified where the type of the response is scalar (i.e. boolean, number, string) or the type of the response is an object with a `message` property. These messages are typically only a single line and can be displayed in a message-box or similarly echoed in a status bar or equivalent.
- A FixIt response. This is identified where the type of the response is an object with a property named `fixits`.
- A detailed information response. This is identified where the type of the response is an object with a `detailed_info` property. These messages are typically multiple lines (such as the documentation and signature for a method) and are best displayed in a panel or preview area (or equivalent).
- A Hierarchy response. This is identified where the type of the response is a list of objects containing `kind` and `locations` properties. Hierarchy requests work similarly to those in the LSP specification. If a completer supports call/type hierarchies, the initial request should be sent through `TypeHierarchy`/`CallHierarchy` subcommand. Resolving any item in the hierarchy tree is done by subsequent `ResolveCallHierarchyItem` and `ResolveTypeHierarchyItem` requests. When resolving a hierarchy item, the arguments following the subcommand name are the item being resolved and the direction in which the item should be resolved. For call hierarchies, the directions are `incoming` and `outgoing`. For type hierarchies, the directions are `subtypes` and `supertypes`. Note that, except for the root node of the hierarchy, resolving an item in both directions is discouraged.
- A GoTo response. This is identified where the response type cannot be determined by any of the above methods. A GoTo response may contain either a single location (e.g. for `GoToDeclaration`), or a list of possible locations for the user to chose from (such as in a `GoToReferences` subcommand).

The context data, including the current cursor position, and details of dirty buffers.

    {
        "column_num": 20,
        "command_arguments": [
            "RefactorRename",
            "Testing"
        ],
        "completer_target": "filetype_default",
        "file_data": {
            "/home/test/dev/test.js": {
                "contents": "<file contents>",
                "filetypes": [
                    "javascript"
                ]
            }
        },
        "filepath": "/home/test/dev/test.js",
        "line_num": 10,
        "options": {
            "insert_spaces": true,
            "tab_size": 4
        }
    }

line_num: LineNumber
column_num: ColumnNumber
filepath: FilePath
file_data: FileDataMap
completer_target: CompleterTarget
working_dir: WorkingDirectory
extra_conf_data: ExtraConfData
command_arguments: string[]

  The command line to execute as a list of arguments. The first such argument is the subcommand to execute (for example: `GoTo`).

  string
range: Range

  The range to which the command is applied (only used by the Format command).

options: object

  A set of editor-related options for the current buffer (only used by the Format command).

  tab_size: integer

    The size of a tabulation in spaces.

  insert_spaces: boolean

    Use spaces to represent tabulations.

application/json

200 OK

  Optional action or display text in response to the request.

  NOTE: If the type of the response is not an object or list, then the response is a simple display message.

  NOTE: If the type of the response is a list, then the response is a GoTo list (e.g. quick-fix list or equivalent) and the items in the list are of type `GoToLocations` (see definitions).

  SubcommandResponse
500 Internal Server Error

  An error occurred.

  ExceptionResponse

Determine if semantic completion is available for current buffer.

### POST /semantic_completion_available

The context data, including the current cursor position, and details of dirty buffers.

SimpleRequest

application/json

200 OK

  Whether or not semantic completion is available.

  YesNo
500 Internal Server Error

  An error occurred

  ExceptionResponse

Compute semantic tokens for a range, or the whole document

### POST /semantic_tokens

Compute and return semantic tokens

The context data, including the current cursor position, and details of dirty buffers.

filepath: FilePath
file_data: FileDataMap
range: Range

200 OK

  Hints created, or not supported (emtpy list)

  semantic_tokens: object
    tokens: SemanticToken
  errors: object[]
    Exception
500 Internal Server Error

  An error occurred

  ExceptionResponse

Request ycmd to shut down.

### POST /shutdown

200 OK
  AlwaysYes

Get signature help (argument hints) for current file context.

### POST /signature_help

Returns a list of method signatures relevant to the current cursor position, along with an indication of which signature and argument are 'active'.

Only returned by semantic engines.

Signatures are actually queried immediately after a trigger character. The result of this is that the client and server collude on remembering the current "trigger" state for signature help. This trades off some complexity in clients for significant performance benefits in the general case.

The client is responsible for maintaining the state of any displayed signature help popup, and is responsible for hiding it when this request returns an empty set of signatures.

That is, when this request returns a non-empty list of signatures, signature help is considered "triggered' and the client must record this and return it in the 'signature_help_state' request field (value `ACTIVE`). The client continues to request signature help on new input and should update its state to `INACTIVE` whenever this request returns an empty list of signatures.

If any errors are reported by the semantic engine, they are reported in the `errors` key in the response.

The first signature and the first argument are both 0.

The context data, including the current cursor position, and details of dirty buffers.

line_num: LineNumber
column_num: ColumnNumber
filepath: FilePath
file_data: FileDataMap
completer_target: CompleterTarget
extra_conf_data: ExtraConfData
signature_help_state: string , x ∈ { ACTIVE , INACTIVE }

  The current state of the signature help triggering. After signatures are returned for the first time (triggered), the client sends further requests with `signature_help_state` set to `ACTIVE` until the request returns no signatures.

application/json

200 OK

  Signature info.

  errors: object[]

    errors reported by the semantic completion engine.

    ExceptionResponse
  signature_help: object
    activeSignature: number

      The active signature. The first is 0.

    activeParameter: number

      The active parameter. The first is 0.

    signatures: object[]

      The list of signatures

      object
      label: string

        The full signature text, including parameters

      documentation: string

        Human readable docstring of the signature.

      parameters: object[]

        List of parameters

        object
        documentation: string

          Human readable docstring of the parameter.

        label: integer[]

          The array of offsets representing an inclusive start and exclusive end within the parameter's containing signature label.

          Offsets are byte offsets into the UTF8 encoded string 'label'

          integer
500 Internal Server Error

  An error occurred.

  ExceptionResponse

Is /signature_help supported for some filetype

### GET /signature_help_available

Since /signature_help can be expensive, clients can query ycmd with /signature_help_available and then stop sending /signature_help if there is no support for that filetype.

If the response is PENDING, the client should make another /signature_help_available request later.

subserver | Subserver filetype for which the request is made. If a subserver supports multiple filetypes, the parameter may hold any one of them. | query | string |

application/json

200 OK

  Signature help support info.

  available: string , x ∈ { YES , NO , PENDING }
500 Internal Server Error

  An error occurred.

  ExceptionResponse

## Schema definitions

### AlwaysYes: boolean

`true` is always returned, unless there is an error.

### Candidate: object

insertion_text: string

  The word to insert when selecting the completion.

  Equivalent of the Vim `complete-items` entry: `word`.

menu_text: string

  The word to display as the suggestion to the user. If not supplied, `insertion_text` is displayed to the user.

  Equivalent of the Vim `complete-items` entry: `abbr`.

extra_menu_info: string

  Additional information to display about the suggestion within the completion menu (or equivalent). Typically this is the signature/declaration of the item being suggested, or some additional free-text qualifiers (such as `[File]` etc.). These are a single line and typically short. For more detailed information, such as usage and docs, see `detailed_info`.

  Equivalent of the Vim `complete-items` entry: `menu`.

detailed_info: string

  Additional information, such as the full signature and method documentation, suitable for display in a preview window or tooltip.

  Equivalent of the Vim `complete-items` entry: `info`.

kind: string

  An indicator of the type of suggestion. Only the first character of `kind` should be displayed.

  Equivalent of the Vim `complete-items` entry: `kind`.

extra_data: object

  Completer-specific additional information.

  doc_string: string

    Additional documentation/information to be displayed alongside (after) information in `detailed_info`.

  fixits: object[]

    Any editional edits to apply when selecting this completion

    FixIt
  resolve: number

    Identifier used to resolve this completion item using /resolve_completion. If not supplied, the item is already fully resolved.

### ColumnNumber: integer

1-based column byte offset within the line.

### CompleterTarget: string

The completer implementation for which the command is intended. Typically, this is set to `filetype_default`, but may also take any of the following values:

- `filetype_default` Use the semantic completer associated with the filetype of the current buffer. This is the default when a target is not supplied.
- `identifier` Use the identifier completer.
- Any filetype Use the completer associated with the supplied filetype.

### CompletionResponse: object

completions: object[]

  List of completion suggestions.

  Candidate
completion_start_column: integer

  1-based byte index of the column from which the completion should be applied. This is the column in which the words suggested in `completions` should be placed.

errors: object[]

  Any errors reported by the semantic completion engine.

  ExceptionResponse

### DebugInfoResponse: object

name: string

  The completer name.

servers: object[]

  A list of servers used by the completer.

  ServerData
items: object[]

  Additional debugging information.

  ItemData

### DiagnosticData: object

- `location` The source location where the diagnostic applies. This is typically (but not always) the start of `location_extent`.
- `location_extent` The source range to which the diagnostic applies. This differs from the `location` in that it refers to the whole range. Typically this is used to underline, or otherwise render as "error" the source code which caused the diagnostic.

ranges: object[]

  List of ranges to which this diagnostic applies. These ranges typically identify the source locations which should be "highlighted" as incorrect.

  Range
location: Location
location_extent: Range
text: string

  The diagnostic text (e.g. error message)

kind: string , x ∈ { WARNING , ERROR , INFORMATION , HINT }

  The type of diagnostic being reported. Typically semantic engines will differentiate between warnings and fatal errors. Informational and hint messages should be treated as warnings where the client does not differentiate.

fixit_available: boolean

  If set to true, indicates that a quick fix action (FixIt) is available for this diagnostic. Typically this is used to indicate to the user that the `FixIt` subcommand is available.

### DiagnosticResponse: object[]

DiagnosticData

### DiagnosticsMessage: object

Diagnostics for a particular file. Note: diagnostics may be supplied for any arbitrary file. The client is responsible for displaying the diagnostics in an appropriate manner. The server supplies an empty set of diagnostics to clear the diagnostics for a particular file.

filepath: FilePath
diagnostics: object[]
  DiagnosticData

### Exception: object

JSON-encoded representation of a Python Exception object.

object

### ExceptionResponse: object

The server raised an exception processing the request. This response is often returned when the server is unable to perform the requested action, not due to a bug or other error, but because it is not possible to do so. For example, it is common for an exception response to be returned when requesting "GoToDefinition" on an identifier for which the semantic, engine is unable to find such a definition.

exception: Exception
message: string

  The exception message. Typically a single line and suitable for display to a user.

traceback: string

  A detailed report of the ycmd call stack at the point the exception was thrown. It is typically not required to display this to a user, as ycmd will print all exceptions to its log file (standard error).

### ExtraConfData: object

A dictionary passed to the `Settings( **kwargs )` function of the `.ycm_extra_conf.py` file under the `client_data` key of `kwargs`. This optional field should be used to give users a way to customize the `.ycm_extra_conf.py` file with their own set of options.

### FileData: object

Contents and details of a dirty buffer.

filetypes: string[]
  string
contents: string

  The entire contents of the buffer encoded as UTF-8.

### FileDataMap: object

An object mapping whose keys are the absolute paths to the files and whose values are data relating unsaved buffers.

An unsaved buffer is any file that is opened in the editor and has been changed without saving the contents to disk.

The file referred to in the request `filepath` entry must always be included. For most requests this is the user's current buffer, but may be any buffer (e.g. in the case of closing a buffer which is not current).

When a file is closed in the editor, a `BufferUnload` event should be sent and the file should not be included in further `FileDataMap` entries until (or unless) it is opened and changed again.

FileData

### FilePath: string

Absolute path to the file in the filesystem. If the file does not yet exist (for example, a new file), then the value should be an arbitrary unique string.

### FixIt: object

text: string

  The diagnostic text or a description of the modification to be made. This is the text displayed to the user when selecting from multiple available FixIts.

location: Location
resolve: boolean

  Indicates whether the fixit requires additional processing.

kind: string

  FixIt kind is meant to suggest what sort of fixit this is. Clients are free to ignore this property or use it to decide whether to automatically apply the fixit. SUpported values are those of LSP. Search for `namespace CodeActionKind` in the following link https://microsoft.github.io/language-server-protocol/specifications/specification-3-15/#textDocument_codeAction

chunks: object[]

  A list of ranges and replacements which must be applied to source files. NOTE: The source ranges may span arbitrary files and the sequence of `chunks` is not defined.

  object
  replacement_text: string

    The text with which to replace the range identified by `range`.

  range: Range

### Hierarchy: object

An object returned, in a list, as a response to hierarchy requests. The object may contain additional properties, which are used to identify the hierarchy tree node, by the subservers.

kind: string , x ∈ { File , Module , Namespace , Package , Class , Method , Property , Field , Constructor , Enum , Interface , Function , Variable , Constant , String , Number , Boolean , Array , Object , Key , , EnumMember , Struct , Event , Operator , TypeParameter }
locations: object[]
  #/defintions/Location
name: string

  The name of the symbol represented by the hierarchy item.

root_location: Location

  In call hierarchies, it is useful to differentiate between the call site (which end up in the `locations` property) and the calling function. This property, if present, represents the latter.

### InlayHint: object

An inlay hint to be rendered in the docuemnt body but not part of the text. Includes optional padding before and after and a kind, which is one of the LSP or tsserver kinds.

kind: string , x ∈ { Unknown , Type , Parameter , Enum }
position: Location
label: string

  Text to display

paddingLeft: boolean
paddingRight: boolean

### ItemData: object

key: string
value: string

### LineNumber: integer

1-based line number.

### Location: object

A contiguous range of bytes in a source buffer starting at `start` and finishing at `end`. The range is (effectively) exclusive. That is if start points to (10,1) and end points to (10,3), then the length of the range is 2 characters.

line_num: LineNumber
column_num: ColumnNumber
filepath: FilePath

### Message: object

An object containing a single asynchronous message. It is either a `SimpleDisplayMessage` or a `DiagnosticsMessage`

message: SimpleDisplayMessage

  If present, this object is a `SimpleDisplayMessage`

diagnostics: DiagnosticsMessage

  If present, this object is a `DiagnosticsMessage`

### MessageList: object[]

A list of messages in the sequence they should be handled.

The type of message in each item is determined by the property name:

- An object with a property `message` is a simple display message where the property value is the message.
- An object with a property `diagnostics` contains diagnostics for a project file. The value of the property is described below.

Message

### MessagePollResponse: boolean

When `true` is returned, the request timed out (meaning no messages were returned in the poll period). Clients should send another `receive_messages` request immediately.

When `false` is returned, the server determined that message polling should abort for the current file type context. Clients should not re-send this request until the filetype being edited changes or the server is restarted.

### Range: object

A contiguous range of bytes in a source buffer.

start: Location
end: Location

### ResolveCompletionResponse: object

completion: Candidate
errors: object[]

  Any errors reported by the semantic completion engine.

  ExceptionResponse

### SemanticToken: object

A item describing the type of token covered by the supplied range.

range: Range
type: string

  One of the token types supported by LSP, or custom ones provided by the semantic engine. Should be mapped to some syntax group understood by the client.

modifiers: object[]

  List of token modifiers, provided by the sematnic engine

  object

### ServerData: object

name: string

  The server name.

is_running: boolean

  `true` if the server is running, `false` otherwise.

executable: string

  The executable path used to start the server.

address: string

  The address on which the server is listening. `null` if not applicable.

port: integer

  The port on which the server is listening. `null` if not applicable.

pid: integer

  The process identifier of the server. `null` if the server is not running.

logfiles: string[]

  A list of logging files used by the server.

  string

  A logging file path.

extras: object[]
  ItemData

### SimpleDisplayMessage: string

A message for display to the user. Note: the message should be displayed discreetly (such as in a status bar) and should not block the user or interrupt them.

### SimpleRequest: object

line_num: LineNumber
column_num: ColumnNumber
filepath: FilePath
file_data: FileDataMap
completer_target: CompleterTarget
working_dir: WorkingDirectory
extra_conf_data: ExtraConfData

### SubcommandResponse: object

fixits: object[]

  If present, this is a FixIt or Refactor response and the value of this property is a list of potential changes to buffers to apply the quick fix or refactoring operation.

  An empty `fixits` list means that no FixIt or refactoring was available. If multiple entries are supplied, the user is prompted to select which one to apply.

  FixIt
message: string

  If present, this is a simple display message and the value of this property is the message to display.

detailed_info: string

  If present, this is a detailed information response and the value of this property is the multi-line information to display as unformatted plain text.

filepath: string

  If present, this is a single GoTo response and this value contains the absolute path of the buffer containing the target location (identified in `line_num` and `column_num`).

kind: string

  If present, this is a Hierarchy response and this value describes the kind of symbol a node in the call/type hierarchy tree is referring to.

locations: object[]

  If present, this is a Hierarchy response and this value contains a list of locations that a node in the call/type hierarchy tree is referring to.

line_num: LineNumber
column_num: ColumnNumber
file_only: boolean

  If present, the line_num and column_num can be ignored.

extra_data: object

  Additional data specific to the response type. For GoTo requests, this may include "kind" and "name" to specify additional data about the GoTo target when doing a symbol search, such as GoToSymbol or GoToDocumentOutline. If supplied, "kind" is a LSP symbol kind.

### UnresolvedFixIt: object

resolve: boolean

  Indicates whether the fixit requires additional processing.

### WorkingDirectory: string

Absolute path to the filesystem working directory of the client. This is used by completer engines to determine things like the project root for the file being modified, amongst other things.

### YesNo: boolean

Result of the query: `true` if yes, `false` otherwise.