Skip to content

Latest commit

 

History

History
608 lines (514 loc) · 22.7 KB

quickstart.mdx

File metadata and controls

608 lines (514 loc) · 22.7 KB
title description keywords metaTitle metaDescription
Quickstart
Get started with the Greptile API
Greptile API, AI code analysis, codebase understanding, API setup, GitHub integration, code querying
Greptile API Quickstart: Setup AI-Powered Code Analysis in Minutes
Learn how to set up Greptile API for AI-powered code analysis. Configure permissions, index your codebase, and start querying in natural language.

This guide will help you set up the Greptile API to answer hard questions about your codebase. There are only three steps, setting up permissions, indexing, and querying.

Base URL: https://api.greptile.com/v2/.

Permissions

You'll need a Greptile API key and a GitHub token, such as a personal access token, or tokens from GitHub Apps or GitHub OAuth apps. For this example, we will use a PAT to authenticate requests.

  1. Greptile API key -- Click here to get your Greptile key. You will need to log in via GitHub or Microsoft.

  2. GitHub Token -- Click here to generate a PAT. Greptile needs read access to your GitHub repositories, in order to index them. You can provision a GitHub PAT by following this guide from GitHub. Make sure to select the repo scope when creating the token, as this is required for Greptile to clone your repositories. Support for GitLab and Azure DevOps is coming soon! You can also use other types of GitHub tokens, such as GitHub Apps or GitHub OAuth apps.

Indexing

Before Greptile can search and answer questions about a repository, it must be indexed. This can take 3-5 minutes for small repositories, and over an hour for bigger ones, but you only need to do this once. Each index that Greptile generates is stored in our database.

  1. Submit a repository for indexing

You can use the POST /repositories endpoint to submit a repository indexing job.

```json // POST https://api.greptile.com/v2/repositories // Headers: // Authorization: Bearer {GREPTILE_API_KEY} // X-Github-Token: {GITHUB_TOKEN} // Content-Type: application/json 
    {
        "remote": "github",
        "repository": "pandas-dev/pandas",
        "branch": "main"
        // ... see API reference for optional fields
    }
    ```
</Accordion>

<Accordion title="Sample response">

    ```json
    // 200

    {
        "response": "started repo processing"
    }
    ```
</Accordion>

export GREPTILE_API_KEY="your-greptile-api-key"
export GITHUB_TOKEN="your-github-token"

curl -X POST \
  https://api.greptile.com/v2/repositories \
  -H "Authorization: Bearer $GREPTILE_API_KEY" \
  -H "X-Github-Token: $GITHUB_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
      "remote": "github",
      "repository": "pandas-dev/pandas",
      "branch": "main"
  }'
const greptile_api_key = "your-greptile-api-key";
const github_token = "your-github-token";

const repository_payload = {
    remote: "github",
    repository: "pandas-dev/pandas"
};

fetch('https://api.greptile.com/v2/repositories', {
    method: 'POST',
    headers: {
        'Authorization': `Bearer ${greptile_api_key}`,
        'X-Github-Token': github_token,
        'Content-Type': 'application/json'
    },
    body: JSON.stringify(repository_payload)
})
.then(response => response.json())
.then(data => console.log(data))
.catch(error => console.error('Error:', error));
import requests

greptile_api_key = "your-greptile-api-key"
github_token = "your-github-token"

url = 'https://api.greptile.com/v2/repositories'
headers = {
    'Authorization': f'Bearer {greptile_api_key}',
    'X-Github-Token': github_token,
    'Content-Type': 'application/json'
}
payload = {
    "remote": "github",
    "repository": "pandas-dev/pandas",
    "branch": "main"
}

response = requests.post(url, json=payload, headers=headers)
print(response.json())
package main

import (
  "bytes"
  "encoding/json"
  "fmt"
  "net/http"
)

