# Web API

SonarQube Cloud offers a Web API, allowing external applications to access its features. The base URL for accessing the API depends on whether you are using the SonarQube Cloud’s EU or [US instance](https://docs.sonarsource.com/sonarqube-cloud/getting-started/getting-started-in-us-region)

* **EU instance**:
  * V1: <https://sonarcloud.io/web_api>
* **US instance**:
  * V1: <https://sonarqube.us/web_api>

{% hint style="warning" %}
The Web API V2 will gradually replace the Web API V1 as endpoints get deprecated and replaced.
{% endhint %}

## Web API documentation

The SonarQube Cloud’s Web API v2 documentation is available [here](https://api-docs.sonarsource.com/sonarqube-cloud/default/landing).

The web services composing the Web API v1 are documented within SonarQube Cloud, through the URL[ https://sonarcloud.io/web\_api](https://sonarcloud.io/web_api).

You can also access the Web API documentation from the top bar in Cloud by selecting the help button.

<figure><img src="broken-reference" alt="Select the help menu (question mark icon) in the top right corner."><figcaption></figcaption></figure>

## Authenticating to the Web API <a href="#authenticate-to-api" id="authenticate-to-api"></a>

Administrative web services are secured and require the user to have specific permissions.

To authenticate to the Web API, we recommend that you use the [bearer authentication scheme](https://swagger.io/docs/specification/v3_0/authentication/bearer-authentication/). With this scheme, a SonarQube Cloud token is used:

* The token is generated in SonarQube Cloud UI. See [managing-tokens](https://docs.sonarsource.com/sonarqube-cloud/managing-your-account/managing-tokens "mention").
* The token is provided through the `Authorization: Bearer <myToken>` header. See [#sample-api-request](#sample-api-request "mention") below.

## Sending an API request <a href="#send-api-request" id="send-api-request"></a>

{% tabs %}
{% tab title="Web API v2" %}
To make a request, you need to find the SonarQube Cloud API and the right path for the operation that you want to use. The following APIs are available:

* Analysis
* Authentication domain
* Audit logs
* AICA (AI Code Assurance)
* Enterprises, Reports, Portfolios, Portfolio Permission Templates
* Organizations
* Projects
* Quality Gates
* SCA (Software Composition Analysis)
* Software Quality Reports
* Users and roles

**Sample request**

The code block below shows a request with cURL.

<pre class="language-bash"><code class="lang-bash">curl --request GET \
<strong>  --url 'https://api.&#x3C;domain>/&#x3C;endpoint>' \
</strong>  --header 'Authorization: Bearer my_token'
</code></pre>

Where `<domain>` is:

* For the EU instance: `sonarcloud.io`
* For the US instance: `sonarqube.us`

**Example**:

<pre class="language-bash"><code class="lang-bash">curl --request GET \
<strong>  --url 'https://api.sonarcloud.io/organizations/organizations' \
</strong>  --header 'Authorization: Bearer my_token'
</code></pre>

{% hint style="info" %}
For more information about API request and response, see the [SonarQube Cloud’s Web API v2 documentation](https://api-docs.sonarsource.com/sonarqube-cloud/default/landing).
{% endhint %}
{% endtab %}

{% tab title="Web API v1" %}
To make a request, you need to find the HTTP method and the right path for the operation that you want to use.

{% hint style="warning" %}
It’s highly recommended to use form data parameters when making POST requests to the Web API. If you use URI query parameters instead then these parameters won’t be securely passed to the endpoint.
{% endhint %}

**Content-Type header**

Unless the Sonar Web API endpoint specifications list a specific `Content-Type` value, your request should use the following `Content-Type` header:

`Content-Type: application/x-www-form-urlencoded`

This is the default `Content-Type` value set by most tools and libraries, such as `curl` and Python’s `requests` module, but you should check their documentation for proper usage.

**Sample API request**

If, for example, you want to use the Web API to extract measures, you can make a "GET MEASURES" call to the SonarQube Cloud [`/api/measures`](https://sonarcloud.io/web_api/api/measures?deprecated=false) endpoint in order to extract measures of a given metric for a given project. For this example, a possible request and response are shown below.

**Sample request**

```bash
curl --request GET \
  --url 'https://sonarcloud.io/api/measures/component?metricKeys=ncloc%2Ccode_smells%2Ccomplexity&component=my_project_key' \
  --header 'Authorization: Bearer my_token' 
```

Where \<domain> is:

* For the EU instance: `sonarcloud.io`
* For the US instance: `sonarqube.us`

**Sample response**

```bash
{
   "component": {
      "id": "id",
      "key": "my_project_key",
      "name": "my_project_name",
      "qualifier": "TRK",
      "measures": [
         {
            "metric": "complexity",
            "value": "4214"
         },
         {
            "metric": "code_smells",
            "value": "8595",
            "bestValue": false
         },
         {
            "metric": "ncloc",
            "value": "51667"
         }
      ]
   }
}
```

{% endtab %}
{% endtabs %}

## Taking into account the API rate limiting <a href="#api-rate-limiting" id="api-rate-limiting"></a>

Some of SonarQube Cloud’s APIs are rate-limited in order to ensure that we can continue to deliver the service smoothly and with optimum performance. In most cases, you should take this into account when automating tasks and processes by using the SonarQube Cloud Web API.

Your API calls will fail with a 429 status code when the rate limit has been reached. If this happens, wait a few minutes before retrying the operation.

## Related pages

* [getting-started-in-us-region](https://docs.sonarsource.com/sonarqube-cloud/getting-started/getting-started-in-us-region "mention")