LGTM API specification

Tools (31)

Extracted live via the executor SDK.

• analyses.getAlerts

  Download all the alerts found by an analysis. Use the Accept: request header to specify the output media type as either CSV or SARIF:

  • application/sarif+json: Alerts in SARIF format. If no version is specified the latest supported SARIF version is used.

  • application/json: Alerts in SARIF format (deprecated). If no version is specified, SARIF 2.0.0 is used for backwards compatibility.

  • text/csv: Alerts in CSV format. The text/csv media type has two optional parameters:

    • charset: determines the character encoding of the text, by default UTF-8.
    • header: determines whether a header row with column names is present or absent. The default value for this parameter is present. For example, an Accept header with value text/csv; header=absent would result in CSV output without a header row.

  To find the analysis identifier for a commit, use the /analyses/{project-id}/commits/{commit-id} endpoint. For more information, see Get analysis summary for a specific commit.

• analyses.getAnalysis

  Get a summary of the analysis results for a specific analysis identifier.

  To find the analysis identifier for a commit, use the /analyses/{project-id}/commits/{commit-id} endpoint. For more information, see Get analysis summary for a specific commit.

  This endpoint reports the commit analyzed and a summary of the results for each language. Alternatively, you can use this identifier to download full details of all the alerts found by the analysis. For more information, see Get detailed alert information.

• analyses.getAnalysisForCommit

  Get a summary of the analysis results for a specific commit, or the latest commit, to a project. (For projects configured for sparse or upload analysis, only latest is supported.)

  This endpoint reports a summary of results for each language, and also the analysis identifier. You can use the analysis identifier to download full details of all the alerts found by the analysis. For more information, see Get detailed alert information.

• analyses.requestAnalysis

  Trigger the analysis of a specific commit to a project. If a previous attempt to analyze that commit failed, this triggers a fresh analysis. This is supported for all LGTM projects, regardless of repository type or host. The commit must be available in the main repository, but can be on a branch that isn't tracked by LGTM. For both LGTM.com and LGTM Enterprise, you must include an access token with the analyses:write scope.

  When you request the analysis of a commit, the API returns:

  • operation-id: used to track the status of the task using the /operations endpoint. For more information, see Get operation status.
  • status: initially pending.
  • task-result: containing information about the progress and results of the analysis.
• apiRoot.getSpec

  Get the specification of this API in OpenAPI format. This endpoint does not require an access token. This makes it easier for you to use the specification with third-party tools.

• apiRoot.getVersion

  Get the version information of this API.

• codeReviews.getCodeReview

  Get the results of a code review using the review identifier for the task.

  When you request a code review, the response includes a task result URL of the form: /codereviews/{review-id}.

  This endpoint reports the results of a complete code review, or the status of a review that's still in progress.

• codeReviews.requestReview

  Trigger the code review of a patch. This is available for projects with Git repositories.

  Your request must include:

  • Identifier for the base commit
  • Patch generated using git diff --binary (see git diff)
  • Header Content-Type: application/octet-stream
  • For both LGTM.com and LGTM Enterprise, an access token with the codereviews:write scope

  Note that if you make a request using Curl, you'll also need to add --data-binary to the request to ensure that the patch you supply in the body is sent with newlines unchanged. You can track the progress of the review using the task result URL returned on creation of the task, or by calling the /operations endpoint with the operations identifier returned by the request. For more information, see Get operation status. Alternatively, if you supply a callback URL you'll get a post-back automatically on completion of the review.

  When the review is complete, you can access the results using the task result URL.

• issues.getIssue

  Fetch the alert information for an issue in SARIF format.

• operations.getOperation

  Track progress of a long-running operation using the operations identifier returned when you created the operation. For example, by triggering the analysis of a commit, or the code review of a patch. For both LGTM.com and LGTM Enterprise, you must include an access token with the operations:read scope.

• projects.addProject

  LGTM administrators can add a new project to LGTM by providing a repository URL. By default, LGTM tries to build and analyze the project in the same way as for projects added through the user interface. If at least one language is successfully analyzed, and the repository doesn't already exist on LGTM, a new project is created. If the project already exists but your API call triggers a successful analysis of additional languages, LGTM adds those languages to the project.

  You can configure how LGTM processes the project using query parameters to:

  • Specify the languages to analyze.
  • Create a new project in sparse mode.
  • Create a new project in upload mode to analyze externally-generated databases. Each database represents a snapshot of the codebase. Use this option when you want to upload databases that were generated by the CodeQL CLI (or the QL command-line tools). The version of the command line used to generate the database must be the same version as LGTM Enterprise.

  With any of these options, you can also include an lgtm.yml in the body of the request to customize extraction.

• projects.deleteProject

  Delete a project with a particular numeric project identifier. In addition to access to the project, administrative access to LGTM or the LGTM Enterprise instance is required to delete projects.

• projects.getProject

  Get the latest summary for a specific project using the numeric project identifier.

  To find the LGTM identifier for a project, list all projects using the /projects endpoint and look up the project by name. Alternatively, use the /projects/{provider}/{org}/{name} endpoint. If you have administration access, the project identifier is also displayed in the administration page for the project.