func main() {
  greptile_api_key := "your-greptile-api-key"
  github_token := "your-github-token"

  repository_data := map[string]string{
    "remote":     "github",
    "repository": "pandas-dev/pandas",
    "branch": "main",
  }
  repository_payload, _ := json.Marshal(repository_data)

  repository_req, _ := http.NewRequest("POST", "https://api.greptile.com/v2/repositories", bytes.NewBuffer(repository_payload))
  repository_req.Header.Set("Authorization", fmt.Sprintf("Bearer %s", greptile_api_key))
  repository_req.Header.Set("X-Github-Token", github_token)
  repository_req.Header.Set("Content-Type", "application/json")

  repository_client := &http.Client{}
  repository_resp, _ := repository_client.Do(repository_req)
  defer repository_resp.Body.Close()

  fmt.Println("Response Status:", repository_resp.Status)
}

See our API Reference for more details and to send test requests.

  1. Check repository indexing progress

You can use the GET /repositories/{repositoryId} endpoint to check the status of a repository's index. The repositoryId should be URL-encoded in the format remote:branch:owner/repository.

```json // GET https://api.greptile.com/v2/repositories/github%3Amain%3Apandas-dev%2Fpandas // Headers: // Authorization: Bearer {GREPTILE_API_KEY} // X-Github-Token: {GITHUB_TOKEN} // Content-Type: application/json ``` 
<Accordion title="Sample response">

    ```json
    // 200

    {
      "repository": "pandas-dev/pandas",
      "remote": "github",
      "branch": "main",
      "private": false,
      "status": "submitted",
      "filesProcessed": 0,
      "numFiles": 26083,
      "sampleQuestions": [],
      "sha": "89b286a699b2d023b7a1ebc468abf230d84ad547"
    }
    ```
</Accordion>

export GREPTILE_API_KEY="your-greptile-api-key"
export GITHUB_TOKEN="your-github-token"

curl -X GET \
  https://api.greptile.com/v2/repositories/github%3Amain%3Apandas-dev%2Fpandas \
  -H "Authorization: Bearer $GREPTILE_API_KEY" \
  -H "X-Github-Token: $GITHUB_TOKEN"
const greptile_api_key = "your-greptile-api-key";
const github_token = "your-github-token";

const repository_identifier = encodeURIComponent("github:main:pandas-dev/pandas");

fetch(`https://api.greptile.com/v2/repositories/${repository_identifier}`, {
    method: 'GET',
    headers: {
        'Authorization': `Bearer ${greptile_api_key}`,
        'X-Github-Token': github_token
    }
})
.then(response => response.json())
.then(data => console.log(data))
.catch(error => console.error('Error:', error));
import requests

greptile_api_key = "your-greptile-api-key"
github_token = "your-github-token"

repository_identifier = "github%3Amain%3Apandas-dev%2Fpandas"

url = f'https://api.greptile.com/v2/repositories/{repository_identifier}'
headers = {
    'Authorization': f'Bearer {greptile_api_key}',
    'X-Github-Token': github_token
}

response = requests.get(url, headers=headers)
print(response.json())
package main

import (
  "fmt"
  "net/http"
  "io/ioutil"
)

func main() {
  greptile_api_key := "your-greptile-api-key"
  github_token := "your-github-token"

  repository_identifier := "github%3Amain%3Apandas-dev%2Fpandas"

  repository_req, _ := http.NewRequest("GET", fmt.Sprintf("https://api.greptile.com/v2/repositories/%s", repository_identifier), nil)
  repository_req.Header.Set("Authorization", fmt.Sprintf("Bearer %s", greptile_api_key))
  repository_req.Header.Set("X-Github-Token", github_token)
  repository_req.Header.Set("Content-Type", "application/json")

  repository_client := &http.Client{}
  repository_resp, _ := repository_client.Do(repository_req)
  defer repository_resp.Body.Close()

  body, _ := ioutil.ReadAll(repository_resp.Body)
  body_string := string(body)
  fmt.Println(body_string)
}

The JSON response has a status field which should be one of the following options:

  • submitted: the job is in queue.
  • cloning: the repository is being cloned to ephemeral storage to begin indexing.
  • processing: indexing is in progress. This is the longest step.
  • completed: the repository index is ready to be queried!

