Version: 0.1.0
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.
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:
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.
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_fileThis 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.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.
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.
| 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. |
| /load_extra_conf_file | POST |
Forcefully load the config for the current buffer. |
| /receive_messages | POST |
Long poll for asynchronous server messages. |
| /run_completer_command | POST |
Run a semantic completer subcommand. |
| /semantic_completer_available | POST |
Determine if semantic completion is available for current buffer. |
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.
application/json
The list of completion suggestions.
An error occurred.
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.
application/json
A dictionary of debugging information.
{
"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"
}
}
Debugging information on the Python interpreter in which the server is running.
Python interpreter path.
Python interpreter version.
Debugging information on Clang.
true if the ycmd server was built with Clang support,
false otherwise.
if has_support is true, return the version of Clang.
Otherwise, return null.
Debugging information on the extra configuration file for the current buffer.
Path of the found extra configuration file, loaded or not.
true if the extra configuration file is loaded, false
otherwise.
Contains debugging information on the completer for the given
filetypes. null if no completer is available.
An error occurred.
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.
application/json
The list of available subcommands.
An error occurred
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.
application/json
The detailed diagnostic
An error occurred, or no diagnostic was available
The server needs to react to a number of client events in order to
provide things like diagnotics and to handler 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 focusses 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.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
}
The event that occurred.
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.
The text to insert in order to trigger the snippet. When supplying non-ultisnips suggestions, this is the text to be inserted.
Additional text to display in the completion menu, such as a summary of the snippet to be inserted.
application/json
Optional set of diagnostics for the current buffer.
An error occurred.
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 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.
The candidates to filter and sort
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.
The text the user has typed so far for the current identifier.
This is to filter against the suggestions in candidates.
application/json
The filtered list of candidated
An error occurred
Return true if the server is healthy, false otherwise. The client
should use this endpoint to keep the server alive.
application/json
Server is healthy.
An error occurred.
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.
application/json
Configuration file ignored.
An error occurred ignoring the configuration 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.
application/json
Configuration file loaded.
An error occurred loading the configuration file.
Return asynchronous messages from the server. This request is used by clients in a "long poll" style, and does not return until either:
true is returned and
the client should re-send this request, orreceive_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:
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.
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.
[
{
"message": "Initializing: 19% complete"
},
{
"message": "Initializing: Done."
},
{
"diagonostics": {
"diagnotics": [
{
"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"
}
}
]
An error occurred.
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 compelter
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:
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.fixits.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).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
}
The command line to execute as a list of arguments. The first
such argument is the subcommand to execute (for example:
GoTo).
application/json
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).
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.
If present, this is a simple display message and the value of this property is the message to display.
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.
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).
An error occurred.
The context data, including the current cursor position, and details of dirty buffers.
application/json
Whether or not semantic completion is available.
An error occurred
The word to insert when selecting the completion.
Equivalent of the Vim complete-items entry: word.
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.
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.
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.
An indicator of the type of suggestion. Only the first character
of kind should be displayed.
Equivalent of the Vim complete-items entry: kind.
Completer-specific additional information.
Additional documentation/information to be displayed
alongside (after) information in detailed_info.
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.List of completion suggestions.
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.
Any errors reported by the semantic completion engine.
The completer name.
A list of servers used by the completer.
Additional debugging information.
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.List of ranges to which this diagnostic applies. These ranges typically identify the source locations which should be "highlighted" as incorrect.
The diagnostic text (e.g. error message)
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.
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.
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.
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.
The exception message. Typically a single line and suitable for display to a user.
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).
Contents and details of a dirty buffer.
The entire contents of the buffer encoded as UTF-8
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.
Absolute path to the file in the filesystem. If the file does not yet exist (for example, a new file), then the value may be the empty 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.
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.
The text with which to replace the range identified by range.
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.
An object containing a single asynchronous message.
It is either a SimpleDisplayMessage or a DiagnosticsMessage
If present, this object is a SimpleDisplayMessage
If present, this object is a DiagnosticsMessage
A list of messages in the sequence they should be handled.
The type of message in each item is determined by the property name:
message is a simple display message where
the property value is the message.diagnostics contains diagnotics for a
project file. The value of the property is described below.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.
The server name.
true if the server is running, false otherwise.
The executable path used to start the server.
The address on which the server is listening. null if not
applicable.
The port on which the server is listening. null if not applicable.
The process identifier of the server. null if the server is not
running.
A list of logging files used by the server.
A logging file path.
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.
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.