Skip to content


Reference for the aedifion HTTP API.


The HTTP API allows accessing all services of the platform through a carefully designed RESTful interface. It can be accessed using a wide range of programming languages, libraries, tools and clients.

If you are using the cloud platform, the base URL of the HTTP API is

If you are using a dedicated platform instance, the base URL of the HTTP API is


where <REALM> is specific to your dedicated platform.

Dedicated platforms and subdomains

In the following and throughtout this documentation, we will use URLs that refer to the cloud platform. If you are using a dedicated platform, remember to use the correct subdomain as explained above.


The HTTP API is completely specified in OpenAPI Specification Version 2 format.


The HTTP API is versioned. The latest version is v2.

The version must be specified as a prefix to the path part of the URL.<VERSION>

E.g., the /user endpoint on API version v2 is located at

Note that and always correspond to the latest version.

Older versions

  • Version v1: Decomissioned in June 2019.

Design principles

The HTTP API is designed according to the following principles.

JSON encoding

All our HTTP API endpoints use the JSON format to encode content of request and response bodies. The JSON standard is widely used on the web and can be written and parsed in virtually any programming language as well as with a wide range of text and code editors.

HTTP methods

We make consistent use of HTTP methods:

  • GET methods are used exclusively to query existing resources and will never trigger any modification of resources. In many cases, you can query single resources by providing a unique identifier or a list of resources of the same type. On success, they directly return the queried resource(s).
  • POST methods are used exclusively to create new resources that previously did not exist, such as new users, projects, or tags. They return a Success object containing the created resource or an Error object with a message that indicates why creating the resource failed.
  • PUT methods are used exclusively to modify existing resources and thus always require a unique identifier of the resource to modify. They return a Success object containing the modified resource or an Error object with a message that indicates why modifying the reference resource failed.
  • DELETE methods are used exclusively to delete existing resources and thus always require a unique identifier of the resource to delete. They return a Success object containing the modified resource or an Error object with a message that indicates why modifying the reference resource failed.

HTTP status codes

The appropriate HTTP status code is used where possible, e.g.,

  • 200 for successful retrieval, modification, and deletion of resources
  • 201 for successful creation of resources
  • 400 for bad requests that the user can correct
  • 401 for access to non-existant or unauthorized resources
  • 403 for valid and authorized requests that are forbidden due to other reasons
  • 404 for access to non-existant resources where this does not leak information
  • 5xx for internal server errors that are not due to and/or fixable by the user

Meaningful error messages

Upon error, an appropriate error message is returned that indicates what went wrong. The error message will be as informative as possible to help you fix the erroneous API call, but will deliberately spare out some details in order to protect privacy. E.g., error messages are formulated such that an unauthorized caller cannot distinguish a non-existant project from one that he/she does not have access to.

Transactional changes

Any API call that touches resources through creation, modification, or deletion, will either succeed as a whole or fail without any modification done. If any errors occurs during a creation, modification, or deletion of an existing resource, all changes made up to that point are rolled back. Viewing an API call as an atomic transaction, the transaction is either made completely or not at all.

Accessing the HTTP API

The API is accessed using HTTP which is one of the most widespread Internet standards today. Thus, you can use a wide range of tools and or programming languages to access it. The best choice depends on your use case and experience.

  • Command line tools are probably the quickest way to issue simple HTTP requests. Adequate tools are already built in all Unix-like systems and may be downloaded for Windows. Of course, these tools do not know anything about the form of request parameters and responses so you will have to do all parsing yourself which quickly becomes unhandy for more complex requests.
  • HTTP libraries are available for all established programming languages. At different levels of abstraction, they let you build, send, and receive HTTP requests and responses yourself. If you want fine-grained control about what is happening or would like to integrate's HTTP API into your own code, HTTP libraries are the best choice.
  • Graphical REST clients are GUIs for HTTP that let you conveniently build, view, send, and parse HTTP requests and responses. If you just want to explore and try out the APIs, this is the best way.
  • API clients can be automatically generated from our API specification for 40+ different programming languages, e.g., Python, Rust, C++, Go, Javascript, and many more. These API clients are, basically, high-level wrappers around standard HTTP libraries and relieve you of much of the boiler plate code for building requests, handling errors, and parsing responses.

Command line tools

Here is how to do a simple HTTP GET request including basic authentication using the two most popular command line tools for opening URLs.


    -X GET
The -X GET option is optional as GET requests are the standard. You will need it, however, for issuing POST, PUT, and DELETE requests.


The -O- option tells wget to print to stdout instead of saving the response in a file.

HTTP libraries

Here are examples in different programming languages for a simple HTTP GET request.

For Python, we greatly recommend the requests library. Alternatives are Python's built-in urllib or httplib modules.

import requests

john = ("", "mys3cr3tp4ssw0rd")
r = requests.get(f"", auth=john)
print(f"{r.status_code} - {r.text}")

curl ""
    -X GET

Graphical REST clients

Swagger UI

The Swagger User Interface (UI) is a Javascript page that is auto-generated from our API specifications and allows you to interactively explore our APIs from within your browser without any additional software. We host it at


Postman is a software development tool that enables users to test calls to APIs via a GUI.

  1. Download the Postman app from
  2. Start the app. You may skip the login.
  3. Build your own story book of HTTP requests


Add a new environment in which you configure the variables email and password that safely stores your credentials. This allows you to save your requests in collections and share these with others without leaking your credentials.

Auto-generated API clients

Using the online Swagger Editor (or the Swagger Codegen desktop application), you can auto-generate API clients for 40+ different programming languages in a few steps:

  1. Go to
  2. Download the the JSON specifications and paste it into the left-side editor field (convert to YAML if you want to).
  3. On the top bar, click Generate Client and choose the desired language.
  4. Download the ZIP Archive and unzip it.
  5. Depending on the programming language, further customization steps might be necessary which we detail below.

Generating a Python API client

  1. Open the file swagger_client/ for editing and configure the API url as well as your login credentials.
# Default Base url = ""


# Username for HTTP basic authentication
self.username = ""
# Password for HTTP basic authentication
self.password = "mys3cr3tp4ssw0rd"
  1. From the base directory of the unzipped archive, open a Python shell.
$ python3
>>> import swagger_client
>>> user_api = swagger_client.UserApi()
>>> r = user_api.get_user()
>>> print(r.user)
{'company_id': 1,
 'email': '',
 'first_name': 'John',
 'id': 1,
 'last_name': 'Doe'}

The process for generating API clients in other languages is similar. But make sure that you set the APIs base URL as well as your login credentials correctly.

Further resources

  • Explore our tutorials that show you how to, e.g., manage user, projects, and permission, or setup alarms, using the HTTP API.

Last update: 2022-09-23
Back to top