API Reference


The ezeep Blue REST API allows to manage almost all objects (e.g. organizations, users, printers, connectors, rules, print jobs) in the ezeep Blue world.

For a list of the available resources and their endpoints, see ezeep Blue REST API resources.

You can also use a partial OpenAPI definition, to test the API directly from the ezeep Blue user interface.

Feddback API

ezeep Blue provides a web API to collect the Feedback from the mobile clients, so that we can easily evaluate working and non-working printers or drivers.

ezeep Blue provides a web API that allows to print documents on ezeep Blue printers that are assigned to an user as well as get the rendered data stream back to be forwarded to an local print device connected to the local network (Direct WiFi print).

OAuth2 API

ezeep Blue provides an OAuth2 compatible authentication endpoint

How to use the API

API requests must include the API version in path. Currently only API version v1 is available.

Valid API request

If you consider api2.ezeep.com endpoint:

curl "https://api2.ezeep.com/printing/v1/printers/" --header "Authorization: Bearer $access_token"

or shell curl "https://api2.ezeep.com/printing/v1/printers/" --header "Cookie: ezp_session_id=$session_cookie"

The API uses JSON to serialize data. You don’t need to specify .json at the end of the API URL.

API request to expose HTTP response headers

If you want to expose HTTP response headers using curl as API request tool, use the --include option:

curl --include "https://api2.ezeep.com/printing/v1/printers/" --header "Authorization:Bearer $access_token"
HTTP/1.1 200 OK

This request can help you investigate an unexpected response.

API request that includes the exit code

If you want to expose the HTTP exit code, include the --fail option:

curl --fail "https://api2.ezeep.com/printing/v1/does-not-exist/" --header "Authorization:Bearer $access_token"
curl: (22) The requested URL returned error: 404 Not Found

The HTTP exit code can help you diagnose the success or failure of your REST request.


Almost all API requests require authentication. When authentication is not required, the documentation for each endpoint specifies this.

There are two ways you can authenticate with the ezeep Blue API:

If authentication information is not valid or is missing, ezeep Blue returns an error message with a status code of 401:

  "detail":"Invalid authentication. Could not decode token."

or json { "detail":"Authentication credentials were not provided." }

OAuth2 tokens

You can use an OAuth2 token to authenticate with the API by passing it in the Authorization header.

Example of using the OAuth2 token in a header:

curl --header "Authorization: Bearer <access_token>" "https://api2.ezeep.com/printing/v1/printers/"

Read more about ezeep Blue OAuth2 authentication.

NOTE: ezeep Blue OAuth access tokens have an expiration time of one hour. You can use the refresh_token parameter to refresh tokens. Integrations may need to be updated to use refresh tokens prior to expiration, which is based on the expires_in property in the token endpoint response. See OAuth2 token documentation for examples requesting a new access token using a refresh token.

Signing in to the main ezeep Blue Portal application sets a ezp_session_id cookie. The API uses this cookie for authentication if it’s present. A session cookie will be returned by the ezeep Authentication Service after opening the URL https://account.ezeep.com/auth/signin/ in a browser and successfully presenting a user’s credentials. The cookie is scoped to *.ezeep.com and not readable by scripts. Retrieval of a session Cookie via API is not supported. Information about the current logged in user a script can get by reading the answer of the URL https://account.ezeep.com/auth/me/ using the GET operation.

NOTE: The primary user of this authentication method is the web frontend of the ezeep Blue Portal itself.

Status codes

The API is designed to return different status codes according to context and action. This way, if a request results in an error, you can get insight into what went wrong.

The following table gives an overview of how the API functions generally behave.

Request type Description
GET Access one or more resources and return the result as JSON.
POST Return 201 Created if the resource is successfully created and return the newly created resource as JSON.
GET / PUT / PATCH Return 200 OK if the resource is accessed or modified successfully. The (modified) result is returned as JSON.
DELETE Returns 204 No Content if the resource was deleted successfully.

The following table shows the possible return codes for API requests.

Return values Description
200 OK The GET, PUT or DELETE request was successful, and the resource(s) itself is returned as JSON.
204 No Content The server has successfully fulfilled the request, and there is no additional content to send in the response payload body.
201 Created The POST request was successful, and the resource is returned as JSON.
304 Not Modified The resource hasn’t been modified since the last request.
400 Bad Request A required attribute of the API request is missing. For example, the title of an issue is not given.
401 Unauthorized The user isn’t authenticated. A valid user token is necessary.
402 Payment Required Your ezeep subscription must be upgraded to access the resource.
403 Forbidden The request isn’t allowed. For example, the user isn’t allowed to delete a project.
404 Not Found A resource couldn’t be accessed. For example, an ID for a resource couldn’t be found.
405 Method Not Allowed The request isn’t supported.
409 Conflict A conflicting resource already exists. For example, creating a project with a name that already exists.
412 The request was denied. This can happen if the If-Unmodified-Since header is provided when trying to delete a resource, which was modified in between.
422 Unprocessable The entity couldn’t be processed.
429 Too Many Requests The user exceeded the application rate limits.
500 Server Error While handling the request, something went wrong on the server.


