2. Query the artifacts

2.1. Basic usage

We have an access key to initiate authenticated calls to the API (if it is not the case, please go back to Authentication), we can now query a tracker to retrieve some artifacts.

For example to retrieve all artifacts that are in Completed status we will issue the following query:

$ curl -XGET --header 'Content-type: application/json' \
    --header 'X-Auth-AccessKey: tlp.k1.1026…' \
    -d '{"status_id":{"operator":"contains","value":"504"}}' \

This will return a bunch of artifacts. Some explanations about values used in this example:

  • tlp.k1.1026… and 115 is the access key you get in the previous section. You should already know what it is and how to get it.

  • status_id is the shortname of the field Status of my tracker.

  • 504 is the id of the value Completed. This value is one of the possible values for the field Status.

  • 101 in the URI is the id of the tracker.

In the list of artifact representations we get, we can query the API to have more details about an artifact with GET /api/artifacts/220.


The API is self discoverable. This means that each resource will detail its sub-resources, meaning that you shouldn’t have to know in advance which id or which shortname to use in your calls.

For example, GET /api/projects will return an array of project representations:

  "id": 110,
  "uri": "projects/110",
  "label": "Project 42",
  "shortname": "project42",
  "resources": [
      "type": "trackers",
      "uri": "projects/110/trackers"

From here I can get the list of trackers of the project with GET /api/projects/110/trackers, etc. Which calls you have to orchestrate will depend on your business case.

In our example, getting the structure of the tracker is important as we need to know the id of the fields/values (either projects/110/trackers or trackers/123 will give us the structure).

2.3. Conclusions

Now we are able to:

  • Do authenticated calls

  • Do a basic GET to retrieve information (projects, trackers, artifacts, …)

  • Handle pagination

This only covered artifacts, but you can apply what you’ve just learned to every routes provided by your Tuleap instance.

You can stop here or do write operations in next section: Update an artifact.