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 personal access token (PAT) to authenticate your requests.

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

  2. GitHub Access 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!

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.

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"
  }'

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.

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"

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.

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": [
          {
              "repository": "pandas-dev/pandas",
              "branch": "main"
          }
      ],
      "sessionId": "test-session-id"
  }'

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 support@greptile.com.