The ezeep Blue API supports the following pagination methods:

  • Offset-based pagination. This is the default method and is available on all endpoints.
  • Keyset-based pagination. Added to selected endpoints but being progressively rolled out.

For large collections, for performance reasons we recommend keyset pagination (when available) instead of offset pagination.

Offset-based pagination

Sometimes, the returned result spans many pages. When listing resources, you can pass the following parameters:

Parameter Description
offset Starting position in relation of all results (default: 1).
limit Maximum number of items to list per page (default: 20, max: 100).

In the following example, we list 50 namespaces per page:

curl --request GET --header "Authorization: Bearer <access_token>" "https://api2.ezeep.com/printing/v1/printers/?limit=50"

Pagination links are returned as part of the content in each paged response. prev and next contain the relevant links. Be sure to use these links instead of generating your own URLs. Additionally count is set to the number of total results.

In the following cURL example, we limit the output to three items per page (limit=3) and we request an offset of 3 (offset=3) of comments printers:

curl --head --header "Authorization: Bearer <access_token>" "https://api2.ezeep.com/printing/v1/printers/?limit=3&offset=3"

The response payload is: json { "count": 10, "next": "https://api2.ezeep.com/printing/v1/printers/?limit=3&offset=6", "previous": "https://api2.ezeep.com/printing/v1/printers/?limit=3&offset=0", "results": [ {"id": "1f3dac2b-da63-48eb-8b22-fcaa4c76a439", ...} ... ] }

Path parameters

If an endpoint has path parameters, the documentation displays them with a preceding colon.

For example:

DELETE /printers/:id/

The :id path parameter needs to be replaced with the printer ID. The colons : shouldn’t be included.

The resulting cURL request for a project with ID a3845dfd-fd2d-4918-913e-ec6c1f70aafe is then:

curl --request DELETE --header "Authorization: Bearer <access_token>" "https://api2.ezeep.com/printing/v1/printers/a3845dfd-fd2d-4918-913e-ec6c1f70aafe/"

Path parameters that are required to be URL-encoded must be followed. If not, it doesn’t match an API endpoint and responds with a 404.

Request Payload

API Requests can use parameters sent as query strings or as a payload body. GET requests usually send a query string, while PUT or POST requests usually send the payload body:

  • Query string:

    curl --request GET "https://api2.ezeep.com/printing/v1/printers/?name=<example-name>&location=<example-location>"
  • Request payload (JSON):

    curl --request POST --header "Content-Type: application/json" \
         --data '{"name":"<example-name>", "location":"<example-location>"}' "https://api2.ezeep.com/printing/v1/printers/"

URL encoded query strings have a length limitation. Requests that are too large result in a 414 Request-URI Too Large error message.

Data validation and error reporting

When working with the API you may encounter validation errors, in which case the API returns an HTTP 400 error.

Such errors appear in the following cases:

  • A required attribute of the API request is missing (for example, the title of an issue isn’t given).
  • An attribute did not pass the validation (for example, the user bio is too long).

When an attribute is missing, you receive something like:

HTTP/1.1 400 Bad Request
Content-Type: application/json
    "detail":"Authentication credentials were not provided"

When a validation error occurs, error messages are different. They hold all details of validation errors:

HTTP/1.1 400 Bad Request
Content-Type: application/json
    "errors": [
            "field": "location"
            "message": "Ensure this field has no more than 255 characters"

This makes error messages more machine-readable. The format can be described as follows:

    "errors": [
            "field": "<field-name>",
            "message": "<error-message>"

Unknown route

When you attempt to access an API URL that doesn’t exist, you receive a 404 Not Found message.

HTTP/1.1 404 Not Found
Content-Type: application/json
    "detail": "Not Found"

Content type

The ezeep Blue API supports the application/json content type by default.

JSON Merge Patch

Selected PATCH APIs accept application/merge-patch+json content type according to RFC 7396 with required request header:

Content-Type: application/merge-patch+json
  • All attributes are optional, including those required when adding a new resource.
  • Requests should only include attributes intended to be modified. Omitted attributes will be left as is.
  • Explicitly sending null will reset an attribute to its default value.
  • Attempts to reset an attribute that is required when adding the resource will be rejected with 400 Bad Request.