# 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 question-mark 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.

# Authentication

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: <TEAMSCALE_URL>/user.html#access-key

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.

# Examples

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 e434mikm35d.

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 mon:

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 master:1597993879000. 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.

WARNING

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).