openapi.yml

openapi: 3.0.0
info:
  title: Greptile API
  version: '2.0'
  description: API for accessing Greptile services including chat history retrieval, repository processing, and executing queries with streaming support.
servers:
  - url: 'https://api.greptile.com/v2/'

components:
  securitySchemes:
    ApiKeyAuth:
      type: http
      scheme: bearer
    GitHubToken:
      type: apiKey
      in: header
      name: X-GitHub-Token

  schemas:
    ChatLog:
      type: object
      properties:
        userId:
          type: string
        timestamp:
          type: string
        sessionId:
          type: string
        chatLog:
          type: array
          items:
            type: object
            properties:
              content:
                type: string
              role:
                type: string
              sources:
                $ref: '#/components/schemas/SearchResponse'

        repos:
          type: array
          items:
            type: string
        parentId:
          type: string
        title:
          type: string
    Sources:
      type: object
      properties:
        repository:
          type: string
          description: The name of the repository where the file resides.
        remote:
          type: string
          description: The remote service or platform where the repository is hosted.
        branch:
          type: string
          description: The branch of the repository where the file is found.
        filepath:
          type: string
          description: The relative path to the file within the repository.
        linestart:
          type: integer
          description: The starting line number of the code that is relevant, if applicable.
          nullable: true
        lineend:
          type: integer
          description: The ending line number of the code that is relevant, if applicable.
          nullable: true
        summary:
          type: string
          description: A summary or description of the contents and functionalities of the file.

    RepositoryRequest:
      type: object
      properties:
        remote:
          type: string
          description: Supported values are "github" or "gitlab".
        repository:
          type: string
          description: Repository identifier in "owner/repository" format.
        branch:
          type: string
          description: Branch name. Optional, defaults to repository's default branch.
        reload:
          type: boolean
          description: If false, won't reprocess if previously successful. Optional, default true.
        notify:
          type: boolean
          description: Whether to notify the user upon completion. Optional, default true.

    RepositoryResponse:
      type: object
      properties:
        message:
          type: string
          description: Processing status message.
        statusEndpoint:
          type: string
          description: URL to check the status of the repository processing.

    RepositoryInfo:
      type: object
      properties:
        repository:
          type: string
        remote:
          type: string
        branch:
          type: string
        private:
          type: boolean
        status:
          type: string
        filesProcessed:
          type: integer
        numFiles:
          type: integer
        sha:
          type: string

    QueryRequest:
      type: object
      properties:
        messages:
          description: List of chat messages until now. For a single query, include only one entry in the list with a natural language query. 
          type: array
          items:
            type: object
            properties:
              id:
                type: string
              content:
                type: string
              role:
                type: string
        repositories:
          description: List of repos that Greptile should reference while answering your question. 
          type: array
          items:
            type: object
            properties:
              remote:
                type: string
              branch:
                type: string
              repository:
                type: string
        sessionId:
          type: string
          description: Optional, defaults to a new session. Only use this if you intend to need to retrieve chat history later. 
        stream:
          type: boolean
          description: Optional, default false.
        genius:
          type: boolean
          description: Optional, default false. Genius requests are smarter but 8-10 seconds slower, great for complex usecases like reviewing PR and updating technical docs. 

    SearchRequest:
      type: object
      properties:
        query:
          type: string
          description: Natural language search query to find the right code in the repo. 
        repositories:
          type: array
          description: List of repos that Greptile should reference while answering your question.
          items:
            type: object
            properties:
              remote:
                type: string
              branch:
                type: string
              repository:
                type: string
        sessionId:
          type: string
          description: Optional, defaults to a new session. You only need this if you want to retrieve this query/response later. 
        stream:
          type: boolean
          description: Optional, default false.

    QueryResponse:
      type: object
      properties:
        message:
          type: string
        sources:
          $ref: '#/components/schemas/SearchResponse'


    SearchResponse:
      type: array
      items:
        $ref: '#/components/schemas/Sources'

paths:
  /chats/{sessionId}:
    get:
      summary: Retrieve chat history for a given session.
      security:
        - ApiKeyAuth: []
        - ApiKeyAuth: []
          GitHubToken: []
      parameters:
        - in: path
          name: sessionId
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Chat history retrieved successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChatLog'

  /repositories:
    post:
      summary: Process or reprocess a repository.
      security:
        - ApiKeyAuth: []
          GitHubToken: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RepositoryRequest'
      responses:
        '200':
          description: Repository processing started.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RepositoryResponse'

  /repositories/{repositoryId}:
    get:
      summary: Get information about a single repository.
      security:
        - ApiKeyAuth: []
        - ApiKeyAuth: []
          GitHubToken: []
      parameters:
        - in: path
          name: repositoryId
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Repository information retrieved successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RepositoryInfo'

  /query:
    post:
      summary: Execute a query with optional streaming.
      security:
        - ApiKeyAuth: []
          GitHubToken: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/QueryRequest'
      responses:
        '200':
          description: Query executed successfully. Response may be streamed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/QueryResponse'

  /search:
    post:
      summary: Search repositories with natural language queries.
      security:
        - ApiKeyAuth: []
          GitHubToken: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SearchRequest'
      responses:
        '200':
          description: Query executed successfully. Response may be streamed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchResponse'