# 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 clicking on the icon at the top right and selecting API Reference.
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.
In case the necessary call is not shown in the documentation you can also append
#/?includeInternal=true to the URL like so
https://teamscale.company.com/api.html#/?includeInternal=true to see non-public service.
However, we do not provide any guarantees on backwards compatibility for the internal services.
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
Services will return JSON responses.
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/api/projects"
To get the list of all findings for the project with ID
curl --user bob:e434mikm35d "http://localhost:8080/api/projects/mon/findings/list?all=true"
And, finally, to get the details for a single finding with specific ID for the same project:
curl --user bob:e434mikm35d "http://localhost:8080/api/projects/mon/findings/D83B237D487AB7DE656ED61CA7032DC6"
# 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.
The branch information is usually passed in as parameter
t in the format
BRANCHNAME:TIMESTAMP (note the colon, which can stay unescaped in the URL), such as
The timestamp is provided as milliseconds since the epoch (start of 1970), but you can also pass in the special value
HEAD to get the latest data on the specified branch.
Timestamps are in milliseconds, while many other tools might produce timestamps in seconds. Make sure to convert these before passing to Teamscale.
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).