openapi: 3.0.3
info:
title: Sourcebot Public Enterprise (EE) Enterprise (EE) Git API
version: v5.1.3
description: 'OpenAPI description for the public Sourcebot REST endpoints used for search, repository listing, and file browsing. Authentication is instance-dependent: API keys are the standard integration mechanism, OAuth bearer tokens are EE-only, and some instances may allow anonymous access.'
security:
- bearerToken: []
- apiKeyHeader: []
- {}
tags:
- name: Git
description: Git history, diff, and file content endpoints.
paths:
/api/source:
get:
operationId: getFileSource
tags:
- Git
summary: Get file contents
description: Returns the raw source content of a file at a given repository path and optional git ref.
parameters:
- schema:
type: string
required: true
name: path
in: query
- schema:
type: string
required: true
name: repo
in: query
- schema:
type: string
required: false
name: ref
in: query
responses:
'200':
description: File source and metadata.
content:
application/json:
schema:
$ref: '#/components/schemas/PublicFileSourceResponse'
'400':
description: Invalid query parameters or git ref.
content:
application/json:
schema:
$ref: '#/components/schemas/PublicApiServiceError'
'404':
description: Repository or file not found.
content:
application/json:
schema:
$ref: '#/components/schemas/PublicApiServiceError'
'500':
description: Unexpected file retrieval failure.
content:
application/json:
schema:
$ref: '#/components/schemas/PublicApiServiceError'
/api/blame:
get:
operationId: getFileBlame
tags:
- Git
summary: Get file blame
description: 'Returns blame information for a file at a given repository path and optional git ref.
The response is split into two parts:
- `ranges`: contiguous, non-overlapping line ranges, each attributed to a single commit. Ordered by `startLine`.
- `commits`: commit metadata (hash, date, message, author, optional `previous` pointer for walking back through history) keyed by hash, deduplicated across ranges.
Whole-file renames are followed automatically. Cross-file line moves and copies are not.'
parameters:
- schema:
type: string
description: The file path to blame, relative to the repository root.
required: true
description: The file path to blame, relative to the repository root.
name: path
in: query
- schema:
type: string
description: The fully-qualified repository name.
required: true
description: The fully-qualified repository name.
name: repo
in: query
- schema:
type: string
description: The git ref (branch, tag, or commit SHA) to blame at. Defaults to the repository's default branch.
required: false
description: The git ref (branch, tag, or commit SHA) to blame at. Defaults to the repository's default branch.
name: ref
in: query
responses:
'200':
description: Blame ranges and deduplicated commit metadata.
content:
application/json:
schema:
$ref: '#/components/schemas/PublicFileBlameResponse'
'400':
description: Invalid query parameters or git ref.
content:
application/json:
schema:
$ref: '#/components/schemas/PublicApiServiceError'
'404':
description: Repository or file not found.
content:
application/json:
schema:
$ref: '#/components/schemas/PublicApiServiceError'
'500':
description: Unexpected blame retrieval failure.
content:
application/json:
schema:
$ref: '#/components/schemas/PublicApiServiceError'
/api/tree:
post:
operationId: getFileTree
tags:
- Git
summary: Get a file tree
description: Returns the file tree for a repository at a given revision.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/PublicGetTreeRequest'
responses:
'200':
description: File tree for the requested repository revision.
content:
application/json:
schema:
type: object
properties:
tree:
$ref: '#/components/schemas/PublicFileTreeNode'
required:
- tree
additionalProperties: false
'400':
description: Invalid request body or git ref.
content:
application/json:
schema:
$ref: '#/components/schemas/PublicApiServiceError'
'404':
description: Repository or path not found.
content:
application/json:
schema:
$ref: '#/components/schemas/PublicApiServiceError'
'500':
description: Unexpected tree retrieval failure.
content:
application/json:
schema:
$ref: '#/components/schemas/PublicApiServiceError'
/api/diff:
get:
operationId: getDiff
tags:
- Git
summary: Get diff between two commits
description: Returns a structured diff between two git refs using a two-dot comparison. See [git-diff](https://git-scm.com/docs/git-diff) for details.
parameters:
- schema:
type: string
description: The fully-qualified repository name.
required: true
description: The fully-qualified repository name.
name: repo
in: query
- schema:
type: string
description: The base git ref (branch, tag, or commit SHA) to diff from.
required: true
description: The base git ref (branch, tag, or commit SHA) to diff from.
name: base
in: query
- schema:
type: string
description: The head git ref (branch, tag, or commit SHA) to diff to.
required: true
description: The head git ref (branch, tag, or commit SHA) to diff to.
name: head
in: query
- schema:
type: string
description: Restrict the diff to changes touching this file path. Omit to diff all changes between the two refs.
required: false
description: Restrict the diff to changes touching this file path. Omit to diff all changes between the two refs.
name: path
in: query
responses:
'200':
description: Structured diff between the two refs.
content:
application/json:
schema:
$ref: '#/components/schemas/PublicGetDiffResponse'
'400':
description: Invalid query parameters or git ref.
content:
application/json:
schema:
$ref: '#/components/schemas/PublicApiServiceError'
'404':
description: Repository not found.
content:
application/json:
schema:
$ref: '#/components/schemas/PublicApiServiceError'
'500':
description: Unexpected diff failure.
content:
application/json:
schema:
$ref: '#/components/schemas/PublicApiServiceError'
/api/commits:
get:
operationId: listCommits
tags:
- Git
summary: List commits
description: Returns a paginated list of commits for a repository.
parameters:
- schema:
type: string
description: The fully-qualified repository name.
required: true
description: The fully-qualified repository name.
name: repo
in: query
- schema:
type: string
description: Filter commits by message content (case-insensitive). Interpreted as a POSIX BRE regex — escape metacharacters for literal matching.
required: false
description: Filter commits by message content (case-insensitive). Interpreted as a POSIX BRE regex — escape metacharacters for literal matching.
name: query
in: query
- schema:
type: string
description: Return commits after this date. Accepts ISO 8601 or relative formats (e.g. `30 days ago`).
required: false
description: Return commits after this date. Accepts ISO 8601 or relative formats (e.g. `30 days ago`).
name: since
in: query
- schema:
type: string
description: Return commits before this date. Accepts ISO 8601 or relative formats.
required: false
description: Return commits before this date. Accepts ISO 8601 or relative formats.
name: until
in: query
- schema:
type: string
description: Filter commits by author name or email (case-insensitive). Interpreted as a POSIX BRE regex — escape metacharacters for literal matching.
required: false
description: Filter commits by author name or email (case-insensitive). Interpreted as a POSIX BRE regex — escape metacharacters for literal matching.
name: author
in: query
- schema:
type: string
description: The git ref (branch, tag, or commit SHA) to list commits from. Defaults to `HEAD`.
required: false
description: The git ref (branch, tag, or commit SHA) to list commits from. Defaults to `HEAD`.
name: ref
in: query
- schema:
type: string
description: Restrict commits to those that touch this file path.
required: false
description: Restrict commits to those that touch this file path.
name: path
in: query
- schema:
type: integer
minimum: 0
exclusiveMinimum: true
default: 1
required: false
name: page
in: query
- schema:
type: integer
minimum: 0
exclusiveMinimum: true
maximum: 100
default: 50
required: false
name: perPage
in: query
responses:
'200':
description: Paginated commit list.
headers:
X-Total-Count:
description: Total number of commits matching the query across all pages.
schema:
type: integer
Link:
description: Pagination links formatted per RFC 8288.
schema:
type: string
content:
application/json:
schema:
$ref: '#/components/schemas/PublicListCommitsResponse'
'400':
description: Invalid query parameters.
content:
application/json:
schema:
$ref: '#/components/schemas/PublicApiServiceError'
'404':
description: Repository not found.
content:
application/json:
schema:
$ref: '#/components/schemas/PublicApiServiceError'
'500':
description: Unexpected failure.
content:
application/json:
schema:
$ref: '#/components/schemas/PublicApiServiceError'
/api/commit:
get:
operationId: getCommit
tags:
- Git
summary: Get commit details
description: Returns details for a single commit, including parent commit SHAs.
parameters:
- schema:
type: string
description: The fully-qualified repository name.
required: true
description: The fully-qualified repository name.
name: repo
in: query
- schema:
type: string
description: The git ref (commit SHA, branch, or tag).
required: true
description: The git ref (commit SHA, branch, or tag).
name: ref
in: query
responses:
'200':
description: Commit details.
content:
application/json:
schema:
$ref: '#/components/schemas/PublicCommitDetail'
'400':
description: Invalid query parameters or git ref.
content:
application/json:
schema:
$ref: '#/components/schemas/PublicApiServiceError'
'404':
description: Repository or revision not found.
content:
application/json:
schema:
$ref: '#/components/schemas/PublicApiServiceError'
'500':
description: Unexpected failure.
content:
application/json:
schema:
$ref: '#/components/schemas/PublicApiServiceError'
/api/commits/authors:
get:
operationId: listCommitAuthors
tags:
- Git
summary: List commit authors
description: Returns a paginated list of unique authors who committed in a repository, sorted by commit count descending. Optionally scoped to a file path.
parameters:
- schema:
type: string
description: The fully-qualified repository name.
required: true
description: The fully-qualified repository name.
name: repo
in: query
- schema:
type: string
description: The git ref (branch, tag, or commit SHA) to list authors from. Defaults to `HEAD`.
required: false
description: The git ref (branch, tag, or commit SHA) to list authors from. Defaults to `HEAD`.
name: ref
in: query
- schema:
type: string
description: Restrict authors to those who touched this file path.
required: false
description: Restrict authors to those who touched this file path.
name: path
in: query
- schema:
type: integer
minimum: 0
exclusiveMinimum: true
default: 1
required: false
name: page
in: query
- schema:
type: integer
minimum: 0
exclusiveMinimum: true
maximum: 100
default: 50
required: false
name: perPage
in: query
responses:
'200':
description: Paginated commit author list.
headers:
X-Total-Count:
description: Total number of unique authors matching the query across all pages.
schema:
type: integer
Link:
description: Pagination links formatted per RFC 8288.
schema:
type: string
content:
application/json:
schema:
$ref: '#/components/schemas/PublicListCommitAuthorsResponse'
'400':
description: Invalid query parameters or git ref.
content:
application/json:
schema:
$ref: '#/components/schemas/PublicApiServiceError'
'404':
description: Repository not found.
content:
application/json:
schema:
$ref: '#/components/schemas/PublicApiServiceError'
'500':
description: Unexpected failure.
content:
application/json:
schema:
$ref: '#/components/schemas/PublicApiServiceError'
components:
schemas:
PublicFileSourceResponse:
type: object
properties:
source:
type: string
language:
type: string
path:
type: string
repo:
type: string
repoCodeHostType:
type: string
enum:
- github
- gitlab
- gitea
- gerrit
- bitbucketServer
- bitbucketCloud
- genericGitHost
- azuredevops
repoDisplayName:
type: string
repoExternalWebUrl:
type: string
webUrl:
type: string
externalWebUrl:
type: string
blobSha:
type: string
required:
- source
- language
- path
- repo
- repoCodeHostType
- webUrl
PublicApiServiceError:
type: object
properties:
statusCode:
type: number
errorCode:
type: string
message:
type: string
required:
- statusCode
- errorCode
- message
description: Structured error response returned by Sourcebot public API endpoints.
PublicCommitAuthor:
type: object
properties:
name:
type: string
email:
type: string
commitCount:
type: integer
minimum: 0
required:
- name
- email
- commitCount
PublicFileBlameResponse:
type: object
properties:
ranges:
type: array
items:
type: object
properties:
hash:
type: string
description: The hash of the commit that last modified the lines in this range.
path:
type: string
description: The file path as it existed at the attributing commit. May differ from the current path due to renames.
startLine:
type: integer
minimum: 0
exclusiveMinimum: true
description: The 1-based line number where the range begins (inclusive).
lineCount:
type: integer
minimum: 0
exclusiveMinimum: true
description: The number of contiguous lines in this range.
required:
- hash
- path
- startLine
- lineCount
description: Contiguous, non-overlapping line ranges ordered by startLine. Each range is attributed to a single commit.
commits:
type: object
additionalProperties:
type: object
properties:
hash:
type: string
description: The full commit SHA.
date:
type: string
description: The commit date in ISO 8601 format.
message:
type: string
description: The commit subject line.
authorName:
type: string
authorEmail:
type: string
previous:
type: object
properties:
hash:
type: string
description: The hash of the commit that previously affected these lines (i.e., the next step backwards in the blame walk).
path:
type: string
description: The file path as it existed at the previous commit. May differ from the current path due to renames.
required:
- hash
- path
description: Pointer to the previous commit that affected these lines, with the file path as it existed there. Absent when the commit introduced the lines (no earlier history to walk to).
required:
- hash
- date
- message
- authorName
- authorEmail
description: Commit metadata keyed by hash, deduplicated across ranges.
required:
- ranges
- commits
PublicListCommitAuthorsResponse:
type: array
items:
$ref: '#/components/schemas/PublicCommitAuthor'
PublicCommitDetail:
type: object
properties:
hash:
type: string
description: The full commit SHA.
date:
type: string
description: The commit date in ISO 8601 format.
message:
type: string
description: The commit subject line.
refs:
type: string
description: Refs pointing to this commit (e.g. branch or tag names).
body:
type: string
description: The commit body (everything after the subject line).
authorName:
type: string
authorEmail:
type: string
parents:
type: array
items:
type: string
description: The parent commit SHAs.
required:
- hash
- date
- message
- refs
- body
- authorName
- authorEmail
- parents
PublicGetDiffResponse:
type: object
properties:
files:
type: array
items:
type: object
properties:
oldPath:
type: string
nullable: true
description: The file path before the change. `null` for added files.
newPath:
type: string
nullable: true
description: The file path after the change. `null` for deleted files.
hunks:
type: array
items:
type: object
properties:
oldRange:
type: object
properties:
start:
type: integer
description: The 1-based line number where the range starts.
lines:
type: integer
description: The number of lines the range spans.
required:
- start
- lines
description: The line range in the old file.
newRange:
type: object
properties:
start:
type: integer
description: The 1-based line number where the range starts.
lines:
type: integer
description: The number of lines the range spans.
required:
- start
- lines
description: The line range in the new file.
heading:
type: string
description: Optional context heading extracted from the @@ line, typically the enclosing function or class name.
body:
type: string
description: The diff content, with each line prefixed by a space (context), + (addition), or - (deletion).
required:
- oldRange
- newRange
- body
description: The list of changed regions within the file.
required:
- oldPath
- newPath
- hunks
description: The list of changed files.
required:
- files
PublicGetTreeRequest:
type: object
properties:
repoName:
type: string
revisionName:
type: string
paths:
type: array
items:
type: string
required:
- repoName
- revisionName
- paths
PublicCommit:
type: object
properties:
hash:
type: string
description: The full commit SHA.
date:
type: string
description: The commit date in ISO 8601 format.
message:
type: string
description: The commit subject line.
refs:
type: string
description: Refs pointing to this commit (e.g. branch or tag names).
body:
type: string
description: The commit body (everything after the subject line).
authorName:
type: string
authorEmail:
type: string
required:
- hash
- date
- message
- refs
- body
- authorName
- authorEmail
PublicFileTreeNode:
type: object
properties:
type:
type: string
path:
type: string
name:
type: string
children:
type: array
items:
$ref: '#/components/schemas/PublicFileTreeNode'
required:
- type
- path
- name
- children
additionalProperties: false
PublicListCommitsResponse:
type: array
items:
$ref: '#/components/schemas/PublicCommit'
securitySchemes:
bearerToken:
type: http
scheme: bearer
description: Bearer authentication header of the form `Bearer <token>`, where `<token>` is your API key.
apiKeyHeader:
type: apiKey
in: header
name: X-Sourcebot-Api-Key
description: 'Header of the form `X-Sourcebot-Api-Key: <token>`, where `<token>` is your API key.'