If there is a sha in the response, it means the repository has been indexed and is ready to be queried. We may just be processing updates from a newer commit.

See our API Reference for more details and to send test requests.

Query

Now, you can send natural language queries to Greptile! To do this, use the POST /query endpoint. Note that this endpoint is based on the OpenAI Chat format, so the query must be formatted as a messages object, which can simply have length 1.

```json // POST https://api.greptile.com/v2/query // Headers: // Authorization: Bearer {GREPTILE_API_KEY} // X-Github-Token: {GITHUB_TOKEN} // Content-Type: application/json 
    {
        "messages": [
            {
                "id": "some-id-1", // optional, unique identifier for the message
                "content": "Where's the code responsible for concatenating dataframes?",
                "role": "user"
            }
        ],
        "repositories": [
            {
                "remote": "github",
                "repository": "pandas-dev/pandas",
                "branch": "main"
            }
        ],
        "sessionId": "test-session-id", // optional
        // "stream": true // optional, set to true to stream results
    }
    ```
</Accordion>

<Accordion title="Sample response (buffered)">

    ```json
    // 200

    {
      "message": "The code responsible for concatenating `DataFrame` objects in the `pandas` library is found in the `concat` function within the `concat.py` file located at `/pandas/core/reshape/concat.py`. The `concat` function orchestrates the concatenation process and can handle both `Series` and `DataFrame` objects.\n\nHere's a simplified view of the relevant part of the `concat` function:\n\n```python\ndef concat(\n    objs: Iterable[Series | DataFrame] | Mapping[HashableT, Series | DataFrame],\n    *,\n    axis: Axis = 0,\n    join: str = \"outer\",\n    ignore_index: bool = False,\n    keys: Iterable[Hashable] | None = None,\n    levels=None,\n    names: list[HashableT] | None = None,\n    verify_integrity: bool = False,\n    sort: bool = False,\n    copy: bool | None = None,\n) -> DataFrame | Series:\n    \"\"\"\n    Concatenate pandas objects along a particular axis with optional set logic\n    along the other axes.\n    \"\"\"\n    # ... (some code omitted for brevity)\n\n    op = _Concatenator(\n        objs,\n        axis=axis,\n        ignore_index=ignore_index,\n        join=join,\n        keys=keys,\n        levels=levels,\n        names=names,\n        verify_integrity=verify_integrity,\n        sort=sort,\n    )\n\n    return op.get_result()\n```\n\nThe `concat` function initializes an instance of the `_Concatenator` class with the provided parameters and then calls its `get_result` method to perform the actual concatenation.\n\nThe `_Concatenator` class contains the logic to handle the concatenation of `DataFrame` objects, taking into account the axis, join method, whether to ignore the index, and other parameters. The `get_result` method of `_Concatenator` orchestrates the concatenation operation for `BlockManagers`, which are the internal data structures that hold the actual data within a `DataFrame`.\n\nFor a detailed understanding, you would need to look into the `_Concatenator` class and its methods, particularly `get_result`, which is where the concatenation of `DataFrame` objects is executed.",
      "sources": [
        {
          "repository": "pandas-dev/pandas",
          "remote": "github",
          "branch": "main",
          "filepath": "/pandas/core/reshape/concat.py",
          "linestart": null,
          "lineend": null,
          "summary": "The code file is a part of the pandas library and contains functions and classes related to concatenating pandas objects, such as DataFrames and Series.\n\n- The file starts with import statements for various modules and classes.\n- It defines the `concat` function, which is used to concatenate pandas objects along a specified axis. The function has multiple overloaded versions, each with different parameter types and return types. The function takes in parameters such as `objs` (iterable or mapping of Series or DataFrame objects), `axis` (axis to concatenate along), `join` (how to handle indexes on other axes), `ignore_index` (whether to use the index values along the concatenation axis), `keys` (used to construct a hierarchical index), `levels` (specific levels to use for constructing a MultiIndex), `names` (names for the levels in the resulting hierarchical index), `verify_integrity` (whether the new concatenated axis contains duplicates), `sort` (whether to sort the non-concatenation axis), and `copy` (whether to copy data unnecessarily). The function returns a DataFrame or Series object depending on the concatenation axis. The function also provides examples and additional information on how to use it.\n- The file also includes a class `_Concatenator` that orchestrates a concatenation operation for BlockManagers. It has several methods, including `_get_result_dim`, `new_axes`, `_get_comb_axis`, `_get_concat_axis`, and `_maybe_check_integrity`.\n- There are also helper functions `_concat_indexes` and `_make_concat_multiindex` that are used internally for concatenation operations. `_concat_indexes` appends multiple indexes together, while `_make_concat_multiindex` creates a MultiIndex object based on the provided keys, levels, and names.\n\nOverall, the file provides the functionality to concatenate pandas objects along different axes and handle various parameters and options for the concatenation process."
        }
      ]
    }
    ```
</Accordion>

<Accordion title="Sample response (streamed)">
  ```json
  {
    "type": "status",
    "message": "Received request"
  }
  {
    "type": "status",
    "message": "Started processing request"
  }
  {
    "type": "status",
    "message": "Identifying relevant sources"
  }
  {
    "type": "status",
    "message": "Retrieving sources"
  }
  {
    "type": "sources",
    "message": [
      {
        "repository": "pandas-dev/pandas",
        "remote": "github",
        "branch": "main",
        "filepath": "/pandas/core/reshape/concat.py",
        "linestart": null,
        "lineend": null,
        "summary": "The code file is a part of the pandas library and contains functions and classes related to concatenating pandas objects, such as DataFrames and Series.\n\n- The file starts with import statements for various modules and classes.\n- It defines the `concat` function, which is used to concatenate pandas objects along a specified axis. The function has multiple overloaded versions, each with different parameter types and return types. The function takes in parameters such as `objs` (iterable or mapping of Series or DataFrame objects), `axis` (axis to concatenate along), `join` (how to handle indexes on other axes), `ignore_index` (whether to use the index values along the concatenation axis), `keys` (used to construct a hierarchical index), `levels` (specific levels to use for constructing a MultiIndex), `names` (names for the levels in the resulting hierarchical index), `verify_integrity` (whether the new concatenated axis contains duplicates), `sort` (whether to sort the non-concatenation axis), and `copy` (whether to copy data unnecessarily). The function returns a DataFrame or Series object depending on the concatenation axis. The function also provides examples and additional information on how to use it.\n- The file also includes a class `_Concatenator` that orchestrates a concatenation operation for BlockManagers. It has several methods, including `_get_result_dim`, `new_axes`, `_get_comb_axis`, `_get_concat_axis`, and `_maybe_check_integrity`.\n- There are also helper functions `_concat_indexes` and `_make_concat_multiindex` that are used internally for concatenation operations. `_concat_indexes` appends multiple indexes together, while `_make_concat_multiindex` creates a MultiIndex object based on the provided keys, levels, and names.\n\nOverall, the file provides the functionality to concatenate pandas objects along different axes and handle various parameters and options for the concatenation process."
      }
    ]
  }
  {
    "type": "status",
    "message": "Writing response"
  }
  {
    "type": "message",
    "message": "The"
  }
  {
    "type": "message",
    "message": " code"
  }
  {
    "type": "message",
    "message": " responsible"
  }
  {
    "type": "message",
    "message": " for"
  }
  {
    "type": "message",
    "message": " concaten"
  }
  {
    "type": "message",
    "message": "ating"
  }
  {
    "type": "message",
    "message": " Data"
  }
  {
    "type": "message",
    "message": "Frames"
  }
  {
    "type": "message",
    "message": " in"
  }
  {
    "type": "message",
    "message": " the"
  }
  // ...message chunks omitted
  {
    "type": "message",
    "message": " with"
  }
  {
    "type": "message",
    "message": " to"
  }
  {
    "type": "message",
    "message": " concatenate"
  }
  {
    "type": "message",
    "message": " their"
  }
  {
    "type": "message",
    "message": " data"
  }
  {
    "type": "message",
    "message": "."
  }
  {
    "type": "status",
    "message": ""
  }
  ```
</Accordion>

export GREPTILE_API_KEY="your-greptile-api-key"
export GITHUB_TOKEN="your-github-token"

curl -X POST \
  https://api.greptile.com/v2/query \
  -H "Authorization: Bearer $GREPTILE_API_KEY" \
  -H "X-Github-Token: $GITHUB_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
      "messages": [
          {
              "id": "some-id-1",
              "content": "Where'\''s the code responsible for concatenating dataframes?",
              "role": "user"
          }
      ],
      "repositories": [
          {
              "remote": "github",
              "repository": "pandas-dev/pandas",
              "branch": "main"
          }
      ],
      "sessionId": "test-session-id" // optional
  }'
const greptileApiKey = "your-greptile-api-key";
const githubToken = "your-github-token";

const queryPayload = {
    messages: [
        {
            id: "some-id-1",
            content: "Where's the code responsible for concatenating dataframes?",
            role: "user"
        }
    ],
    repositories: [
        {
            remote: "github",
            repository: "pandas-dev/pandas",
            branch: "main"
        }
    ],
    sessionId: "test-session-id" // optional
};

fetch('https://api.greptile.com/v2/query', {
    method: 'POST',
    headers: {
        'Authorization': `Bearer ${greptileApiKey}`,
        'X-Github-Token': githubToken,
        'Content-Type': 'application/json'
    },
    body: JSON.stringify(queryPayload)
})
.then(response => response.json())
.then(data => console.log(data))
.catch(error => console.error('Error:', error));
import requests

greptile_api_key = "your-greptile-api-key"
github_token = "your-github-token"

url = 'https://api.greptile.com/v2/query'
headers = {
    'Authorization': f'Bearer {greptile_api_key}',
    'X-Github-Token': github_token,
    'Content-Type': 'application/json'
}
payload = {
    "messages": [
        {
            "id": "some-id-1",
            "content": "Where's the code responsible for concatenating dataframes?",
            "role": "user"
        }
    ],
    "repositories": [
        {
            "remote": "github",
            "repository": "pandas-dev/pandas",
            "branch": "main"
        }
    ],
    "sessionId": "test-session-id" // optional
}

response = requests.post(url, json=payload, headers=headers)
print(response.json())
package main

import (
  "bytes"
  "encoding/json"
  "fmt"
  "net/http"
  "io/ioutil"
)

func main() {
  greptileApiKey := "your-greptile-api-key"
  githubToken := "your-github-token"

  queryData := map[string]interface{}{
    "messages": []map[string]string{
      {
        "id":      "some-id-1",
        "content": "Where's the code responsible for concatenating dataframes?",
        "role":    "user",
      },
    },
    "repositories": []map[string]string{
      {
        "repository":   "pandas-dev/pandas",
        "branch": "main",
      },
    },
    "sessionId": "test-session-id",  // optional
  }
  queryPayload, _ := json.Marshal(queryData)

  queryReq, _ := http.NewRequest("POST", "https://api.greptile.com/v2/query", bytes.NewBuffer(queryPayload))
  queryReq.Header.Set("Authorization", fmt.Sprintf("Bearer %s", greptileApiKey))
  queryReq.Header.Set("X-Github-Token", githubToken)
  queryReq.Header.Set("Content-Type", "application/json")

  queryClient := &http.Client{}
  queryResp, _ := queryClient.Do(queryReq)
  defer queryResp.Body.Close()

  body, _ := ioutil.ReadAll(queryResp.Body)
  bodyString := string(body)
  fmt.Println(bodyString)
}

See our API Reference for more details and to send test requests.

Need inspiration? Check out some examples of what you can build with Greptile.

If you have any questions, please reach out to us at [email protected].