mintlify · ethanpalm · Feb 10, 2026 · Feb 10, 2026 · Feb 10, 2026 · Feb 10, 2026
diff --git a/admin-openapi.json b/admin-openapi.json
@@ -310,9 +310,277 @@
           }
         }
       }
+    },
+    "/autopilot/{projectId}/suggestions": {
+      "get": {
+        "summary": "Get agent suggestions",
+        "description": "Returns a paginated list of agent suggestions sorted by creation date. Each suggestion includes a title, suggested changes, and source information.",
+        "parameters": [
+          {
+            "name": "projectId",
+            "in": "path",
+            "description": "Your project ID. Can be copied from the [API keys](https://dashboard.mintlify.com/settings/organization/api-keys) page in your dashboard.",
+            "required": true,
+            "schema": {
+              "type": "string"
+            }
+          },
+          {
+            "name": "status",
+            "in": "query",
+            "description": "Filter suggestions by status.",
+            "required": false,
+            "schema": {
+              "type": "string",
+              "enum": ["open", "resolved", "cancelled"]
+            }
+          },
+          {
+            "name": "page",
+            "in": "query",
+            "description": "Page number for pagination.",
+            "required": false,
+            "schema": {
+              "type": "integer",
+              "minimum": 1,
+              "default": 1
+            }
+          },
+          {
+            "name": "limit",
+            "in": "query",
+            "description": "Number of suggestions per page.",
+            "required": false,
+            "schema": {
+              "type": "integer",
+              "minimum": 1,
+              "maximum": 100,
+              "default": 20
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "A list of agent suggestions.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "array",
+                  "items": {
+                    "$ref": "#/components/schemas/AgentSuggestion"
+                  }
+                }
+              }
+            }
+          },
+          "400": {
+            "description": "Invalid query parameters.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Error"
+                }
+              }
+            }
+          },
+          "404": {
+            "description": "Deployment not found.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Error"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/autopilot/{projectId}/suggestions/count": {
+      "get": {
+        "summary": "Get agent suggestions count",
+        "description": "Get the total number of agent suggestions for your documentation project.",
+        "parameters": [
+          {
+            "name": "projectId",
+            "in": "path",
+            "description": "Your project ID. Can be copied from the [API keys](https://dashboard.mintlify.com/settings/organization/api-keys) page in your dashboard.",
+            "required": true,
+            "schema": {
+              "type": "string"
+            }
+          },
+          {
+            "name": "status",
+            "in": "query",
+            "description": "Filter the count by suggestion status.",
+            "required": false,
+            "schema": {
+              "type": "string",
+              "enum": ["open", "resolved", "cancelled"]
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "The count of matching suggestions.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "count": {
+                      "type": "integer",
+                      "description": "The total number of matching suggestions."
+                    }
+                  }
+                }
+              }
+            }
+          },
+          "400": {
+            "description": "Invalid query parameters.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Error"
+                }
+              }
+            }
+          },
+          "404": {
+            "description": "Deployment not found.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Error"
+                }
+              }
+            }
+          }
+        }
+      }
     }
   },
   "components": {
+    "schemas": {
+      "Error": {
+        "type": "object",
+        "properties": {
+          "error": {
+            "type": "string",
+            "description": "A description of the error."
+          }
+        }
+      },
+      "AgentSuggestion": {
+        "type": "object",
+        "properties": {
+          "_id": {
+            "type": "string",
+            "description": "The unique identifier for the suggestion."
+          },
+          "subdomain": {
+            "type": "string",
+            "description": "The subdomain of your documentation project."
+          },
+          "status": {
+            "type": "string",
+            "enum": ["open", "resolved", "cancelled"],
+            "description": "The current status of the suggestion."
+          },
+          "createdAt": {
+            "type": "string",
+            "format": "date-time",
+            "description": "An ISO 8601 timestamp of when the suggestion was created."
+          },
+          "title": {
+            "type": "string",
+            "description": "The title of the suggestion."
+          },
+          "suggestedChanges": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            },
+            "description": "A list of suggested documentation changes."
+          },
+          "prompt": {
+            "type": "string",
+            "description": "The analysis prompt used to generate the suggestion."
+          },
+          "source": {
+            "type": "string",
+            "enum": ["pr", "assistant_message"],
+            "description": "The origin of the suggestion. `pr` indicates the suggestion came from a pull request analysis. `assistant_message` indicates it came from assistant conversation analysis."
+          },
+          "sourceData": {
+            "type": "object",
+            "description": "Source-specific data. The shape depends on the `source` field.",
+            "oneOf": [
+              {
+                "title": "Pull request source",
+                "description": "Returned when `source` is `pr`.",
+                "type": "object",
+                "properties": {
+                  "repo": {
+                    "type": "string",
+                    "description": "The repository in `owner/repo` format."
+                  },
+                  "pullRequestNumber": {
+                    "type": "integer",
+                    "description": "The pull request number."
+                  },
+                  "pullRequestTitle": {
+                    "type": "string",
+                    "description": "The pull request title."
+                  },
+                  "pullRequestUrl": {
+                    "type": "string",
+                    "description": "A URL to the pull request."
+                  }
+                }
+              },
+              {
+                "title": "Assistant message source",
+                "description": "Returned when `source` is `assistant_message`.",
+                "type": "object",
+                "properties": {
+                  "bucketIds": {
+                    "type": "array",
+                    "items": {
+                      "type": "string"
+                    },
+                    "description": "Identifiers for the message buckets analyzed."
+                  },
+                  "exampleMessages": {
+                    "type": "array",
+                    "items": {
+                      "type": "string"
+                    },
+                    "description": "Example user messages from the analysis."
+                  },
+                  "analysisPeriodStart": {
+                    "type": "string",
+                    "format": "date-time",
+                    "description": "The start of the analysis period."
+                  },
+                  "analysisPeriodEnd": {
+                    "type": "string",
+                    "format": "date-time",
+                    "description": "The end of the analysis period."
+                  }
+                }
+              }
+            ]
+          },
+          "linkedSession": {
+            "type": "string",
+            "description": "An optional reference to a linked session."
+          }
+        }
+      }
+    },
     "securitySchemes": {
       "bearerAuth": {
         "type": "http",

diff --git a/api/agent/get-suggestions-count.mdx b/api/agent/get-suggestions-count.mdx
@@ -0,0 +1,8 @@
+---
+openapi: /admin-openapi.json GET /autopilot/{projectId}/suggestions/count
+keywords: ["agent", "suggestions", "count"]
+---
+
+## Usage
+
+Use this endpoint to get the total number of agent suggestions for your documentation project. Optionally filter by status to count only `open`, `resolved`, or `cancelled` suggestions.
diff --git a/api/agent/get-suggestions.mdx b/api/agent/get-suggestions.mdx
@@ -0,0 +1,10 @@
+---
+openapi: /admin-openapi.json GET /autopilot/{projectId}/suggestions
+keywords: ["agent", "suggestions", "documentation improvements"]
+---
+
+## Usage
+
+Use this endpoint to retrieve agent [suggestions](/agent/suggestions) for your documentation project. The agent analyzes pull requests and assistant conversations to surface recommended documentation changes.
+
+Use the `page` and `limit` query parameters to paginate through the results. The results are sorted by creation date with the newest suggestions first.
diff --git a/api/introduction.mdx b/api/introduction.mdx
@@ -4,7 +4,7 @@
 keywords: ["REST API", "endpoints", "API keys"]
 ---

 The Mintlify REST API enables you to programmatically interact with your documentation, trigger updates, embed AI-powered chat experiences, and export analytics data.

 ## Endpoints

@@ -13,8 +13,10 @@
 - [Create agent job](/api/agent/create-agent-job): Create an agent job to automatically edit your documentation.
 - [Get agent job](/api/agent/get-agent-job): Retrieve the details and status of a specific agent job.
 - [Get all agent jobs](/api/agent/get-all-jobs): Retrieve all agent jobs for a domain.
 - [Generate assistant message](/api/assistant/create-assistant-message): Embed the assistant, trained on your docs, into any application of your choosing.
 - [Search documentation](/api/assistant/search): Search through your documentation.
+- [Get agent suggestions](/api/autopilot/get-suggestions): Retrieve agent suggestions for documentation improvements.
+- [Get agent suggestions count](/api/autopilot/get-suggestions-count): Get the total number of agent suggestions.
 - [Get user feedback](/api/analytics/feedback): Export user feedback from your documentation.
 - [Get assistant conversations](/api/analytics/assistant-conversations): Export AI assistant conversation history.
 
@@ -24,6 +26,7 @@
 - **CI/CD integration**: Update documentation as part of your deployment pipeline when code changes with [Trigger update](/api/update/trigger).
 - **Custom integrations**: Embed the AI assistant into your product, support portal, or internal tools with [Generate assistant message](/api/assistant/create-assistant-message) and [Search documentation](/api/assistant/search).
 - **Automated editing**: Use agent jobs to programmatically update documentation at scale with [Create agent job](/api/agent/create-agent-job), [Get agent job](/api/agent/get-agent-job), and [Get all agent jobs](/api/agent/get-all-jobs).
+- **Agent suggestions**: Access AI-generated suggestions to improve your documentation based on merged pull requests and assistant conversations with [Get agent suggestions](/api/autopilot/get-suggestions).
 - **Analytics export**: Export feedback and assistant conversations for external analysis with [Get user feedback](/api/analytics/feedback) and [Get assistant conversations](/api/analytics/assistant-conversations).
 
 ## Authentication
@@ -34,11 +37,11 @@
 
 ### Admin API key
 
-Use the admin API key to authenticate requests to [Trigger update](/api/update/trigger), [Get update status](/api/update/status), [Create agent job](/api/agent/create-agent-job), [Get agent job](/api/agent/get-agent-job), [Get all agent jobs](/api/agent/get-all-jobs), [Get user feedback](/api/analytics/feedback), and [Get assistant conversations](/api/analytics/assistant-conversations).
+Use the admin API key to authenticate requests to [Trigger update](/api/update/trigger), [Get update status](/api/update/status), [Create agent job](/api/agent/create-agent-job), [Get agent job](/api/agent/get-agent-job), [Get all agent jobs](/api/agent/get-all-jobs), [Get agent suggestions](/api/autopilot/get-suggestions), [Get agent suggestions count](/api/autopilot/get-suggestions-count), [Get user feedback](/api/analytics/feedback), and [Get assistant conversations](/api/analytics/assistant-conversations).
 
 Admin API keys begin with the `mint_` prefix. 
 
 The admin API key is a server-side secret. Do not expose it in client-side code.

 ### Assistant API key


diff --git a/docs.json b/docs.json
@@ -334,7 +334,9 @@
                 "pages": [
                   "api/agent/create-agent-job",
                   "api/agent/get-agent-job",
-                  "api/agent/get-all-jobs"
+                  "api/agent/get-all-jobs",
+                  "api/agent/get-suggestions",
+                  "api/agent/get-suggestions-count"
                 ]
               },
               {