Code Suggestions API

Use this API to access GitLab Duo Code Suggestions.

Generate code completions

  • Status: Experiment
POST /code_suggestions/completions

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

Use the AI abstraction layer to generate code completions.

Requests to this endpoint are proxied to the AI Gateway.

Parameters:

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:

shell
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:

json
{
  "choices": [
    {
      "text": "\n        if self.is_running:\n            self.speed += increment\n            print(\"The car's speed is now",
      "index": 0,
      "finish_reason": "length"
    }
  ],
  "metadata": {
    "model": {
      "engine": "fireworks_ai",
      "name": "codestral-2508",
      "lang": "python",
      "tokens_consumption_metadata": {
        "input_tokens": 64,
        "output_tokens": 24,
        "max_output_tokens_used": false,
        "context_tokens_sent": 0,
        "context_tokens_used": 0
      }
    },
    "timestamp": 1759680000,
    "enabled_feature_flags": [],
    "region": "us-central1"
  },
  "model": {
    "engine": "fireworks_ai",
    "name": "codestral-2508",
    "lang": "python",
    "tokens_consumption_metadata": {
      "input_tokens": 64,
      "output_tokens": 24,
      "max_output_tokens_used": false,
      "context_tokens_sent": 0,
      "context_tokens_used": 0
    }
  }
}

Validate that Code Suggestions is enabled

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:

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:

shell
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 details for the AI Gateway

POST /code_suggestions/direct_access

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

Returns user-specific connection details which can be used by IDEs/clients to send completion requests directly to AI Gateway, including headers that must be proxied to the AI Gateway as well as the required authentication token.

Example request:

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

Example response:

json
{
  "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"
  }
}

Fetch connection details

POST /code_suggestions/connection_details

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

Returns user-specific connection details which can be used by IDEs/clients for telemetry, including metadata about the GitLab instance the user is connected to.

Example request:

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

Example response:

json
{
  "instance_id": "292c3c7c-c5d5-48ec-b4bf-f00b724ce560",
  "instance_version": "18.2",
  "realm": "saas",
  "global_user_id": "Df0Jhs9xlbetQR8YoZCKDZJflhxO0ZBI8uoRzmpnd1w=",
  "host_name": "gitlab.example.com",
  "feature_enablement_type": "duo_pro",
  "saas_duo_pro_namespace_ids": "1000000"
}