The Gentics Mesh REST API provides endpoints enabling you to invoke CRUD operations on just ANY Gentics Mesh element. There are many things you can do with the REST API. To name a few:

  • Obviously you can create, update & fetch multilingual content items as well as tag them.

  • But you can also define the schemas, i.e. the content types of your project.

  • You can do file upload and image manipulation.

  • WebRoot Paths for fetching content by path as well as automatic link resolving greatly simplify the integration with any routing framework.

  • Fetching dynamic navigation menus and breadcrumbs based on the content structure will make your editors happy.

  • With Elasticsearch under the hood you can search your content.

  • You can manage your users and their permissions on content elements.

All REST API responses are available in JSON, only, except for binary data.

Query Parameters

The REST API end points can be used in combination with a set of query parameters, all of which are documented for the specific end points in the Gentics Mesh REST API reference. Following, we provide an overview of the most common query parameters.

Paging Parameters

Name Type Mandatory Description


number (default: 1)


Number of page to be loaded.


number (default: 25)


Number of elements per page.

Versioning Parameters

Name Type Mandatory Description




Specifies the release to be used for loading data. The latest project release will be used if this parameter is omitted.


string (default: draft)


Specifies the version to be loaded. Can either be published/draft or version number. e.g.: 0.1, 1.0, draft, published.

Node Parameters
Name Type Mandatory Description




ISO 639-1 language tag of the language which should be loaded. Fallback handling can be applied by specifying multiple languages in a comma-separated list. The first matching language will be returned. If omitted or the requested language is not available then the defaultLanguage as configured in mesh.yml will be returned.




The resolve links parameter can be set to either short, medium or full. Stored mesh links will automatically be resolved and replaced by the resolved webroot link. With the parameter set the path property as well as the languagesPath property (for available language variants) will be included in the response. Gentics Mesh links in any HTML-typed field will automatically be resolved and replaced by the resolved WebRoot path. No resolving occurs if no link has been specified.

Role Permission Parameters
Name Type Mandatory Description




The role query parameter take a UUID of a role and may be used to add permission information to the response via the rolePerm property which lists the permissions for the specified role on the element. This may be useful when you are logged in as admin but you want to retrieve the editor role permissions on a given node. Endpoint: /api/v1/:projectName/nodes?role=:roleUuid


We have set up a Gentics Mesh instance for demo purposes, that you can play with.

Let’s see what’s inside…​

List all projects. Well, it’s just our demo project.
Want to fetch all content items including media? With pretty URLs? Here you go
And now forget about UUIDs and do it with its corresponding WebRoot path

That’s easy. Well, what about images?

The Insomnia REST client can be used to build and invoke requests from your browser to Gentics Mesh.

HTTP details


Gentics Mesh expects and returns UTF-8 encoded data. Sending data in any other encoding format will result in encoding issues.


It is important to set the Content-Type: application/json when sending JSON data and to also set the Accept header in order to signal Gentics Mesh that your client is accepting JSON.

Content-Type: application/json
Accept: application/json

A request which is not well formatted may fail. Gentics Mesh will do its best to identify the issue and return a meaningful error response in those cases.


The Cross-Origin Resource Sharing mechanism enables Gentics Mesh to configure cross-domain access controls.

You can read up on this topic on the MDN article.

The CORS header handling can be configured using the httpServerOptions.corsAllowedOriginPattern and httpServerOptions.enableCors configuration settings.

ETag Handling

Most endpoints of the Gentics Mesh REST API will return an ETag header within the response.


These headers values can be used to implement or utilize existing web caching solutions.

An ETag validation ocures once the ETag is passed along a http request.


Gentics Mesh will compare the provided ETag with the current state of the content and return a 304 response if the ETag is the same and the response did not change. Updating the requested resource will alter its ETag and thus another request would return the response which includes the current ETag.



Gentics Mesh provides multiple ways of authentication:

  • Authentication via login

  • Authentication via API token

  • No authentication - Access via anonymous user

Currently, all data including media assets such as images, videos, and documents are secured and need authentication to be retrieved.
Sending user credentials as base64 encoded string, or as plaintext is highly insecure to be used on an open network. This method MUST not be used in scenarios other than debugging and development when the connection between server and client is trusted.

Authentication Configuration

Gentics Mesh uses JWT (JSON Web Token) to handle authentication. It is thus required to create a cryptograph key to sign and verify the generated JWT’s. Typically, if no keystore file has been provided, Gentics Mesh will create one on the basis of the configuration details in mesh.yml (see Configuration & Settings). If the keystorePassword property is omitted, a password will be generated randomly and stored in the configuration file.

  tokenExpirationTime: 3600
  keystorePassword: "secret"
  keystorePath: "keystore.jceks"
  algorithm: "HS256"

Alternatively, you can use the Java keytool to create a new keystore. Here is an example on how to create a keystore which contains a HMacSHA256 key:

keytool -genseckey -keystore keystore.jceks -storetype jceks -storepass secret -keyalg HMacSHA256 -keysize 2048 -alias HS256 -keypass secret

After creating the keystore, you need to set the keystore password, the path to the keystore file, and the used algorithm in the mesh.yml configuration file (see Configuration & Settings).


In order to be able to store and retrieve content, a Gentics Mesh user needs to authenticate (username:password).

Each way will store a JWT in a cookie which is used to authenticate the user for succeeding requests. The token only lasts a certain amount of time (which can be configured in the mesh.yml file, see setting tokenExpirationTime in the Configuration & Settings section), so it might be necessary to refresh the token. The JWT will be automatically renewed with every request on the Gentics Mesh API.


Basic Authentication Header

In basic authentication, when a client requests a URL that requires authentication, the server requests the client to authenticate itself by sending a 401-Not Authorized code. The client, in return, answers with login credentials sent in the authorization header:

