gitlab-ce/doc/api/code_suggestions.md

stage	group	info	description	title
Create	Code Creation	To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments	Documentation for the REST API for Code Suggestions.	Code Suggestions API

Use this API to access the Code Suggestions feature.

Generate code completions

{{< details >}}

• Status: Experiment

{{< /details >}}

{{< history >}}

• Introduced in GitLab 16.2 with a flag named code_suggestions_completion_api. Disabled by default. This feature is an experiment.
• Requirement to generate a JWT before calling this endpoint was removed in GitLab 16.3.
• Generally available in GitLab 16.8. Feature flag code_suggestions_completion_api removed.
• context and user_instruction attributes introduced in GitLab 17.1 with a flag named code_suggestions_context. Disabled by default.

{{< /history >}}

{{< alert type="flag" >}}

The availability of the context and user_instruction attributes is controlled by a feature flag. For more information, see the history. These attributes are available for testing, but are not ready for production use.

{{< /alert >}}

POST /code_suggestions/completions

{{< alert type="note" >}}

This endpoint rate-limits each user to 60 requests per 1-minute window.

{{< /alert >}}

Use the AI abstraction layer to generate code completions.

Requests to this endpoint are proxied to the AI gateway.

Parameters:

Attribute	Type	Required	Description
current_file	hash	yes	Attributes of file that suggestions are being generated for. See File attributes for a list of strings this attribute accepts.
intent	string	no	The intent of the completion request. This can be either completion or generation.
stream	boolean	no	Whether to stream the response as smaller chunks as they are ready (if applicable). Default: false.
project_path	string	no	The path of the project.
generation_type	string	no	The type of event for generation requests. This can be comment, empty_function, or small_file.
context	array	no	Additional context to be used for Code Suggestions. See Context attributes for a list of parameters this attribute accepts.
user_instruction	string	no	A user's instructions for Code Suggestions.

File attributes

The current_file attribute accepts the following strings:

• file_name - The name of the file. Required.
• content_above_cursor - The content of the file above the current cursor position. Required.
• content_below_cursor - The content of the file below the current cursor position. Optional.

Context attributes

The context attribute accepts a list of elements with the following attributes:

• type - The type of the context element. This can be either file or snippet.
• name - The name of the context element. A name of the file or a code snippet.
• content - The content of the context element. The body of the file or a function.

Example request:

curl --request POST \
  --header "Authorization: Bearer <YOUR_ACCESS_TOKEN>" \
  --data '{
      "current_file": {
        "file_name": "car.py",
        "content_above_cursor": "class Car:\n    def __init__(self):\n        self.is_running = False\n        self.speed = 0\n    def increase_speed(self, increment):",
        "content_below_cursor": ""
      },
      "intent": "completion"
    }' \
  --url "https://gitlab.example.com/api/v4/code_suggestions/completions"

Example response:

{
  "id": "id",
  "model": {
    "engine": "vertex-ai",
    "name": "code-gecko"
  },
  "object": "text_completion",
  "created": 1688557841,
  "choices": [
    {
      "text": "\n        if self.is_running:\n            self.speed += increment\n            print(\"The car's speed is now",
      "index": 0,
      "finish_reason": "length"
    }
  ]
}

Validate that Code Suggestions is enabled

{{< history >}}

• Introduced in GitLab 16.7.

{{< /history >}}

Use this endpoint to validate if either:

• A project has code_suggestions enabled.
• A project's group has code_suggestions enabled in its namespace settings.

POST code_suggestions/enabled

Supported attributes:

Attribute	Type	Required	Description
project_path	string	yes	The path of the project to be validated.

If successful, returns:

• 200 if the feature is enabled.
• 403 if the feature is disabled.

Additionally, returns a 404 if the path is empty or the project does not exist.

Example request:

curl --request POST \
  --url "https://gitlab.example.com/api/v4/code_suggestions/enabled"
  --header "Private-Token: <YOUR_ACCESS_TOKEN>" \
  --header "Content-Type: application/json" \
  --data '{
      "project_path": "group/project_name"
    }' \

Fetch direct connection information

{{< history >}}

• Introduced in GitLab 17.0 with a flag named code_suggestions_direct_completions. Disabled by default.
• Generally available in GitLab 17.2. Feature flag code_suggestions_direct_completions removed.

{{< /history >}}

POST /code_suggestions/direct_access

{{< alert type="note" >}}

This endpoint rate-limits each user to 10 requests per 5-minute window.

{{< /alert >}}

Returns user-specific connection details which can be used by IDEs/clients to send completion requests directly to AI gateway.

Example request:

curl --request POST \
  --header "Authorization: Bearer <YOUR_ACCESS_TOKEN>" \
  --url "https://gitlab.example.com/api/v4/code_suggestions/direct_access"

Example response:

{
  "base_url": "http://0.0.0.0:5052",
  "token": "a valid token",
  "expires_at": 1713343569,
  "headers": {
    "X-Gitlab-Instance-Id": "292c3c7c-c5d5-48ec-b4bf-f00b724ce560",
    "X-Gitlab-Realm": "saas",
    "X-Gitlab-Global-User-Id": "Df0Jhs9xlbetQR8YoZCKDZJflhxO0ZBI8uoRzmpnd1w=",
    "X-Gitlab-Host-Name": "gitlab.example.com"
  }
}