Skip to content
This documentation is a preview of the pull request #2253

For the latest updates and improvements in production, open docs.codacy.com instead.

Using the Codacy API#

The Codacy API allows you to programmatically retrieve and analyze data from Codacy and perform a few configuration changes.

Codacy supports two API versions but we strongly recommend using the new API v3 when possible since it's the version being actively developed. Import the OpenAPI 2.0 definition provided below into your development tools to help bootstrap your integration with Codacy.

API v3 (recommended) API v2
Endpoint documentation https://api.codacy.com/api/api-docs https://api.codacy.com/api-docs
OpenAPI 2.0 definition https://api.codacy.com/api/api-docs/swagger.yaml -
Base URL https://api.codacy.com/api/v3 https://api.codacy.com/
Overview

Use the new endpoints to access and manipulate the following resources, among others:

  • Analysis details, issue and ignored issue details, repository quality settings
  • Account details and API token management
  • Organization details and join request management
  • People management
  • Repository management and file details
  • Tool and code pattern details

Use the legacy endpoints to access and manipulate the following resources:

  • Commit code quality details and deltas
  • Project details and configurations, file code quality and issue details

Important

If you're using Codacy Self-hosted you must use your own Codacy instance domain name in the API URLs to access the endpoint documentation matching your Codacy Self-hosted version and to call the endpoints on your Codacy instance.

For example, use the following URLs for the API v3 endpoint documentation and endpoints:

https://<your Codacy instance domain name>/api/api-docs

https://<your Codacy instance domain name>/api/v3

Authenticating requests#

Most API endpoints require that you authenticate using an API token. After obtaining the necessary tokens, include them in your request headers using the format api-token: <your account API token> or project-token: <your repository API token>.

Note

Currently, all API v3 endpoints that require authentication must use account API tokens, while the API v2 endpoints require either account or repository API tokens.

Performing GET requests for public repositories doesn't require authentication.

For example, to make a request to an API v3 endpoint that requires an account API token:

curl -X GET 'https://api.codacy.com/api/v3/user/organizations/gh' \
     -H 'api-token: <your account API token>'

Or to make a request to an API v2 endpoint that requires a repository API token:

curl -X GET 'https://api.codacy.com/2.0/commit/da275c14ffab6e402dcc6009828067ffa44b7ee0' \
     -H 'project-token: <your repository API token>'

Using parameters in requests#

Most API endpoints require that you specify parameters.

For GET requests, specify parameters directly as path segments of the endpoint URLs. Some endpoints also accept optional query string parameters.

For example, to call the endpoint getRepositoryWithAnalysis with the parameters:

  • provider: gh
  • remoteOrganizationName: codacy
  • repositoryName: docs
  • branch (query string): api-overview
curl -X GET 'https://app.codacy.com/api/v3/analysis/organizations/gh/codacy/repositories/docs?branch=api-overview' \
     -H 'api-token: <your account API token>'

For POST, PATCH, and DELETE requests, besides the parameters included in the URL you may also need to include a JSON body.

For example, to call the endpoint searchRepositoryIssues specifying the issue levels Error and Warning in the body:

curl -X POST 'https://app.codacy.com/api/v3/analysis/organizations/gh/codacy/repositories/docs/issues/search' \
     -H 'api-token: <your account API token>' \
     -H 'Content-Type: application/json' \
     -d '{"levels": ["Error", "Warning"]}'

Using pagination#

Endpoints that return lists containing a potential large number of results use cursor-based pagination to return the results in small batches.

These endpoints return the results together with a pagination object:

  • If the pagination object includes a cursor, obtain the next page of results by calling the endpoint again using the cursor from the previous response as a query string parameter

    If the pagination object doesn't include a cursor, the endpoint returned the last page of results

  • Use the query string parameter limit to configure the number of results that the endpoint returns in each page. The maximum limit is 1000 and the default is 100

  • The total is the total number of results that the endpoint can return

Note

To make sure that you receive all results when calling an endpoint with pagination, repeat the process above until the response doesn't include the cursor to obtain another page of results.

For example, the following command requests the first 10 repositories in the Codacy GitHub organization:

curl -X GET 'https://app.codacy.com/api/v3/organizations/gh/codacy/repositories?limit=10'
     -H 'api-token: <your account API token>'

The response includes the first 10 results, as well as the cursor to obtain the next page of results:

{
  "data": [
    ...
  ],
  "pagination": {
      "cursor": "codacy_2",
      "limit": 10,
      "total": 156
  }
}

To obtain the next page of results, it's necessary to include the cursor from the previous page as a parameter:

curl -X GET 'https://app.codacy.com/api/v3/organizations/gh/codacy/repositories?limit=10&cursor=codacy_2'
     -H 'api-token: <your account API token>'

If you continue requesting more pages the endpoint will eventually return a pagination object that doesn't include a cursor. This means that you've reached the last page of results:

{
  "data": [
    ...
  ],
  "pagination": {
      "limit": 10,
      "total": 156
  }
}

Request rate limit#

On Codacy Cloud the number of requests that you can perform to the Codacy API is rate limited to help us provide a reliable service:

  • The limit is 2500 requests per 5 minutes and per source IP address
  • When a request is rate limited, Codacy responds with an HTTP 503 or 504 error code and you should wait before attempting the request again

Although it's possible for you to perform short bursts of requests to the Codacy API, you should always use a delay between requests to ensure that your API client doesn't hit the rate limits.

The request rate limit doesn't apply to Codacy Self-hosted.

Share your feedback 📢

Did this page help you?

Thanks for the feedback! Is there anything else you'd like to tell us about this page?

We're sorry to hear that. Please let us know what we can improve:

Alternatively, you can create a more detailed issue on our GitHub repository.

Thanks for helping improve the Codacy documentation.

Edit this page on GitHub if you notice something wrong or missing.

If you have a question or need help please contact support@codacy.com.

Last modified May 8, 2024