diff --git a/admin-openapi.json b/admin-openapi.json index c743bb01c..7b470dcff 100644 --- 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 new file mode 100644 index 000000000..76676907b --- /dev/null +++ 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 new file mode 100644 index 000000000..ce0892471 --- /dev/null +++ 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 index 50480703b..b4054a294 100644 --- a/api/introduction.mdx +++ b/api/introduction.mdx @@ -15,6 +15,8 @@ The Mintlify REST API enables you to programmatically interact with your documen - [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 @@ The Mintlify REST API enables you to programmatically interact with your documen - **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,7 +37,7 @@ You can create up to 10 API keys per hour per organization. ### 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. diff --git a/docs.json b/docs.json index 9fbf6b45f..1e40ca0e1 100644 --- 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" ] }, {