feat(api): document public API authentication (#1038)

Author: KonradStanski

docs/api-reference/sourcebot-public.openapi.json

@@ -3,8 +3,18 @@
   "info": {
     "title": "Sourcebot Public API",
     "version": "v4.16.3",
-    "description": "OpenAPI description for the public Sourcebot REST endpoints used for search, repository listing, and file browsing."
+    "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": [
+    {
+      "bearerAuth": []
+    },
+    {
+      "sourcebotApiKey": []
+    },
+    {}
+  ],
   "tags": [
     {
       "name": "Search",
@@ -512,8 +522,7 @@
         "properties": {
           "version": {
             "type": "string",
-            "description": "Running Sourcebot version.",
-            "example": "v4.15.2"
+            "description": "Running Sourcebot version."
           }
         },
         "required": [
@@ -657,11 +666,25 @@
         "additionalProperties": false
       }
     },
-    "parameters": {}
+    "parameters": {},
+    "securitySchemes": {
+      "bearerAuth": {
+        "type": "http",
+        "scheme": "bearer",
+        "description": "Send either a Sourcebot API key (`sbk_...` or legacy `sourcebot-...`) or, on EE instances with OAuth enabled, an OAuth access token (`sboa_...`) in the Authorization header."
+      },
+      "sourcebotApiKey": {
+        "type": "apiKey",
+        "in": "header",
+        "name": "X-Sourcebot-Api-Key",
+        "description": "Send a Sourcebot API key (`sbk_...` or legacy `sourcebot-...`) in the X-Sourcebot-Api-Key header."
+      }
+    }
   },
   "paths": {
     "/api/search": {
       "post": {
+        "operationId": "search",
         "tags": [
           "Search"
         ],
@@ -712,6 +735,7 @@
     },
     "/api/stream_search": {
       "post": {
+        "operationId": "streamSearch",
         "tags": [
           "Search"
         ],
@@ -763,6 +787,7 @@
     },
     "/api/repos": {
       "get": {
+        "operationId": "listRepositories",
         "tags": [
           "Repositories"
         ],
@@ -878,6 +903,7 @@
     },
     "/api/version": {
       "get": {
+        "operationId": "getVersion",
         "tags": [
           "Misc"
         ],
@@ -898,6 +924,7 @@
     },
     "/api/source": {
       "get": {
+        "operationId": "getFileSource",
         "tags": [
           "Files"
         ],
@@ -974,6 +1001,7 @@
     },
     "/api/tree": {
       "post": {
+        "operationId": "getFileTree",
         "tags": [
           "Files"
         ],
@@ -1043,6 +1071,7 @@
     },
     "/api/files": {
       "post": {
+        "operationId": "listFiles",
         "tags": [
           "Files"
         ],

docs/docs/api-reference/overview.mdx

@@ -7,6 +7,13 @@ You can fetch the OpenAPI document for your Sourcebot instance from `/api/openap
 
 This API reference is generated from the web app's Zod schemas and OpenAPI registry. Mintlify renders it from the checked-in spec at [`/api-reference/sourcebot-public.openapi.json`](/api-reference/sourcebot-public.openapi.json).
 
+For authenticated access, create an API key in Sourcebot from **Settings -> API Keys** and send it with either:
+
+- `X-Sourcebot-Api-Key: sbk_...`
+- `Authorization: Bearer sbk_...`
+
+Some instances may also allow anonymous access for these endpoints. On EE instances with OAuth enabled, bearer tokens with the `sboa_...` prefix are also accepted.
+
 The first documented endpoints include:
 
 - `/api/search`

packages/web/src/openapi/publicApiDocument.ts

@@ -1,6 +1,6 @@
 import { OpenAPIRegistry, OpenApiGeneratorV3 } from '@asteasolutions/zod-to-openapi';
 import type { ZodTypeAny } from 'zod';
-import type { SchemaObject } from 'openapi3-ts/oas30';
+import type { ComponentsObject, SchemaObject, SecuritySchemeObject } from 'openapi3-ts/oas30';
 import {
     publicFileSourceRequestSchema,
     publicFileSourceResponseSchema,
@@ -45,6 +45,20 @@ const publicGetTreeResponseSchema: SchemaObject = {
     additionalProperties: false,
 };
 
+const securitySchemes: Record<string, SecuritySchemeObject> = {
+    bearerAuth: {
+        type: 'http',
+        scheme: 'bearer',
+        description: 'Send either a Sourcebot API key (`sbk_...` or legacy `sourcebot-...`) or, on EE instances with OAuth enabled, an OAuth access token (`sboa_...`) in the Authorization header.',
+    },
+    sourcebotApiKey: {
+        type: 'apiKey',
+        in: 'header',
+        name: 'X-Sourcebot-Api-Key',
+        description: 'Send a Sourcebot API key (`sbk_...` or legacy `sourcebot-...`) in the X-Sourcebot-Api-Key header.',
+    },
+};
+
 function jsonContent(schema: ZodTypeAny | SchemaObject) {
     return {
         'application/json': {
@@ -66,6 +80,7 @@ export function createPublicOpenApiDocument(version: string) {
     registry.registerPath({
         method: 'post',
         path: '/api/search',
+        operationId: 'search',
         tags: [searchTag.name],
         summary: 'Run a blocking code search',
         request: {
@@ -87,6 +102,7 @@ export function createPublicOpenApiDocument(version: string) {
     registry.registerPath({
         method: 'post',
         path: '/api/stream_search',
+        operationId: 'streamSearch',
         tags: [searchTag.name],
         summary: 'Run a streaming code search',
         description: 'Returns a server-sent event stream. Each event data payload is a JSON object describing either a chunk, final summary, or error.',
@@ -113,6 +129,7 @@ export function createPublicOpenApiDocument(version: string) {
     registry.registerPath({
         method: 'get',
         path: '/api/repos',
+        operationId: 'listRepositories',
         tags: [reposTag.name],
         summary: 'List repositories',
         request: {
@@ -147,6 +164,7 @@ export function createPublicOpenApiDocument(version: string) {
     registry.registerPath({
         method: 'get',
         path: '/api/version',
+        operationId: 'getVersion',
         tags: [miscTag.name],
         summary: 'Get Sourcebot version',
         responses: {
@@ -160,6 +178,7 @@ export function createPublicOpenApiDocument(version: string) {
     registry.registerPath({
         method: 'get',
         path: '/api/source',
+        operationId: 'getFileSource',
         tags: [filesTag.name],
         summary: 'Get file contents',
         request: {
@@ -179,6 +198,7 @@ export function createPublicOpenApiDocument(version: string) {
     registry.registerPath({
         method: 'post',
         path: '/api/tree',
+        operationId: 'getFileTree',
         tags: [filesTag.name],
         summary: 'Get a file tree',
         request: {
@@ -201,6 +221,7 @@ export function createPublicOpenApiDocument(version: string) {
     registry.registerPath({
         method: 'post',
         path: '/api/files',
+        operationId: 'listFiles',
         tags: [filesTag.name],
         summary: 'List files in a repository revision',
         request: {
@@ -227,16 +248,26 @@ export function createPublicOpenApiDocument(version: string) {
         info: {
             title: 'Sourcebot Public API',
             version,
-            description: 'OpenAPI description for the public Sourcebot REST endpoints used for search, repository listing, and file browsing.',
+            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: [
+            { bearerAuth: [] },
+            { sourcebotApiKey: [] },
+            {},
+        ],
         tags: [searchTag, reposTag, filesTag, miscTag],
     });
 
-    document.components = document.components ?? {};
-    document.components.schemas = {
-        ...(document.components.schemas ?? {}),
+    const components: ComponentsObject = document.components ?? {};
+    components.schemas = {
+        ...(components.schemas ?? {}),
         PublicFileTreeNode: publicFileTreeNodeSchema,
     };
+    components.securitySchemes = {
+        ...(components.securitySchemes ?? {}),
+        ...securitySchemes,
+    };
+    document.components = components;
 
     return document;
 }

packages/web/src/openapi/publicApiSchemas.ts

@@ -41,7 +41,6 @@ export const publicFileSourceResponseSchema = fileSourceResponseSchema.openapi('
 export const publicVersionResponseSchema = z.object({
     version: z.string().openapi({
         description: 'Running Sourcebot version.',
-        example: 'v4.15.2',
     }),
 }).openapi('PublicVersionResponse');