{ "openapi": "3.0.3", "info": { "title": "Sourcebot Public API", "version": "v5.1.6", "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." }, "tags": [ { "name": "Search & Navigation", "description": "Code search and symbol navigation endpoints." }, { "name": "Repositories", "description": "Repository listing and metadata endpoints." }, { "name": "Git", "description": "Git history, diff, and file content endpoints." }, { "name": "System", "description": "System health and version endpoints." }, { "name": "Enterprise (EE)", "description": "Enterprise endpoints for user management and audit logging." } ], "security": [ { "bearerToken": [] }, { "apiKeyHeader": [] }, {} ], "components": { "schemas": { "PublicSearchResponse": { "type": "object", "properties": { "stats": { "type": "object", "properties": { "actualMatchCount": { "type": "number" }, "totalMatchCount": { "type": "number" }, "duration": { "type": "number" }, "fileCount": { "type": "number" }, "filesSkipped": { "type": "number" }, "contentBytesLoaded": { "type": "number" }, "indexBytesLoaded": { "type": "number" }, "crashes": { "type": "number" }, "shardFilesConsidered": { "type": "number" }, "filesConsidered": { "type": "number" }, "filesLoaded": { "type": "number" }, "shardsScanned": { "type": "number" }, "shardsSkipped": { "type": "number" }, "shardsSkippedFilter": { "type": "number" }, "ngramMatches": { "type": "number" }, "ngramLookups": { "type": "number" }, "wait": { "type": "number" }, "matchTreeConstruction": { "type": "number" }, "matchTreeSearch": { "type": "number" }, "regexpsConsidered": { "type": "number" }, "flushReason": { "type": "string" } }, "required": [ "actualMatchCount", "totalMatchCount", "duration", "fileCount", "filesSkipped", "contentBytesLoaded", "indexBytesLoaded", "crashes", "shardFilesConsidered", "filesConsidered", "filesLoaded", "shardsScanned", "shardsSkipped", "shardsSkippedFilter", "ngramMatches", "ngramLookups", "wait", "matchTreeConstruction", "matchTreeSearch", "regexpsConsidered", "flushReason" ] }, "files": { "type": "array", "items": { "type": "object", "properties": { "fileName": { "type": "object", "properties": { "text": { "type": "string" }, "matchRanges": { "type": "array", "items": { "type": "object", "properties": { "start": { "type": "object", "properties": { "byteOffset": { "type": "number" }, "lineNumber": { "type": "number" }, "column": { "type": "number" } }, "required": [ "byteOffset", "lineNumber", "column" ] }, "end": { "type": "object", "properties": { "byteOffset": { "type": "number" }, "lineNumber": { "type": "number" }, "column": { "type": "number" } }, "required": [ "byteOffset", "lineNumber", "column" ] } }, "required": [ "start", "end" ] } } }, "required": [ "text", "matchRanges" ] }, "webUrl": { "type": "string" }, "externalWebUrl": { "type": "string" }, "repository": { "type": "string" }, "repositoryId": { "type": "number" }, "language": { "type": "string" }, "chunks": { "type": "array", "items": { "type": "object", "properties": { "content": { "type": "string" }, "matchRanges": { "type": "array", "items": { "type": "object", "properties": { "start": { "type": "object", "properties": { "byteOffset": { "type": "number" }, "lineNumber": { "type": "number" }, "column": { "type": "number" } }, "required": [ "byteOffset", "lineNumber", "column" ] }, "end": { "type": "object", "properties": { "byteOffset": { "type": "number" }, "lineNumber": { "type": "number" }, "column": { "type": "number" } }, "required": [ "byteOffset", "lineNumber", "column" ] } }, "required": [ "start", "end" ] } }, "contentStart": { "type": "object", "properties": { "byteOffset": { "type": "number" }, "lineNumber": { "type": "number" }, "column": { "type": "number" } }, "required": [ "byteOffset", "lineNumber", "column" ] }, "symbols": { "type": "array", "items": { "type": "object", "properties": { "symbol": { "type": "string" }, "kind": { "type": "string" }, "parent": { "type": "object", "properties": { "symbol": { "type": "string" }, "kind": { "type": "string" } }, "required": [ "symbol", "kind" ] } }, "required": [ "symbol", "kind" ] } } }, "required": [ "content", "matchRanges", "contentStart" ] } }, "branches": { "type": "array", "items": { "type": "string" } }, "content": { "type": "string" } }, "required": [ "fileName", "webUrl", "repository", "repositoryId", "language", "chunks" ] } }, "repositoryInfo": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "number" }, "codeHostType": { "type": "string", "enum": [ "github", "gitlab", "gitea", "gerrit", "bitbucketServer", "bitbucketCloud", "genericGitHost", "azuredevops" ] }, "name": { "type": "string" }, "displayName": { "type": "string" }, "webUrl": { "type": "string" } }, "required": [ "id", "codeHostType", "name" ] } }, "isSearchExhaustive": { "type": "boolean" } }, "required": [ "stats", "files", "repositoryInfo", "isSearchExhaustive" ] }, "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." }, "PublicSearchRequest": { "type": "object", "properties": { "query": { "type": "string" }, "matches": { "type": "number" }, "contextLines": { "type": "number" }, "whole": { "type": "boolean" }, "isRegexEnabled": { "type": "boolean" }, "isCaseSensitivityEnabled": { "type": "boolean" } }, "required": [ "query", "matches" ] }, "PublicListReposResponse": { "type": "array", "items": { "type": "object", "properties": { "codeHostType": { "type": "string", "enum": [ "github", "gitlab", "gitea", "gerrit", "bitbucketServer", "bitbucketCloud", "genericGitHost", "azuredevops" ] }, "repoId": { "type": "number" }, "repoName": { "type": "string" }, "webUrl": { "type": "string" }, "repoDisplayName": { "type": "string" }, "externalWebUrl": { "type": "string" }, "imageUrl": { "type": "string" }, "indexedAt": { "type": "string", "nullable": true }, "pushedAt": { "type": "string", "nullable": true }, "defaultBranch": { "type": "string" }, "isFork": { "type": "boolean" }, "isArchived": { "type": "boolean" } }, "required": [ "codeHostType", "repoId", "repoName", "webUrl", "isFork", "isArchived" ] } }, "PublicVersionResponse": { "type": "object", "properties": { "version": { "type": "string" } }, "required": [ "version" ] }, "PublicHealthResponse": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "ok" ] } }, "required": [ "status" ] }, "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" ] }, "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" ] }, "PublicGetTreeRequest": { "type": "object", "properties": { "repoName": { "type": "string" }, "revisionName": { "type": "string" }, "paths": { "type": "array", "items": { "type": "string" } } }, "required": [ "repoName", "revisionName", "paths" ] }, "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" ] }, "PublicFindSymbolsResponse": { "type": "object", "properties": { "stats": { "type": "object", "properties": { "matchCount": { "type": "number" } }, "required": [ "matchCount" ] }, "files": { "type": "array", "items": { "type": "object", "properties": { "fileName": { "type": "string" }, "repository": { "type": "string" }, "repositoryId": { "type": "number" }, "webUrl": { "type": "string" }, "language": { "type": "string" }, "matches": { "type": "array", "items": { "type": "object", "properties": { "lineContent": { "type": "string" }, "range": { "type": "object", "properties": { "start": { "type": "object", "properties": { "byteOffset": { "type": "number" }, "lineNumber": { "type": "number" }, "column": { "type": "number" } }, "required": [ "byteOffset", "lineNumber", "column" ] }, "end": { "type": "object", "properties": { "byteOffset": { "type": "number" }, "lineNumber": { "type": "number" }, "column": { "type": "number" } }, "required": [ "byteOffset", "lineNumber", "column" ] } }, "required": [ "start", "end" ] } }, "required": [ "lineContent", "range" ] } } }, "required": [ "fileName", "repository", "repositoryId", "webUrl", "language", "matches" ] } }, "repositoryInfo": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "number" }, "codeHostType": { "type": "string", "enum": [ "github", "gitlab", "gitea", "gerrit", "bitbucketServer", "bitbucketCloud", "genericGitHost", "azuredevops" ] }, "name": { "type": "string" }, "displayName": { "type": "string" }, "webUrl": { "type": "string" } }, "required": [ "id", "codeHostType", "name" ] } } }, "required": [ "stats", "files", "repositoryInfo" ] }, "PublicFindSymbolsRequest": { "type": "object", "properties": { "symbolName": { "type": "string" }, "language": { "type": "string" }, "revisionName": { "type": "string" }, "repoName": { "type": "string" } }, "required": [ "symbolName" ] }, "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" ] }, "PublicListCommitsResponse": { "type": "array", "items": { "$ref": "#/components/schemas/PublicCommit" } }, "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" ] }, "PublicCommitAuthor": { "type": "object", "properties": { "name": { "type": "string" }, "email": { "type": "string" }, "commitCount": { "type": "integer", "minimum": 0 } }, "required": [ "name", "email", "commitCount" ] }, "PublicListCommitAuthorsResponse": { "type": "array", "items": { "$ref": "#/components/schemas/PublicCommitAuthor" } }, "PublicEeUser": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string", "nullable": true }, "email": { "type": "string" }, "role": { "type": "string", "enum": [ "OWNER", "MEMBER" ] }, "suspendedAt": { "type": "string", "nullable": true, "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "lastActivityAt": { "type": "string", "nullable": true, "format": "date-time" } }, "required": [ "id", "name", "email", "role", "suspendedAt", "createdAt", "updatedAt", "lastActivityAt" ] }, "PublicEeDeleteUserResponse": { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "string" } }, "required": [ "success", "message" ] }, "PublicEeUsersResponse": { "type": "array", "items": { "$ref": "#/components/schemas/PublicEeUser" } }, "PublicEeAuditRecord": { "type": "object", "properties": { "id": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "action": { "type": "string", "description": "The audited action (e.g. `user.read`, `user.delete`, `audit.fetch`)." }, "actorId": { "type": "string" }, "actorType": { "type": "string" }, "targetId": { "type": "string" }, "targetType": { "type": "string" }, "sourcebotVersion": { "type": "string" }, "metadata": { "type": "object", "nullable": true, "additionalProperties": { "nullable": true } }, "orgId": { "type": "number" } }, "required": [ "id", "timestamp", "action", "actorId", "actorType", "targetId", "targetType", "sourcebotVersion", "metadata", "orgId" ] }, "PublicEeAuditResponse": { "type": "array", "items": { "$ref": "#/components/schemas/PublicEeAuditRecord" } }, "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 } }, "parameters": {}, "securitySchemes": { "bearerToken": { "type": "http", "scheme": "bearer", "description": "Bearer authentication header of the form `Bearer `, where `` is your API key." }, "apiKeyHeader": { "type": "apiKey", "in": "header", "name": "X-Sourcebot-Api-Key", "description": "Header of the form `X-Sourcebot-Api-Key: `, where `` is your API key." } } }, "paths": { "/api/search": { "post": { "operationId": "search", "tags": [ "Search & Navigation" ], "summary": "Search code", "description": "Executes a blocking code search and returns all matching file chunks.", "x-mint": { "content": "## Usage\n\nThe `query` field supports literal, regexp, and symbol searches with filters for repository, file, language, branch, and more. See the [search syntax reference](https://docs.sourcebot.dev/docs/features/search/syntax-reference) for the full query language." }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicSearchRequest" } } } }, "responses": { "200": { "description": "Search results.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicSearchResponse" } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiServiceError" } } } }, "500": { "description": "Unexpected search failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiServiceError" } } } } } } }, "/api/repos": { "get": { "operationId": "listRepositories", "tags": [ "Repositories" ], "summary": "List repositories", "description": "Returns a paginated list of repositories indexed by this Sourcebot instance.", "parameters": [ { "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": 30 }, "required": false, "name": "perPage", "in": "query" }, { "schema": { "type": "string", "enum": [ "name", "pushed" ], "default": "name" }, "required": false, "name": "sort", "in": "query" }, { "schema": { "type": "string", "enum": [ "asc", "desc" ], "default": "asc" }, "required": false, "name": "direction", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "query", "in": "query" } ], "responses": { "200": { "description": "Paginated repository list.", "headers": { "X-Total-Count": { "description": "Total number of repositories matching the query across all pages.", "schema": { "type": "integer", "example": 137 } }, "Link": { "description": "Pagination links formatted per RFC 8288. Includes `rel=\"next\"`, `rel=\"prev\"`, `rel=\"first\"`, and `rel=\"last\"` when applicable.", "schema": { "type": "string", "example": "; rel=\"next\", ; rel=\"last\"" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicListReposResponse" } } } }, "400": { "description": "Invalid query parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiServiceError" } } } }, "500": { "description": "Unexpected repository listing failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiServiceError" } } } } } } }, "/api/version": { "get": { "operationId": "getVersion", "tags": [ "System" ], "summary": "Get Sourcebot version", "description": "Returns the currently running Sourcebot version string.", "responses": { "200": { "description": "Current Sourcebot version.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicVersionResponse" } } } } } } }, "/api/health": { "get": { "operationId": "getHealth", "tags": [ "System" ], "summary": "Health check", "responses": { "200": { "description": "Service is healthy.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicHealthResponse" } } } } } } }, "/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.\n\nThe response is split into two parts:\n- `ranges`: contiguous, non-overlapping line ranges, each attributed to a single commit. Ordered by `startLine`.\n- `commits`: commit metadata (hash, date, message, author, optional `previous` pointer for walking back through history) keyed by hash, deduplicated across ranges.\n\nWhole-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/find_definitions": { "post": { "operationId": "findDefinitions", "tags": [ "Search & Navigation" ], "summary": "Find symbol definitions", "description": "Returns all locations in the codebase where the given symbol is defined.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicFindSymbolsRequest" } } } }, "responses": { "200": { "description": "Symbol definition locations.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicFindSymbolsResponse" } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiServiceError" } } } }, "500": { "description": "Unexpected failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiServiceError" } } } } } } }, "/api/find_references": { "post": { "operationId": "findReferences", "tags": [ "Search & Navigation" ], "summary": "Find symbol references", "description": "Returns all locations in the codebase where the given symbol is referenced.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicFindSymbolsRequest" } } } }, "responses": { "200": { "description": "Symbol reference locations.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicFindSymbolsResponse" } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiServiceError" } } } }, "500": { "description": "Unexpected 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" } } } } } } }, "/api/ee/user": { "get": { "operationId": "getUser", "tags": [ "Enterprise (EE)" ], "summary": "Get a user", "description": "Fetches details for a single organization member by `userId`. Only organization owners can access this endpoint.", "x-mint": { "content": "\nThis API is only available with an active Sourcebot license. [More information](/docs/activating-a-subscription).\n" }, "parameters": [ { "schema": { "type": "string", "description": "The ID of the user to retrieve." }, "required": true, "description": "The ID of the user to retrieve.", "name": "userId", "in": "query" } ], "responses": { "200": { "description": "User details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicEeUser" } } } }, "400": { "description": "Missing userId parameter.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiServiceError" } } } }, "403": { "description": "Insufficient permissions or entitlement not enabled.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiServiceError" } } } }, "404": { "description": "User is not a member of this organization.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiServiceError" } } } }, "500": { "description": "Unexpected failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiServiceError" } } } } } }, "delete": { "operationId": "deleteUser", "tags": [ "Enterprise (EE)" ], "summary": "Remove a user from the organization", "description": "Removes a user from the organization, revoking their access and their sessions. Only organization owners can access this endpoint.", "x-mint": { "content": "\nThis API is only available with an active Sourcebot license. [More information](/docs/activating-a-subscription).\n" }, "parameters": [ { "schema": { "type": "string", "description": "The ID of the user to remove." }, "required": true, "description": "The ID of the user to remove.", "name": "userId", "in": "query" } ], "responses": { "200": { "description": "User removed successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicEeDeleteUserResponse" } } } }, "400": { "description": "Missing userId parameter.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiServiceError" } } } }, "403": { "description": "Insufficient permissions, the last active owner cannot be removed, or SCIM provisioning is enabled (membership is managed through your identity provider).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiServiceError" } } } }, "404": { "description": "User is not a member of this organization.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiServiceError" } } } }, "500": { "description": "Unexpected failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiServiceError" } } } } } } }, "/api/ee/users": { "get": { "operationId": "listUsers", "tags": [ "Enterprise (EE)" ], "summary": "List users", "description": "Returns all members of the organization. Only organization owners can access this endpoint.", "x-mint": { "content": "\nThis API is only available with an active Sourcebot license. [More information](/docs/activating-a-subscription).\n" }, "responses": { "200": { "description": "List of organization members.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicEeUsersResponse" } } } }, "403": { "description": "Insufficient permissions or entitlement not enabled.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiServiceError" } } } }, "500": { "description": "Unexpected failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiServiceError" } } } } } } }, "/api/ee/audit": { "get": { "operationId": "listAuditRecords", "tags": [ "Enterprise (EE)" ], "summary": "List audit records", "description": "Returns a paginated list of audit log entries. Only organization owners can access this endpoint.", "x-mint": { "content": "\nThis API is only available with an active Sourcebot license. [More information](/docs/activating-a-subscription).\n" }, "parameters": [ { "schema": { "type": "string", "format": "date-time", "description": "Return records at or after this timestamp (ISO 8601)." }, "required": false, "description": "Return records at or after this timestamp (ISO 8601).", "name": "since", "in": "query" }, { "schema": { "type": "string", "format": "date-time", "description": "Return records at or before this timestamp (ISO 8601)." }, "required": false, "description": "Return records at or before this timestamp (ISO 8601).", "name": "until", "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 audit log.", "headers": { "X-Total-Count": { "description": "Total number of audit records 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/PublicEeAuditResponse" } } } }, "400": { "description": "Invalid query parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiServiceError" } } } }, "403": { "description": "Insufficient permissions or entitlement not enabled.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiServiceError" } } } }, "500": { "description": "Unexpected failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiServiceError" } } } } } } } } }