Submit a Git repository for indexing and check indexing progress. POST /repositories queues a repo (remote, repository, branch) for processing into a graph and embeddings; GET /repositories/{repositoryId} returns processing status, file counts, and the indexed commit SHA.
openapi: 3.0.1
info:
title: Greptile API
description: >-
Specification of the Greptile API. Greptile indexes Git repositories into a
graph plus embeddings, then answers natural-language questions and searches
over that indexed code. Authentication requires a Greptile API key as a
Bearer token plus a Git provider token (for GitHub, a GitHub personal access
token) supplied in the X-GitHub-Token header so Greptile can read the source.
termsOfService: https://www.greptile.com/legal/terms
contact:
name: Greptile Support
url: https://docs.greptile.com
email: support@greptile.com
version: '2.0'
servers:
- url: https://api.greptile.com/v2
description: Greptile API v2
security:
- bearerAuth: []
gitHubToken: []
tags:
- name: Repositories
description: Submit repositories for indexing and check indexing status.
- name: Query
description: Ask natural-language questions over indexed repositories.
- name: Search
description: Retrieve relevant code locations without a synthesized answer.
paths:
/repositories:
post:
operationId: indexRepository
tags:
- Repositories
summary: Submit a repository for indexing
description: >-
Queues a Git repository (identified by remote, repository, and branch)
for processing into Greptile's graph and embeddings. Indexing is
asynchronous; poll GET /repositories/{repositoryId} until a sha is
present, which indicates the repository is ready to be queried.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/IndexRepositoryRequest'
responses:
'200':
description: Repository accepted for indexing.
content:
application/json:
schema:
$ref: '#/components/schemas/IndexRepositoryResponse'
'401':
$ref: '#/components/responses/Unauthorized'
/repositories/{repositoryId}:
get:
operationId: getRepository
tags:
- Repositories
summary: Get repository indexing status
description: >-
Returns metadata and indexing progress for a previously submitted
repository. The repositoryId is the URL-encoded composite identifier in
the form remote:branch:owner/repository (for example
github%3Amain%3Agreptileai%2Fgreptile).
parameters:
- name: repositoryId
in: path
required: true
description: >-
URL-encoded repository identifier in the form
remote:branch:owner/repository.
schema:
type: string
example: github%3Amain%3Apandas-dev%2Fpandas
responses:
'200':
description: Repository metadata and indexing status.
content:
application/json:
schema:
$ref: '#/components/schemas/Repository'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
description: Repository not found or not yet submitted.
/query:
post:
operationId: queryRepositories
tags:
- Query
summary: Query repositories in natural language
description: >-
Submits a natural-language question against one or more indexed
repositories and returns a synthesized answer plus the source files,
functions, and classes used to construct it. Set stream to true to
receive the answer incrementally as Server-Sent Events. Set genius to
true to use a larger, more accurate model better suited to complex bug
diagnosis (billed at a higher per-query rate).
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/QueryRequest'
responses:
'200':
description: >-
A synthesized answer and supporting sources. When stream is true the
response is a text/event-stream of incremental message and source
chunks instead of a single JSON object.
content:
application/json:
schema:
$ref: '#/components/schemas/QueryResponse'
text/event-stream:
schema:
type: string
description: Server-Sent Events stream of message and sources chunks.
'401':
$ref: '#/components/responses/Unauthorized'
/search:
post:
operationId: searchRepositories
tags:
- Search
summary: Search repositories in natural language
description: >-
Searches one or more indexed repositories in natural language and
returns just the ranked list of relevant files, functions, and classes,
without the synthesized answer produced by /query.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/SearchRequest'
responses:
'200':
description: Ranked list of relevant source locations.
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Source'
'401':
$ref: '#/components/responses/Unauthorized'
components:
securitySchemes:
bearerAuth:
type: http
scheme: bearer
description: 'Greptile API key supplied as `Authorization: Bearer <GREPTILE_API_KEY>`.'
gitHubToken:
type: apiKey
in: header
name: X-GitHub-Token
description: >-
Git provider access token (a GitHub personal access token for GitHub
remotes) Greptile uses to read repository source code.
responses:
Unauthorized:
description: Missing or invalid Greptile API key or Git provider token.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
schemas:
RepositoryRef:
type: object
description: Reference to a specific repository and branch on a Git remote.
required:
- remote
- repository
properties:
remote:
type: string
description: The Git host the repository lives on.
enum:
- github
- gitlab
example: github
repository:
type: string
description: Repository in owner/name form.
example: greptileai/greptile
branch:
type: string
description: Branch to index or query. Defaults to the repository default branch.
example: main
IndexRepositoryRequest:
type: object
required:
- remote
- repository
properties:
remote:
type: string
enum:
- github
- gitlab
example: github
repository:
type: string
example: greptileai/greptile
branch:
type: string
example: main
reload:
type: boolean
description: >-
If true, re-process the repository even if it was already indexed
(picks up new commits).
default: false
notify:
type: boolean
description: If true, email the account owner when indexing completes.
default: false
IndexRepositoryResponse:
type: object
properties:
message:
type: string
example: 'started repo processing'
statusEndpoint:
type: string
description: URL to poll for indexing status.
example: https://api.greptile.com/v2/repositories/github%3Amain%3Agreptileai%2Fgreptile
Repository:
type: object
properties:
repository:
type: string
example: pandas-dev/pandas
remote:
type: string
example: github
branch:
type: string
example: main
private:
type: boolean
example: false
status:
type: string
description: Indexing lifecycle state.
enum:
- submitted
- cloning
- processing
- completed
- failed
example: completed
filesProcessed:
type: integer
example: 26083
numFiles:
type: integer
example: 26083
sha:
type: string
description: >-
Indexed commit SHA. When present, the repository is ready to query.
example: 89b286a699b2d023b7a1ebc468abf230d84ad547
QueryRequest:
type: object
required:
- messages
- repositories
properties:
messages:
type: array
description: >-
Conversation history. For a single question this can contain one
user message.
items:
$ref: '#/components/schemas/Message'
repositories:
type: array
description: One or more indexed repositories to query against.
items:
$ref: '#/components/schemas/RepositoryRef'
sessionId:
type: string
description: >-
Opaque session identifier to maintain conversational context across
multiple queries.
example: session-abc-123
stream:
type: boolean
description: Stream the answer as Server-Sent Events.
default: false
genius:
type: boolean
description: >-
Use a larger, higher-accuracy model. Improves complex reasoning and
bug diagnosis at a higher per-query cost.
default: false
Message:
type: object
required:
- role
- content
properties:
id:
type: string
role:
type: string
enum:
- user
- assistant
- system
example: user
content:
type: string
example: How is authentication handled in this codebase?
QueryResponse:
type: object
properties:
message:
type: string
description: The synthesized natural-language answer.
sources:
type: array
items:
$ref: '#/components/schemas/Source'
SearchRequest:
type: object
required:
- query
- repositories
properties:
query:
type: string
example: where is rate limiting implemented
repositories:
type: array
items:
$ref: '#/components/schemas/RepositoryRef'
sessionId:
type: string
stream:
type: boolean
default: false
Source:
type: object
description: A relevant source location returned by query or search.
properties:
repository:
type: string
example: greptileai/greptile
remote:
type: string
example: github
branch:
type: string
example: main
filepath:
type: string
example: src/auth/middleware.ts
linestart:
type: integer
nullable: true
example: 42
lineend:
type: integer
nullable: true
example: 88
summary:
type: string
description: Summary of the file's contents and relevance.
Error:
type: object
properties:
error:
type: string
message:
type: string