# REST API
The Teamscale server exposes all of its functionality as REST web services. All functionality used in the Web UI and the IDE integrations is built upon these services and can also be used programmatically.
# Available REST Services
The list of REST services is available from a running Teamscale
instance by appending
servicedoc.html to the base URL and opening the
page in a web browser.
For a local test instance, the URL might look like this: http://localhost:8080/servicedoc.html.
To get an idea which service might be useful, you can also observe the calls made from the Web UI using the development tools of your web browser.
Authentication for Teamscale's REST API happens via HTTP Basic Authentication and thus require a user name and the user's Access Key (not the password). The service call is then executed with the permissions of this user.
You can generate an access key on your profile page:
A sample call using authentication using curl to
https://demo.teamscale.com for user
demo with an access key
7eSRFFOEUqO7NhhqDeyB1yEbUsMzZGDN would be:
curl --user demo:7eSRFFOEUqO7NhhqDeyB1yEbUsMzZGDN "https://demo.teamscale.com/api/health-check"
# Result representation
Most services will return JSON responses.
# Calling Conventions & Service Types
We differentiate between two types of services:
Project services allow querying data from a single project, for example the list of findings. These services need the project name as a parameter and thus, adhere to the URL form of
Global services are not specific to a single project and can be used to query all projects of an instance. These services are called directly by appending the service name to the base URL.
Many services take their main argument (e.g., a code path) directly
attached to the main URL. Some services also accept additional
parameters that are passed using the HTTP convention: Parameters are
separated by a
? from the main URL and separated by
For first experiments, the tool curl can be used to query services
from the command line. For this we assume the service to be running on
http://localhost:8080/, the user name to be bob and his access key to be
To get the list of all projects visible to the user, you can use
curl --user bob:e434mikm35d "http://localhost:8080/projects"
To get the information about the configured metrics for a project with id mon:
curl --user bob:e434mikm35d "http://localhost:8080/p/mon/metric-schema"
And, finally, to get the actual metric values for a branch rel42 at timestamp 374343221 for the same project:
curl --user bob:e434mikm35d "http://localhost:8080/p/mon/metrics?t=rel42:374343221"
# Common pitfalls
Always make sure that you use the IDE access key as password and not the actual password of the user when making REST calls. Also, the user needs to have sufficient permissions to view or change the corresponding data.
If something does not work as expected, you can often find additional information in the Service Log, which is available via the Web UI (System perspective).