API

Neovim's public API is the surface every UI, plugin, and remote client uses to drive the editor. It lives in src/nvim/api/ and is callable from Lua, Vimscript, and msgpack-rpc, with the same names and the same semantics in each. This section documents the shape of the API; the implementation is covered in API and msgpack-rpc.

Pages in this section

• Public API surface — the families of nvim_* functions, what each is for, and where they're declared.
• UI events — the redraw event protocol that UIs consume.

Where the canonical reference lives

• runtime/doc/api.txt — the user-facing reference, regenerated from C doc comments by make doc.
• runtime/doc/api-ui-events.txt — the UI event spec.
• :help api, :help api-ui-events — same content, in-editor.
• The C source itself — every nvim_* function has a doc comment immediately above it.

How to read the API

Every nvim_* function has the same shape:

/// One-line summary.
///
/// Optional longer description.
///
/// @param p1     What this is.
/// @param p2     What that is.
/// @param[out] err Error details, if any.
/// @return The thing returned, with semantics.
ReturnType nvim_some_function(P1Type p1, P2Type p2, ..., Error *err);

The doc-comment grammar is parsed by src/gen/cdoc_parser.lua. Every parameter type maps to a Lua type and a msgpack type:

API type	Lua type	msgpack type
Boolean	boolean	bool
Integer	integer	int
Float	number	float
String	string	str
Buffer, Window, Tabpage	integer	EXT type
Object	any	any
Array / ArrayOf(T)	T[]	array
Dict / DictOf(T)	table<string, T>	map
LuaRef	function	(Lua only)

A function that takes LuaRef cannot be called from msgpack-rpc — only from Lua. The dispatcher rejects the call with an error.

Stability

Every API function has a since field in its doc comment indicating the NVIM_API_LEVEL it was introduced in. UIs negotiate level at attach time via nvim_get_api_info(). Functions removed between major versions go through src/nvim/api/deprecated.c first, where they emit a one-time warning before being deleted.

Calling from each context

-- Lua
vim.api.nvim_buf_set_lines(0, 0, -1, false, {'hello'})

-- Vimscript
:call nvim_buf_set_lines(0, 0, -1, v:false, ['hello'])

-- msgpack-rpc (any language)
client.request('nvim_buf_set_lines', 0, 0, -1, false, ['hello'])

The wire format is identical across transports; the request name is just nvim_buf_set_lines, the args are an array of API types.