• projects.getProjectByUrlIdentifier

  Get the latest summary for a specific project using the project's URL identifier {provider}/{org}/{name}.

  To find the URL identifier for a project, view the project overview page in LGTM. The URL identifier follows after /projects. For example, for a project with the URL https://lgtm.example.com/projects/g/apache/commons-io the URL identifier is g/apache/commons-io. In the example, g represents the provider (repository host), apache is the organization and commons-io is the name of the repository.

• projects.getProjectConfig

  Get the latest configuration for a specific project using the numeric project identifier.

• projects.getProjects

  List all the projects the current user has authorization to view.

  A maximum of 100 projects are returned in each response. When further results are available, the response includes the URL you need to request the next page of results.

  Use the optional parameter, limit, to change the number of results reported in each response (range of 1—100). If you supply an invalid value for this parameter, the default value of 100 is used.

  When more than one page of results is available, each response includes a nextPageUrl response parameter. You can use this URL to request the next page of results. The nextPageUrl includes an automatically generated start parameter, which specifies the projects to return in the next page of results.

• projects.setProjectConfig

  Set the administrator configuration for a specific project using the numeric project identifier.

• queryJobs.createQueryJob

  Submit a query to run on one or more projects on LGTM. The query is included in the body of the request.

• queryJobs.getQueryJob

  Get the status of a query job using the query job identifier for the task.

  When you create a query job, the response includes a task result URL of the form: /queryjobs/{queryjob-id}.

• queryJobs.getQueryJobResultsForProject

  Fetch the results for a specific project. The endpoint succeeds only if the query was successful, and returns a 404 error otherwise. By default, the endpoint provides only results that are within the source tree. To obtain all results, specify the nofilter parameter.

• queryJobs.getQueryJobResultsOverview

  This endpoint provides a summary of the results generated by completed query runs for each project specified in the the POST /queryjobs endpoint. For completed query jobs, the summary includes:

  • The number of results for successful query runs.
  • Error information for failed query runs.

  No information is included in the response for any project for which the query run is still in progress.

• snapshots.abortUpload

  Aborts the specified upload session and deletes any uploaded parts. After the session is aborted it cannot be restarted. If any part uploads are in progress when the session is aborted, their data may not be deleted. To ensure that uploaded parts are deleted correctly, you should only abort an upload session after all part uploads have completed.

• snapshots.completeUpload

  Completes the database upload by closing the upload session, upgrading the database if appropriate, and scheduling analysis of that snapshot of the codebase.

  You can view the analysis progress and access the results using the task-result-url.

• snapshots.getSnapshot

  Download a CodeQL database from LGTM, representing a snapshot of the codebase, to run queries in your IDE.

  This endpoint works for projects that have been successfully analyzed for the language specified in the request. A successful request redirects you to a URL for downloading a database that represents the code snapshot, as specified in the Location: header in the response. Therefore, your HTTP client should be configured to follow redirects. For example, if you are using curl, you can add the-L flag to the command.

  The database is downloaded as a zip file that can be imported into an IDE equipped with a CodeQL extension. The extension must be up to date to analyze databases downloaded from LGTM. For more information on running queries locally in your IDE, see Runnning queries in your IDE.

• snapshots.initSnapshotUpload

  Start a session to upload an externally-built database (which represents a snapshot of a codebase) to a project on LGTM.

  This endpoint works for projects that are already on LGTM, and the selected language of the database must already be configured. The project must be configured with 'upload' analysis mode. You can upload a "bundled" CodeQL database or a database exported by the QL command-line tools (odasa).

  If your database was generated using a version of the command line that is older than LGTM, LGTM will try to upgrade and analyze it when the upload is complete. You can include cached predicates in the upload, but they are ignored as the cache is repopulated after the database has been upgraded and analyzed. However, if you want to include results with your database, make sure the database is compatible before you start the upload session. Incompatible databases with results won't be upgraded and therefore cannot be uploaded. For further information on externally-built databases, see Preparing snapshots to upload to LGTM using the QL command-line tools.

  When the upload session has been successfully started, upload the database to the upload URL returned in the response. The database can be uploaded to the upload URL in parts using the PUT /snapshots/uploads/{session-id} endpoint. After uploading all the parts you must call the POST /snapshots/uploads/{session-id} endpoint to complete the upload session.

• snapshots.uploadPart

  Upload a database representing a snapshot of a codebase. The database is sent in one or more parts. Each part is sent in the request body. Use the POST /snapshots/{project-id}/{language} endpoint to start an upload session before uploading a database part. Database parts must have been generated and prepared for upload using the CodeQL CLI or the QL command-line tools. For further information on exporting externally-built databases, see Preparing snapshots to upload to LGTM.

  Split large databases into multiple parts. Upload the parts by making a separate request for each part. Don't upload the next part until you've successfully uploaded the previous part.

  If the upload fails you should retry it with the same data.

• system.getHealth

  Return an indication of whether the application is working as expected (up) or needs attention (down). > The description and details fields are reported only if the request includes an access token for a user account that has administration rights for this LGTM server.

• system.getMetric

  LGTM administrators can download usage data using this endpoint. The response includes up to 1000 values for the specified metric and reports the date-time that each value was calculated. There is normally one value per day.

• system.getMetrics

  LGTM administrators can use this endpoint to list the usage metrics that are available to download.

• openapi.previewSpec

  Preview an OpenAPI document before adding it as a source

• openapi.addSource

  Add an OpenAPI source and register its operations as tools