M-Files gRPC API
The M-Files Server gRPC API is the complete interface to M-Files Server. The M-Files web and desktop clients and M-Files Admin use it for everything they do with the server: working with objects, files and metadata, searching, workflows, and administering vaults and the server.
The COM API and the REST API, also documented on this portal, are layers on top of the same server interface: the COM API calls it, and the REST API is built on the COM API. They expose much, but not all, of what the gRPC API offers.
- Native gRPC (recommended). Call the API over HTTP/2 with any gRPC implementation, using the
.protofiles below, or the client packages for Python, C# and Go. Use it from servers, desktop applications, scripts and agents. - mf-http-grpc. For browsers and other environments that cannot speak HTTP/2 gRPC, the mf-http-grpc gateway accepts the same messages as JSON over HTTP, at routes such as
POST /grpc/v1/get-object-types(the method name in kebab case; each method page shows its route).
The API evolves with M-Files Server: most changes are additions, and methods can also be deprecated or removed. See Versions and compatibility.
You need a gRPC library for your language, the server's address (port 443 with TLS on M-Files Cloud, 7766 by default on-premises) and an M-Files account. Connecting to the server lists the endpoints, TLS and the limits.
Start here
- Find your endpoint: Cloud and on-premises tells M-Files Cloud and on-premises apart.
- Run a quickstart in your language, about 10 minutes: Python quickstart, C# quickstart, Go quickstart.
- Learn what every call needs: Connecting to the server, Authentication and sessions, Call metadata, Errors.
- Learn the model: Concepts -- The M-Files model behind the API: vaults and their metadata structure, objects and versions, properties, search, permissions and workflows.
- Do a task: Guides -- recipes for searching, reading and creating objects, files, workflows and errors.
- Look up methods in the API reference: Vault API, Administration API, Server integration API.
Client packages
The client code generated from the .proto files, with helpers for the connection, login, call metadata and errors that the guides use. Each package has the version of the server release it was generated from, and its repository has runnable examples.
| Language | Package | Install | Source |
|---|---|---|---|
| Python | mfiles-grpc | pip install mfiles-grpc==26.11.0 | M-Files/mfiles-grpc-python |
| C# | MFiles.Grpc | dotnet add package MFiles.Grpc --version 26.11.0 | M-Files/mfiles-grpc-dotnet |
| Go | github.com/M-Files/mfiles-grpc-go | go get github.com/M-Files/mfiles-grpc-go@v0.2611.0 | M-Files/mfiles-grpc-go |
| API version | 26.11 |
|---|---|
| Package | MFiles |
| Services | 78 |
| Methods | 712 |
| Generated | 2026-11-06T06:32:26+00:00 |
For coding agents
- llms.txt -- the map of this documentation, with Markdown links
- methods.txt -- one line per method
- methods.jsonl -- one JSON object per method
- llms-full-vault.txt -- all pages of the Vault API as one Markdown file
- llms-full-admin.txt -- all pages of the Administration API as one Markdown file
- llms-full-integration.txt -- all pages of the Server integration API as one Markdown file
- llms-full-guides.txt -- all concept, runtime and guide pages as one Markdown file
Every page has a Markdown twin: add index.md to its URL.
Concepts
- Vault and metadata structure -- How an M-Files vault is organized (object types, value lists, classes, property definitions, workflows) and the separate ID spaces that identify them.
- Objects and versions -- Object and version identity (ObjID, ObjVer), latest versus specific versions, check-out and check-in, files, deleted versus destroyed objects, GUIDs and external IDs.
- Properties and values -- How property values are represented (PropertyValue, TypedValue), how to set each data type including lookups and empty values, and the rules the server enforces.
- Search -- The search condition model (expression, condition type, value), the conditions you need most with their exact message shapes, and how results, limits, sorting and paging behave.
- Workflows -- Workflows, states and state transitions as metadata; how to read the allowed transitions, change an object's state, and what electronic signatures add.
- Permissions -- Vault-level rights, object ACLs and named ACLs, effective permissions, setting the ACL of a new object, and what "access denied" looks like to a gRPC caller.
- Metadata structure version and caching -- The vault's metadata structure version (mfiles-metadata-version-bin trailer, GetMetadataStructureVersion), the per-list version numbers, and how to cache the metadata structure safely.
Runtime conventions
- Files -- How to download and upload file content - download sessions, block sizes, upload sessions and inline content, which method to choose, and the limits that apply.
- Versions and compatibility -- How the API changes between versions, how to find out what a server supports (QueryVersion, GetServerCapabilities), what to send in ClientData, and the compatibility rules that let one client work with older and newer servers.
- HTTP access (mf-http-grpc) -- The JSON-over-HTTP gateway that M-Files Server runs next to its gRPC endpoint for browsers - what it is, how its routes and JSON map to the gRPC API, and why native gRPC is the better choice elsewhere.
Guides
- Connect, log in and keep the session -- Check the server version and capabilities anonymously, log in to a vault, read the session information, keep the session alive and log out.
- Read the vault structure -- List object types, classes and property definitions, find the properties of a class, and resolve the ID of a class or property by its alias.
- Search for documents -- Find the documents of a class modified in the last N days, newest first, with SearchObjects - object type, deletion, class and date conditions, sorting and a limit.
- Read an object and its properties -- Get the latest version of an object with all its property values in one call, and print text, number, date, timestamp, lookup and multi-select lookup values.
- Download a file -- Download a file of a document version to disk with a download session - DownloadFile_Begin, DownloadFile_ReadBlock in a loop, DownloadFile_Stop.
- Create a document -- Upload a file with UploadTempFile and UploadTempFileCommit, then create a single-file document with a class, a title and an access control list with AddObjectWithFiles.
- Update properties safely -- Change property values without overwriting other users' changes - SetProperties on the version you read with fail_if_newer_version_exists, or CheckOut, SetProperties and CheckIn.
- Change the workflow state -- Read a workflow's states and the transitions the user may take from an object's current state, and move the object to another state by setting its State property.
- Page through large result sets -- Visit every object that matches a search, page by page, by sorting on object ID and asking each page for the objects after the last ID of the previous one.
- Handle errors -- Catch a failed call, decode the M-Files error code from the error trailers, and tell "not found" and "access denied" apart from other errors.
API reference
| Book | Contents | Services | Methods |
|---|---|---|---|
| Vault API | Everything an application does in a vault on behalf of a user. | 39 | 380 |
| Administration API | Server and vault administration, metadata structure and user management. | 28 | 264 |
| Server integration API | Services that other M-Files components and connectors call. | 11 | 68 |
Downloads
- mfiles-grpc-api-bundle.zip -- the .proto files and the runnable Python, C# and Go samples
- mfiles-grpc-api-proto.zip -- the .proto files of the API
- All downloads -- proto files, descriptor set, manifest and indexes