M-Files gRPC API

View as Markdown

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 .proto files below. 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 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.

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.

Start here

• Python quickstart -- From an empty folder to a Python program that logs in to an M-Files vault over gRPC and lists its 10 most recently modified documents, on M-Files Cloud or on-premises.
• C# quickstart -- From nothing to a .NET console app that logs in to an M-Files vault over gRPC and lists the 10 most recently modified documents, on M-Files Cloud or on-premises.
• Go quickstart -- From nothing to a Go program that logs in to an M-Files vault over gRPC and lists the 10 most recently modified documents, on M-Files Cloud or on-premises.
• Connecting to the server -- Endpoints, TLS, HTTP/2, message size and keepalive limits, method paths, and a first anonymous call to check that the server answers.
• Cloud and on-premises -- What differs between M-Files Cloud and an on-premises M-Files Server for a gRPC caller - address, TLS, authentication and the front end.
• Authentication and sessions -- How to log in with each AuthDataType, bind the session to a vault, send the 48-byte session ID, keep the session alive with KeepAlive and close it with LogOut.

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

• Call metadata -- Every metadata key the server reads or writes - session ID, activity ID, remote-call marker, metadata structure version trailer, cookies - plus deadlines and call importance.
• Errors -- How MFServer reports errors over gRPC - status codes, the error trailers, decoding the M-Files error stack, and the common error codes with what to do about each.
• 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

• All services
• All messages
• All enums

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