authorization: Basic {base64_encode(username:password)}

In Gentics Mesh, a user can be authenticated by invoking a regular GET request to the /api/v1/auth/login endpoint including a basic authentication HTTP header.


curl -v -X GET   http://localhost:8080/api/v1/auth/login   -H 'authorization: Basic YWRtaW46YWRtaW4='

The response will be a valid JWT as well as set a cookie with the token.

  "token" : "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ1c2VyVXVpZCI6IjNjYjY2YzU0MmFlMzRiMDFiNjZjNTQyYWUzY2IwMWRiIiwiaWF0IjoxNDkxNzczMDYzLCJleHAiOjE0OTE3NzY2NjN9.8iG3I0Pe1M7J43pwbsBXiBOd6p0sn9dRxO3NfazVbOk="


Alternatively, the user can POST his or her credentials to the /api/v1/auth/login endpoint in order to retrieve a token. The JSON object must contain the following fields:

  • username: The username of the user

  • password: The password of the user

If authentication has been successful, the server will respond with a JSON object containing a single property:

  • token: The token to be sent on every subsequent request.

Additionally, the token will also be provided in a cookie.


curl -v -X POST \
  http://localhost:8080/api/v1/auth/login \
  -H 'content-type: application/json' \
  -d '{
  "username" : "admin",
  "password" : "admin"
*   Trying ::1...
* Connected to localhost (::1) port 8080 (#0)
> POST /api/v1/auth/login HTTP/1.1
> Host: localhost:8080
> User-Agent: curl/7.50.3
> Accept: */*
> content-type: application/json
> Content-Length: 50
* upload completely sent off: 50 out of 50 bytes
< HTTP/1.1 200 OK
< Content-Type: application/json; charset=utf-8
< Cache-Control: no-cache
< Content-Length: 208
< Set-Cookie: mesh.token=eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ1c2VyVXVpZCI6IjNjYjY2YzU0MmFlMzRiMDFiNjZjNTQyYWUzY2IwMWRiIiwiaWF0IjoxNDkxNzczODU0LCJleHAiOjE0OTE3Nzc0NTR9._qt3Eufi7-3jnvgQ8lfe_KwJbd5ePwx5jOFrCK9w76A=; Max-Age=3600; Expires=Sun, 9 Apr 2017 22:37:34 GMT; Path=/
  "token" : "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ1c2VyVXVpZCI6IjNjYjY2YzU0MmFlMzRiMDFiNjZjNTQyYWUzY2IwMWRiIiwiaWF0IjoxNDkxNzczODU0LCJleHAiOjE0OTE3Nzc0NTR9._qt3Eufi7-3jnvgQ8lfe_KwJbd5ePwx5jOFrCK9w76A="
* Curl_http_done: called premature == 0
* Connection #0 to host localhost left intact

Both login methods will yield a JSON web token.

For further requests, the JWT can be provided in two ways. By default it is passed along with a cookie value. E.g., this is useful for embedding binary image nodes directly in HTML, since the browser will automatically handle authentication on the basis of the cookie. Alternatively, the token can be passed along within the Authorization header which includes the regular JWT Bearer <Token>, where <Token> is the token you received from the login/cookie.

curl -X GET \
  http://localhost:8080/api/v1/demo/nodes \
  -H 'Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ1c2VyVXVpZCI6IjNjYjY2YzU0MmFlMzRiMDFiNjZjNTQyYWUzY2IwMWRiIiwiaWF0IjoxNDkxNzY1NDEzLCJleHAiOjE0OTE3NjkwMTN9.UY8OgjiK5qyZobAWt6X1Vd1Z-zg68BeJgGZKbW4Ucj0=' \

API Token

An API token will never expire. This is different from regular tokens which will be issued when calling /api/v1/auth/login.

Leaking an API token is potentially dangerous and thus the API token should only be used in combination with a secure connection.

Typical use cases for API tokens are backend implementations which constantly communicate with Gentics Mesh using a secure or local connection.

The token can be issued per user with POST /api/v1/users/:userUuid/token.

Creating a new API token will automatically invalidate a previously issued token.

Since the token is just a regular JWT you just need to add it to your request Authorization header field.

curl -X GET \
  http://localhost:8080/api/v1/demo/nodes \
  -H 'Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ1c2VyVXVpZCI6IjNjYjY2YzU0MmFlMzRiMDFiNjZjNTQyYWUzY2IwMWRiIiwiaWF0IjoxNDkxNzY1NDEzLCJleHAiOjE0OTE3NjkwMTN9.UY8OgjiK5qyZobAWt6X1Vd1Z-zg68BeJgGZKbW4Ucj0=' \

It is possible to manually revoke a previously issued token via DELETE /api/v1/users/:userUuid/token. Once the token is invalidated it can no longer be used for authentication.

Anonymous Access

Gentics Mesh first and foremost keeps your content safe - all data including media assets such as images, videos, and documents are secured and need authentication to be retrieved. However, sometimes it may be desirable to serve public content with Gentics Mesh.

That is why Gentics Mesh instances ship with an included anonymous user/role/group set. If no authentication details are provided Gentics Mesh will automatically try to authenticate with the user anonymous.

Try our Gentics Mesh demo instance without authenticating yourself: https://demo.getmesh.io/api/v1/auth/me. This API endpoint shows the currently authenticated user - which is anonymous.

You can assign readPublished permissions to the anonymous role for all elements you want to be publicly available.

Assigning further permissions would of course allow for other operations to be granted.

Anonymous access can be configured in the mesh.yml configuration file (see Configuration & Settings):

   enableAnonymousAccess: true
Recreating a previously deleted anonymous user would automatically re-enable the feature if the configuration setting enableAnonymousAccess is set to true.