GitHub models REST API docs (#55288)

Co-authored-by: Roniece Ricardo <33437850+RonRicardo@users.noreply.github.com>
Co-authored-by: Daniel Garman <garman@github.com>
Co-authored-by: SiaraMist <siaramist@github.com>
Co-authored-by: Evan Bonsignori <ebonsignori@github.com>

Author: 5 people

.github/workflows/sync-openapi.yml

@@ -42,14 +42,23 @@ jobs:
           path: rest-api-description
           ref: ${{ inputs.SOURCE_BRANCH }}
 
+      - uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11 # v4.1.1
+        with:
+          # By default, only the most recent commit of the `main` branch
+          # will be checked out
+          repository: github/models-gateway
+          path: models-gateway
+
       - uses: ./.github/actions/node-npm-setup
 
       - name: Sync the REST, Webhooks, and GitHub Apps schemas
         env:
           # Needed for gh
           GITHUB_TOKEN: ${{ secrets.DOCS_BOT_PAT_BASE }}
         run: |
-          npm run sync-rest -- --source-repo rest-api-description --output rest github-apps webhooks rest-redirects
+          npm run sync-rest -- \
+            --source-repos rest-api-description models-gateway \
+            --output rest github-apps webhooks rest-redirects
           git status
           echo "Deleting the cloned github/rest-api-description repo..."
           rm -rf rest-api-description

content/rest/index.md

@@ -73,6 +73,7 @@ children:
   - /meta
   - /metrics
   - /migrations
+  - /models
   - /oauth-authorizations
   - /orgs
   - /packages

content/rest/models/catalog.md

@@ -0,0 +1,17 @@
+---
+title: REST API endpoints for models catalog
+shortTitle: Catalog
+intro: Use the REST API to get a list of models available for use, including details like ID, supported input/output modalities, and rate limits.
+versions: # DO NOT MANUALLY EDIT. CHANGES WILL BE OVERWRITTEN BY A 🤖
+  fpt: '*'
+topics:
+  - API
+autogenerated: rest
+allowTitleToDifferFromFilename: true
+---
+
+## About {% data variables.product.prodname_github_models %} catalog
+
+You can use the REST API to explore available models in the {% data variables.product.prodname_github_models %} catalog.
+
+<!-- Content after this section is automatically generated -->

content/rest/models/index.md

@@ -0,0 +1,12 @@
+---
+title: Models
+topics:
+  - API
+autogenerated: rest
+allowTitleToDifferFromFilename: true
+children:
+  - /catalog
+  - /inference
+versions:
+  fpt: '*'
+---

content/rest/models/inference.md

@@ -0,0 +1,24 @@
+---
+title: REST API endpoints for models inference
+shortTitle: Inference
+intro: Use the REST API to submit a chat completion request to a specified model, with or without organizational attribution.
+versions: # DO NOT MANUALLY EDIT. CHANGES WILL BE OVERWRITTEN BY A 🤖
+  fpt: '*'
+topics:
+  - API
+autogenerated: rest
+allowTitleToDifferFromFilename: true
+---
+
+## About {% data variables.product.prodname_github_models %} inference
+
+You can use the REST API to run inference requests using the {% data variables.product.prodname_github_models %} platform.
+
+The API supports:
+
+* Accessing top models from OpenAI, DeepSeek, Microsoft, Llama, and more.
+* Running chat-based inference requests with full control over sampling and response parameters.
+* Streaming or non-streaming completions.
+* Organizational attribution and usage tracking.
+
+<!-- Content after this section is automatically generated -->

package-lock.json

@@ -266,6 +266,7 @@
     "cookie-parser": "^1.4.7",
     "cuss": "2.2.0",
     "dayjs": "^1.11.13",
+    "dereference-json-schema": "^0.2.1",
     "dotenv": "^16.4.7",
     "escape-string-regexp": "5.0.0",
     "express": "4.21.2",

package.json

@@ -36,7 +36,7 @@ To run the REST pipeline locally:
 
 1. Clone the [`github/rest-api-description`](https://github.com/github/rest-api-description) repository inside your local `docs-internal` repository. 
 1. Set a `GITHUB_TOKEN` in your `.env` with (classic) `repo` scopes & enable SSO for the github org. 
-1. Run `npm run sync-rest -- -s rest-api-description -o rest`. Note, by default `-o rest` is specified, so you can omit it.
+1. Run `npm run sync-rest -- -s rest-api-description models-gateway -o rest`. Note, by default `-o rest` is specified, so you can omit it.
 
 ## About this directory
 

src/rest/README.md

@@ -76,8 +76,13 @@ export function RestCodeSamples({ operation, slug, heading }: Props) {
   // Menu options for the language selector
   const languageSelectOptions: CodeSampleKeys[] = [CodeSampleKeys.curl]
 
-  // Management Console and GHES Manage API operations are not supported by Octokit
-  if (operation.subcategory !== 'management-console' && operation.subcategory !== 'manage-ghes') {
+  // Management Console, GHES Manage API, and GitHub Models
+  // operations are not supported by Octokit
+  if (
+    operation.category !== 'models' &&
+    operation.subcategory !== 'management-console' &&
+    operation.subcategory !== 'manage-ghes'
+  ) {
     languageSelectOptions.push(CodeSampleKeys.javascript)
 
     // Not all examples support the GH CLI language option. If any of

src/rest/components/RestCodeSamples.tsx

@@ -26,6 +26,13 @@ const DEFAULT_ACCEPT_HEADER = {
   isRequired: false,
 }
 
+const REQUIRED_CONTENT_TYPE_HEADER = {
+  name: 'content-type',
+  type: 'string',
+  description: `<p>Setting to <code>application/json</code> is required.</p>`,
+  isRequired: true,
+}
+
 export function RestOperation({ operation }: Props) {
   const titleSlug = slug(operation.title)
   const { t } = useTranslation('rest_reference')
@@ -34,11 +41,13 @@ export function RestOperation({ operation }: Props) {
   const headers =
     operation.subcategory === 'management-console' || operation.subcategory === 'manage-ghes'
       ? []
-      : [DEFAULT_ACCEPT_HEADER]
-  const numPreviews = operation.previews.length
-  const hasStatusCodes = operation.statusCodes.length > 0
-  const hasCodeSamples = operation.codeExamples.length > 0
-  const hasParameters = operation.parameters.length > 0 || operation.bodyParameters.length > 0
+      : operation.subcategory === 'inference'
+        ? [REQUIRED_CONTENT_TYPE_HEADER, DEFAULT_ACCEPT_HEADER]
+        : [DEFAULT_ACCEPT_HEADER]
+  const numPreviews = operation.previews?.length || 0
+  const hasStatusCodes = operation.statusCodes?.length > 0
+  const hasCodeSamples = operation.codeExamples?.length > 0
+  const hasParameters = operation.parameters?.length > 0 || operation.bodyParameters?.length > 0
 
   const anchorRef = useRef<null | HTMLDivElement>(null)