From 53455e3bdb7dafeba1912404fc031bc226340709 Mon Sep 17 00:00:00 2001 From: Ethan Palm <56270045+ethanpalm@users.noreply.github.com> Date: Thu, 4 Jun 2026 16:44:27 -0700 Subject: [PATCH 1/2] deprecate mdx stubs for openAPI spec nav --- admin-openapi.json | 740 +++++++++------- analytics.openapi.json | 63 +- api/agent/create-agent-job.mdx | 23 - api/agent/get-agent-job.mdx | 20 - api/agent/get-all-jobs.mdx | 17 - api/agent/v2/create-agent-job.mdx | 23 - api/agent/v2/get-agent-job.mdx | 10 - api/agent/v2/send-message.mdx | 21 - api/analytics/assistant-caller-stats.mdx | 19 - api/analytics/assistant-conversations.mdx | 25 - api/analytics/feedback-by-page.mdx | 18 - api/analytics/feedback.mdx | 27 - api/analytics/searches.mdx | 17 - api/analytics/views.mdx | 17 - api/analytics/visitors.mdx | 17 - api/assistant/create-assistant-message.mdx | 9 +- api/assistant/get-page-content.mdx | 6 +- api/assistant/search.mdx | 7 +- api/introduction.mdx | 72 +- api/preview/trigger.mdx | 20 - api/update/status.mdx | 6 - api/update/trigger.mdx | 6 - discovery-openapi.json | 48 +- docs.json | 37 +- openapi.json | 310 ------- redirects.json | 966 +++++++++++---------- 26 files changed, 1079 insertions(+), 1465 deletions(-) delete mode 100644 api/agent/create-agent-job.mdx delete mode 100644 api/agent/get-agent-job.mdx delete mode 100644 api/agent/get-all-jobs.mdx delete mode 100644 api/agent/v2/create-agent-job.mdx delete mode 100644 api/agent/v2/get-agent-job.mdx delete mode 100644 api/agent/v2/send-message.mdx delete mode 100644 api/analytics/assistant-caller-stats.mdx delete mode 100644 api/analytics/assistant-conversations.mdx delete mode 100644 api/analytics/feedback-by-page.mdx delete mode 100644 api/analytics/feedback.mdx delete mode 100644 api/analytics/searches.mdx delete mode 100644 api/analytics/views.mdx delete mode 100644 api/analytics/visitors.mdx delete mode 100644 api/preview/trigger.mdx delete mode 100644 api/update/status.mdx delete mode 100644 api/update/trigger.mdx delete mode 100644 openapi.json diff --git a/admin-openapi.json b/admin-openapi.json index c433d51487..4932457721 100644 --- a/admin-openapi.json +++ b/admin-openapi.json @@ -2,7 +2,7 @@ "openapi": "3.0.1", "info": { "title": "Mintlify Admin API", - "description": "An API for administrative operations including documentation updates and agent management.", + "description": "API for managing documentation deployments and agent jobs.", "version": "2.0.0" }, "servers": [ @@ -15,362 +15,325 @@ "bearerAuth": [] } ], + "x-mcp": { + "enabled": true + }, "paths": { - "/v1/agent/{projectId}/job": { + "/v1/project/update/{projectId}": { "post": { - "summary": "Create agent job (v1)", - "deprecated": true, - "description": "Deprecated: use [v2 create agent job](/api/agent/v2/create-agent-job) instead. Creates a new agent job that can generate and edit documentation based on provided messages and branch information.", + "summary": "Trigger update", + "description": "Queue a deployment update for your documentation project. Returns a status ID that you can use with [Get update status](#operation/getUpdateStatus) to track progress. The update deploys from your configured deployment branch.", + "operationId": "triggerUpdate", + "tags": ["Deployments"], "parameters": [ { "name": "projectId", "in": "path", + "description": "Your project ID. Copy it from the [API keys](https://app.mintlify.com/settings/organization/api-keys) page in your dashboard.", "required": true, "schema": { - "type": "string" - }, - "description": "Your project ID. Can be copied from the [API keys](https://app.mintlify.com/settings/organization/api-keys) page in your dashboard." + "type": "string", + "example": "my-project-id" + } } ], - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { - "type": "object", - "required": [ - "messages" - ], - "properties": { - "branch": { - "type": "string", - "description": "The name of the Git branch that the agent should work on. If omitted, the agent generates a branch name based on the message content." - }, - "messages": { - "type": "array", - "description": "A list of messages to provide to the agent. A default system prompt is always prepended automatically, so you typically only need to include user messages.", - "items": { - "type": "object", - "required": [ - "role", - "content" - ], - "properties": { - "role": { - "type": "string", - "enum": ["system", "user", "assistant"], - "description": "The role of the message sender. Use `user` for task instructions. Use `system` to add supplementary instructions that are appended after the default system prompt (does not replace it). Use `assistant` to provide example assistant responses for few-shot prompting." - }, - "content": { - "type": "string", - "description": "The content of the message." - } - } + "responses": { + "202": { + "description": "Update queued successfully.", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "statusId": { + "type": "string", + "description": "The status ID of the triggered update. Pass this to [Get update status](#operation/getUpdateStatus).", + "example": "abc123def456" } - }, - "asDraft": { - "type": "boolean", - "default": false, - "description": "Control whether the pull request is created in draft or non-draft mode. When true, creates a draft pull request. When false (default), creates a regular pull request ready for review." - }, - "model": { - "type": "string", - "enum": ["sonnet", "opus"], - "default": "sonnet", - "description": "The AI model to use for the agent job. Use `sonnet` for faster, cost-effective processing. Use `opus` for more capable, but slower processing." } } } } } }, - "responses": { - "200": { - "description": "Agent job created successfully. Returns a streaming response with Server-Sent Events.", - "headers": { - "X-Session-Id": { - "schema": { - "type": "string" - }, - "description": "Unique session identifier for the created agent job." - }, - "X-Branch-Name": { - "schema": { - "type": "string" - }, - "description": "Git branch name where the agent is making changes." - } - }, - "content": { - "text/event-stream": { - "schema": { - "type": "string", - "description": "Server-Sent Events stream containing the agent job execution details and results." - } - } - } - } + "x-codeSamples": [ + { + "lang": "bash", + "label": "cURL", + "source": "curl -X POST https://api.mintlify.com/v1/project/update/my-project-id \\\n -H \"Authorization: Bearer mint_xxxxx\"" } + ] } }, - "/v1/agent/{projectId}/job/{id}": { + "/v1/project/update-status/{statusId}": { "get": { - "summary": "Get agent job by ID (v1)", - "deprecated": true, - "description": "Deprecated: use [v2 get agent job](/api/agent/v2/get-agent-job) instead. Retrieves the details and status of a specific agent job by its ID.", + "summary": "Get update status", + "description": "Get the status and details of a documentation update by its status ID.", + "operationId": "getUpdateStatus", + "tags": ["Deployments"], "parameters": [ { - "name": "projectId", + "name": "statusId", "in": "path", + "description": "The status ID returned by [Trigger update](#operation/triggerUpdate).", "required": true, "schema": { - "type": "string" - }, - "description": "Your project ID. Can be copied from the [API keys](https://app.mintlify.com/settings/organization/api-keys) page in your dashboard." - }, - { - "name": "id", - "in": "path", - "required": true, - "schema": { - "type": "string" - }, - "description": "The unique identifier of the agent job to retrieve." + "type": "string", + "example": "abc123def456" + } } ], "responses": { "200": { - "description": "Agent job details retrieved successfully", + "description": "Update details.", "content": { "application/json": { "schema": { "type": "object", "properties": { - "sessionId": { + "_id": { "type": "string", - "description": "The subdomain this session belongs to." + "description": "The status ID of the update.", + "example": "abc123def456" }, - "subdomain": { + "projectId": { "type": "string", - "description": "The subdomain this session belongs to." + "description": "The documentation project ID.", + "example": "my-project-id" }, - "branch": { + "createdAt": { "type": "string", - "description": "Git branch name where changes were made.", - "nullable": true + "description": "ISO 8601 timestamp when the update was created.", + "example": "2024-06-04T12:00:00.000Z" }, - "haulted": { - "type": "boolean", - "description": "Whether the session execution was halted." - }, - "haultReason": { + "endedAt": { "type": "string", - "enum": ["completed", "github_missconfigured", "error", "processing", "interrupted"], - "description": "Reason for session halt. `processing` indicates the job is still running. `interrupted` indicates the job was manually interrupted." + "description": "ISO 8601 timestamp when the update completed. Null if still in progress.", + "example": "2024-06-04T12:01:30.000Z" }, - "pullRequestLink": { + "status": { "type": "string", - "description": "Link to the created pull request." + "enum": ["queued", "in_progress", "success", "failure"], + "description": "Current status of the update.", + "example": "success" }, - "messageToUser": { + "summary": { "type": "string", - "description": "Message for the user about the session outcome." + "description": "Summary of the update result.", + "example": "Deployed 3 changed pages" }, - "todos": { + "logs": { "type": "array", - "description": "List of todo items from the session.", + "description": "Array of log messages from the build.", "items": { - "type": "object", - "properties": { - "content": { - "type": "string", - "description": "Brief description of the task." - }, - "status": { - "type": "string", - "enum": ["pending", "in_progress", "completed", "cancelled"], - "description": "Current status of the task." - }, - "priority": { - "type": "string", - "enum": ["high", "medium", "low"], - "description": "Priority level of the task." - }, - "id": { - "type": "string", - "description": "Unique identifier for the todo item." - } - } + "type": "string" } }, - "userId": { + "subdomain": { "type": "string", - "description": "The ID of the user who created this session, if available." + "description": "The subdomain of the docs being updated.", + "example": "my-org" }, - "title": { + "screenshotLight": { "type": "string", - "description": "A generated title summarizing the agent job." + "description": "URL of a screenshot of the docs in light mode.", + "example": "https://cdn.mintlify.com/screenshots/abc123.png" }, - "createdAt": { + "screenshotDark": { "type": "string", - "format": "date-time", - "description": "Timestamp when the session was created." + "description": "URL of a screenshot of the docs in dark mode.", + "example": "https://cdn.mintlify.com/screenshots/abc123-dark.png" + }, + "author": { + "type": "object", + "description": "The author who triggered the update.", + "nullable": true, + "properties": { + "name": { + "type": "string", + "description": "The author's name.", + "example": "Jane Smith" + }, + "avatarUrl": { + "type": "string", + "description": "URL of the author's avatar image.", + "example": "https://avatars.githubusercontent.com/u/12345678" + }, + "githubUserId": { + "type": "number", + "description": "The author's GitHub user ID.", + "example": 12345678 + } + } + }, + "commit": { + "type": "object", + "description": "Details of the deployed commit.", + "properties": { + "sha": { + "type": "string", + "description": "The commit SHA.", + "example": "a1b2c3d4e5f6" + }, + "ref": { + "type": "string", + "description": "The branch or tag ref.", + "example": "refs/heads/main" + }, + "message": { + "type": "string", + "description": "The commit message.", + "example": "docs: update quickstart guide" + }, + "filesChanged": { + "type": "object", + "description": "Files changed in this commit.", + "properties": { + "added": { + "type": "array", + "description": "New files added.", + "items": { "type": "string" }, + "example": ["quickstart.mdx"] + }, + "modified": { + "type": "array", + "description": "Existing files that were modified.", + "items": { "type": "string" }, + "example": ["introduction.mdx", "api/overview.mdx"] + }, + "removed": { + "type": "array", + "description": "Files that were removed.", + "items": { "type": "string" }, + "example": [] + } + } + } + } + }, + "source": { + "type": "string", + "description": "What triggered the update.", + "enum": ["internal", "github-app-installation", "api", "github", "dashboard", "gitlab", "onboarding"], + "example": "api" } } } } } } - } + }, + "x-codeSamples": [ + { + "lang": "bash", + "label": "cURL", + "source": "curl https://api.mintlify.com/v1/project/update-status/abc123def456 \\\n -H \"Authorization: Bearer mint_xxxxx\"" + } + ] } }, - "/v1/agent/{projectId}/jobs": { - "get": { - "summary": "Get all agent jobs (v1)", - "deprecated": true, - "description": "Deprecated: use [v2 get agent job](/api/agent/v2/get-agent-job) instead. Retrieves all agent jobs for the specified domain, including their status and details.", + "/v1/project/preview/{projectId}": { + "post": { + "summary": "Trigger preview deployment", + "description": "Create or update a preview deployment for a specific Git branch. If a preview already exists for the branch, it triggers a redeployment instead of creating a duplicate. Returns a status ID and the preview URL.\n\n**Rate limit:** 5 requests per minute per organization.", + "operationId": "triggerPreview", + "tags": ["Deployments"], "parameters": [ { "name": "projectId", "in": "path", + "description": "Your project ID. Copy it from the [API keys](https://app.mintlify.com/settings/organization/api-keys) page in your dashboard.", "required": true, "schema": { - "type": "string" - }, - "description": "Your project ID. Can be copied from the [API keys](https://app.mintlify.com/settings/organization/api-keys) page in your dashboard." - }, - { - "name": "skip", - "in": "query", - "required": false, - "schema": { - "type": "integer", - "minimum": 0, - "default": 0 - }, - "description": "Number of results to skip for pagination." - }, - { - "name": "take", - "in": "query", - "required": false, - "schema": { - "type": "integer", - "minimum": 1, - "maximum": 100, - "default": 12 - }, - "description": "Number of results to return. Maximum 100." + "type": "string", + "example": "my-project-id" + } } ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "required": ["branch"], + "properties": { + "branch": { + "type": "string", + "description": "The name of the Git branch to create a preview deployment for.", + "minLength": 1, + "example": "feat/new-quickstart" + } + } + } + } + } + }, "responses": { - "200": { - "description": "All agent jobs retrieved successfully", + "202": { + "description": "Preview deployment queued successfully.", "content": { "application/json": { "schema": { "type": "object", "properties": { - "allSessions": { - "type": "array", - "description": "Array of all agent sessions for the domain.", - "items": { - "type": "object", - "properties": { - "sessionId": { - "type": "string", - "description": "The subdomain this session belongs to." - }, - "subdomain": { - "type": "string", - "description": "The subdomain this session belongs to." - }, - "branch": { - "type": "string", - "description": "Git branch name where changes were made.", - "nullable": true - }, - "haulted": { - "type": "boolean", - "description": "Whether the session execution was halted." - }, - "haultReason": { - "type": "string", - "enum": ["completed", "github_missconfigured", "error", "processing", "interrupted"], - "description": "Reason for session halt. `processing` indicates the job is still running. `interrupted` indicates the job was manually interrupted." - }, - "pullRequestLink": { - "type": "string", - "description": "Link to the created pull request." - }, - "messageToUser": { - "type": "string", - "description": "Message for the user about the session outcome." - }, - "todos": { - "type": "array", - "description": "List of todo items from the session.", - "items": { - "type": "object", - "properties": { - "content": { - "type": "string", - "description": "Brief description of the task." - }, - "status": { - "type": "string", - "enum": ["pending", "in_progress", "completed", "cancelled"], - "description": "Current status of the task." - }, - "priority": { - "type": "string", - "enum": ["high", "medium", "low"], - "description": "Priority level of the task." - }, - "id": { - "type": "string", - "description": "Unique identifier for the todo item." - } - } - } - }, - "userId": { - "type": "string", - "description": "The ID of the user who created this session, if available." - }, - "title": { - "type": "string", - "description": "A generated title summarizing the agent job." - }, - "createdAt": { - "type": "string", - "format": "date-time", - "description": "Timestamp when the session was created." - } - } - } + "statusId": { + "type": "string", + "description": "Use this with [Get update status](#operation/getUpdateStatus) to track the deployment.", + "example": "preview-abc123" + }, + "previewUrl": { + "type": "string", + "description": "The URL where the preview deployment is hosted.", + "example": "https://my-org-feat-new-quickstart.mintlify.app" } } } } } + }, + "400": { + "description": "Invalid request. The `branch` field is required.", + "content": { + "application/json": { + "schema": { "$ref": "#/components/schemas/Error" } + } + } + }, + "403": { + "description": "Preview deployments are not available on your current plan.", + "content": { + "application/json": { + "schema": { "$ref": "#/components/schemas/Error" } + } + } } - } + }, + "x-codeSamples": [ + { + "lang": "bash", + "label": "cURL", + "source": "curl -X POST https://api.mintlify.com/v1/project/preview/my-project-id \\\n -H \"Authorization: Bearer mint_xxxxx\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"branch\": \"feat/new-quickstart\"}'" + } + ] } }, "/v2/agent/{projectId}/job": { "post": { "summary": "Create agent job", - "description": "Creates a new agent job that runs in the background. The job processes the prompt asynchronously — poll the get job endpoint to track progress. If the agent edits files successfully, a pull request is automatically created.", + "description": "Create a background agent job. The job processes the prompt asynchronously — poll [Get agent job](#operation/getAgentJob) to track progress. If the agent edits files successfully, Mintlify creates a pull request and populates the `prLink` field.\n\n**Rate limit:** 100 requests per project per hour.", + "operationId": "createAgentJob", + "tags": ["Agent"], "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { - "type": "string" + "type": "string", + "example": "my-project-id" }, - "description": "Your project ID. Can be copied from the [API keys](https://app.mintlify.com/settings/organization/api-keys) page in your dashboard." + "description": "Your project ID. Copy it from the [API keys](https://app.mintlify.com/settings/organization/api-keys) page in your dashboard." } ], "requestBody": { @@ -384,7 +347,8 @@ "prompt": { "type": "string", "minLength": 1, - "description": "The instruction for the agent to execute." + "description": "The instruction for the agent to execute.", + "example": "Add a quickstart guide for the Python SDK" } } } @@ -393,106 +357,118 @@ }, "responses": { "201": { - "description": "Agent job created successfully", + "description": "Agent job created. Poll [Get agent job](#operation/getAgentJob) until `status` is `completed`, `archived`, or `failed`.", "content": { "application/json": { - "schema": { - "$ref": "#/components/schemas/AgentJob" - } + "schema": { "$ref": "#/components/schemas/AgentJob" } } } }, "400": { - "description": "Invalid request", + "description": "Invalid request.", "content": { "application/json": { - "schema": { - "$ref": "#/components/schemas/Error" - } + "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { - "description": "Rate limit exceeded", + "description": "Rate limit exceeded.", "content": { "application/json": { - "schema": { - "$ref": "#/components/schemas/Error" - } + "schema": { "$ref": "#/components/schemas/Error" } } } } - } + }, + "x-codeSamples": [ + { + "lang": "bash", + "label": "cURL", + "source": "curl -X POST https://api.mintlify.com/v2/agent/my-project-id/job \\\n -H \"Authorization: Bearer mint_xxxxx\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"prompt\": \"Add a quickstart guide for the Python SDK\"}'" + } + ] } }, "/v2/agent/{projectId}/job/{id}": { "get": { "summary": "Get agent job", - "description": "Retrieves the current status and details of an agent job. Poll this endpoint to track job progress.", + "description": "Get the current status and details of an agent job. Poll this endpoint to track job progress — the `status` field transitions from `active` to `completed`, `archived`, or `failed`.", + "operationId": "getAgentJob", + "tags": ["Agent"], "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { - "type": "string" + "type": "string", + "example": "my-project-id" }, - "description": "Your project ID. Can be copied from the [API keys](https://app.mintlify.com/settings/organization/api-keys) page in your dashboard." + "description": "Your project ID. Copy it from the [API keys](https://app.mintlify.com/settings/organization/api-keys) page in your dashboard." }, { "name": "id", "in": "path", "required": true, "schema": { - "type": "string" + "type": "string", + "example": "job_abc123" }, "description": "The unique identifier of the agent job." } ], "responses": { "200": { - "description": "Agent job details", + "description": "Agent job details.", "content": { "application/json": { - "schema": { - "$ref": "#/components/schemas/AgentJob" - } + "schema": { "$ref": "#/components/schemas/AgentJob" } } } }, "404": { - "description": "Job not found", + "description": "Job not found.", "content": { "application/json": { - "schema": { - "$ref": "#/components/schemas/Error" - } + "schema": { "$ref": "#/components/schemas/Error" } } } } - } + }, + "x-codeSamples": [ + { + "lang": "bash", + "label": "cURL", + "source": "curl https://api.mintlify.com/v2/agent/my-project-id/job/job_abc123 \\\n -H \"Authorization: Bearer mint_xxxxx\"" + } + ] } }, "/v2/agent/{projectId}/job/{id}/message": { "post": { "summary": "Send follow-up message", - "description": "Sends a follow-up message to an existing agent job. The message is processed asynchronously — poll the get job endpoint to track progress.", + "description": "Send a follow-up instruction to an existing agent job. The message is processed asynchronously — poll [Get agent job](#operation/getAgentJob) to track progress.\n\n**Rate limit:** 100 requests per project per hour.", + "operationId": "sendFollowUpMessage", + "tags": ["Agent"], "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { - "type": "string" + "type": "string", + "example": "my-project-id" }, - "description": "Your project ID. Can be copied from the [API keys](https://app.mintlify.com/settings/organization/api-keys) page in your dashboard." + "description": "Your project ID. Copy it from the [API keys](https://app.mintlify.com/settings/organization/api-keys) page in your dashboard." }, { "name": "id", "in": "path", "required": true, "schema": { - "type": "string" + "type": "string", + "example": "job_abc123" }, "description": "The unique identifier of the agent job to send a message to." } @@ -508,7 +484,8 @@ "prompt": { "type": "string", "minLength": 1, - "description": "The follow-up instruction for the agent." + "description": "The follow-up instruction for the agent.", + "example": "Also add error handling examples to the quickstart guide" } } } @@ -517,45 +494,160 @@ }, "responses": { "200": { - "description": "Message sent successfully", + "description": "Message sent. Poll [Get agent job](#operation/getAgentJob) to track progress.", "content": { "application/json": { - "schema": { - "$ref": "#/components/schemas/AgentJob" - } + "schema": { "$ref": "#/components/schemas/AgentJob" } } } }, "400": { - "description": "Invalid request", + "description": "Invalid request.", "content": { "application/json": { - "schema": { - "$ref": "#/components/schemas/Error" - } + "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { - "description": "Job not found", + "description": "Job not found.", "content": { "application/json": { - "schema": { - "$ref": "#/components/schemas/Error" - } + "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { - "description": "Rate limit exceeded", + "description": "Rate limit exceeded.", "content": { "application/json": { - "schema": { - "$ref": "#/components/schemas/Error" + "schema": { "$ref": "#/components/schemas/Error" } + } + } + } + }, + "x-codeSamples": [ + { + "lang": "bash", + "label": "cURL", + "source": "curl -X POST https://api.mintlify.com/v2/agent/my-project-id/job/job_abc123/message \\\n -H \"Authorization: Bearer mint_xxxxx\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"prompt\": \"Also add error handling examples to the quickstart guide\"}'" + } + ] + } + }, + "/v1/agent/{projectId}/job": { + "post": { + "summary": "Create agent job (v1)", + "deprecated": true, + "x-hidden": true, + "description": "Deprecated. Use [Create agent job](#operation/createAgentJob) instead.", + "parameters": [ + { + "name": "projectId", + "in": "path", + "required": true, + "schema": { "type": "string" }, + "description": "Your project ID." + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "required": ["messages"], + "properties": { + "branch": { + "type": "string", + "description": "The Git branch for the agent to work on." + }, + "messages": { + "type": "array", + "description": "Conversation messages.", + "items": { + "type": "object", + "required": ["role", "content"], + "properties": { + "role": { "type": "string", "enum": ["system", "user", "assistant"] }, + "content": { "type": "string" } + } + } + }, + "asDraft": { "type": "boolean", "default": false }, + "model": { "type": "string", "enum": ["sonnet", "opus"], "default": "sonnet" } } } } } + }, + "responses": { + "200": { + "description": "Streaming SSE response.", + "content": { + "text/event-stream": { + "schema": { "type": "string" } + } + } + } + } + } + }, + "/v1/agent/{projectId}/job/{id}": { + "get": { + "summary": "Get agent job by ID (v1)", + "deprecated": true, + "x-hidden": true, + "description": "Deprecated. Use [Get agent job](#operation/getAgentJob) instead.", + "parameters": [ + { + "name": "projectId", + "in": "path", + "required": true, + "schema": { "type": "string" } + }, + { + "name": "id", + "in": "path", + "required": true, + "schema": { "type": "string" } + } + ], + "responses": { + "200": { + "description": "Agent job details.", + "content": { + "application/json": { + "schema": { "type": "object" } + } + } + } + } + } + }, + "/v1/agent/{projectId}/jobs": { + "get": { + "summary": "Get all agent jobs (v1)", + "deprecated": true, + "x-hidden": true, + "description": "Deprecated. Use [Get agent job](#operation/getAgentJob) instead.", + "parameters": [ + { + "name": "projectId", + "in": "path", + "required": true, + "schema": { "type": "string" } + } + ], + "responses": { + "200": { + "description": "List of agent jobs.", + "content": { + "application/json": { + "schema": { "type": "object" } + } + } + } } } } @@ -567,12 +659,14 @@ "properties": { "id": { "type": "string", - "description": "Unique identifier for the agent job." + "description": "Unique identifier for the agent job.", + "example": "job_abc123" }, "status": { "type": "string", "enum": ["active", "completed", "archived", "failed"], - "description": "Current status of the job. `active` — the agent is currently processing the prompt. `completed` — the agent finished successfully and a PR may have been created (check `prLink`). `archived` — the job has been archived. `failed` — the agent encountered an unrecoverable error. Poll until status is `completed`, `archived`, or `failed`." + "description": "Current status of the job. Poll until `completed`, `archived`, or `failed`.\n\n- `active` — the agent is processing the prompt\n- `completed` — the agent finished; check `prLink` for a pull request\n- `archived` — the job has been archived\n- `failed` — the agent encountered an unrecoverable error", + "example": "completed" }, "source": { "type": "object", @@ -580,36 +674,41 @@ "properties": { "repository": { "type": "string", - "description": "Full URL of the GitHub repository." + "description": "Full URL of the GitHub repository.", + "example": "https://github.com/my-org/my-docs" }, "ref": { "type": "string", "description": "Git branch the agent is working on.", - "nullable": true + "nullable": true, + "example": "agent/add-python-quickstart" } } }, "model": { "type": "string", - "description": "The AI model used for this job." + "description": "The AI model used for this job.", + "example": "claude-sonnet-4-5" }, "prLink": { "type": "string", "format": "uri", - "example": "https://github.com/org/repo/pull/123", - "description": "GitHub pull request URL created by the agent. `null` while the job is still `active` or if no files were changed. Populated once the agent successfully creates a PR.", - "nullable": true + "description": "GitHub pull request URL created by the agent. `null` while `active` or if no files were changed.", + "nullable": true, + "example": "https://github.com/my-org/my-docs/pull/42" }, "createdAt": { "type": "string", "format": "date-time", - "description": "Timestamp when the job was created." + "description": "Timestamp when the job was created.", + "example": "2024-06-04T12:00:00.000Z" }, "archivedAt": { "type": "string", "format": "date-time", "description": "Timestamp when the job was archived.", - "nullable": true + "nullable": true, + "example": null } } }, @@ -618,7 +717,8 @@ "properties": { "error": { "type": "string", - "description": "Error message." + "description": "Error message.", + "example": "Invalid request body" } } } @@ -627,7 +727,7 @@ "bearerAuth": { "type": "http", "scheme": "bearer", - "description": "The Authorization header expects a Bearer token. Use an admin API key (prefixed with `mint_`). This is a server-side secret key. Generate one on the [API keys page](https://app.mintlify.com/settings/organization/api-keys) in your dashboard." + "description": "Use an admin API key (prefixed `mint_`). Generate one on the [API keys page](https://app.mintlify.com/settings/organization/api-keys) in your dashboard. Keep this key server-side — never expose it in client-side code." } } } diff --git a/analytics.openapi.json b/analytics.openapi.json index f1ecea56fe..4559e14bba 100644 --- a/analytics.openapi.json +++ b/analytics.openapi.json @@ -638,7 +638,7 @@ "/v1/analytics/{projectId}/feedback": { "get": { "summary": "Get user feedback", - "description": "Returns paginated user feedback with optional filtering", + "description": "Returns paginated user feedback with optional filtering. Paginate using the `cursor` from each response while `hasMore` is `true`.", "tags": [ "Analytics" ], @@ -647,6 +647,13 @@ "bearerAuth": [] } ], + "x-codeSamples": [ + { + "lang": "bash", + "label": "cURL", + "source": "curl \"https://api.mintlify.com/v1/analytics/my-project-id/feedback?dateFrom=2024-01-01&dateTo=2024-02-01&limit=50\" \\\n -H \"Authorization: Bearer mint_xxxxx\"" + } + ], "parameters": [ { "$ref": "#/components/parameters/projectId" @@ -754,7 +761,7 @@ "/v1/analytics/{projectId}/feedback/by-page": { "get": { "summary": "Get feedback by page", - "description": "Returns feedback counts aggregated by documentation page path (thumbs up/down for contextual feedback, code snippet count, and total per page)", + "description": "Returns feedback counts aggregated by documentation page path — thumbs up/down for contextual feedback, code snippet feedback count, and total per page.", "tags": [ "Analytics" ], @@ -763,6 +770,13 @@ "bearerAuth": [] } ], + "x-codeSamples": [ + { + "lang": "bash", + "label": "cURL", + "source": "curl \"https://api.mintlify.com/v1/analytics/my-project-id/feedback/by-page?dateFrom=2024-01-01&dateTo=2024-02-01\" \\\n -H \"Authorization: Bearer mint_xxxxx\"" + } + ], "parameters": [ { "$ref": "#/components/parameters/projectId" @@ -861,7 +875,7 @@ "/v1/analytics/{projectId}/assistant": { "get": { "summary": "Get assistant conversations", - "description": "Returns paginated AI assistant conversation history", + "description": "Returns paginated AI assistant conversation history, including the user query, assistant response, sources cited, resolution status, and query category. Paginate using the `cursor` from each response while `hasMore` is `true`.", "tags": [ "Analytics" ], @@ -870,6 +884,13 @@ "bearerAuth": [] } ], + "x-codeSamples": [ + { + "lang": "bash", + "label": "cURL", + "source": "curl \"https://api.mintlify.com/v1/analytics/my-project-id/assistant?dateFrom=2024-01-01&dateTo=2024-02-01&limit=100\" \\\n -H \"Authorization: Bearer mint_xxxxx\"" + } + ], "parameters": [ { "$ref": "#/components/parameters/projectId" @@ -954,7 +975,7 @@ "/v1/analytics/{projectId}/assistant/caller-stats": { "get": { "summary": "Get assistant caller stats", - "description": "Returns a breakdown of assistant query counts by caller type (web, API, and other) for the specified date range.", + "description": "Returns a breakdown of assistant query counts by caller type (web, API, and other) for the specified date range. Use this to understand whether queries come from your documentation site or from direct API integrations.", "tags": [ "Analytics" ], @@ -963,6 +984,13 @@ "bearerAuth": [] } ], + "x-codeSamples": [ + { + "lang": "bash", + "label": "cURL", + "source": "curl \"https://api.mintlify.com/v1/analytics/my-project-id/assistant/caller-stats?dateFrom=2024-01-01&dateTo=2024-02-01\" \\\n -H \"Authorization: Bearer mint_xxxxx\"" + } + ], "parameters": [ { "$ref": "#/components/parameters/projectId" @@ -1025,7 +1053,7 @@ "/v1/analytics/{projectId}/searches": { "get": { "summary": "Get search queries", - "description": "Returns paginated documentation search terms for the date range, ordered by hit count descending. Each row includes click-through rate, the most-clicked result path for that query (if any), and the last time the term was searched. `totalSearches` is the total number of search query events in the same date range (sum of all hits, not distinct queries).", + "description": "Returns paginated documentation search terms ordered by hit count descending. Each row includes click-through rate, the most-clicked result path, and the last time the term was searched. `totalSearches` is the total search event count (sum of all hits, not distinct queries). Paginate using `nextCursor` while it is not null.", "tags": [ "Analytics" ], @@ -1034,6 +1062,13 @@ "bearerAuth": [] } ], + "x-codeSamples": [ + { + "lang": "bash", + "label": "cURL", + "source": "curl \"https://api.mintlify.com/v1/analytics/my-project-id/searches?dateFrom=2024-01-01&dateTo=2024-02-01&limit=50\" \\\n -H \"Authorization: Bearer mint_xxxxx\"" + } + ], "parameters": [ { "$ref": "#/components/parameters/projectId" @@ -1117,7 +1152,7 @@ "/v1/analytics/{projectId}/views": { "get": { "summary": "Get page views", - "description": "Returns per-path and site-wide content view event counts, split by human and AI traffic.", + "description": "Returns per-path and site-wide content view event counts, split by human and AI traffic. Paginate using offset-based pagination: increment `offset` by `limit` while `hasMore` is `true`.", "tags": [ "Analytics" ], @@ -1126,6 +1161,13 @@ "bearerAuth": [] } ], + "x-codeSamples": [ + { + "lang": "bash", + "label": "cURL", + "source": "curl \"https://api.mintlify.com/v1/analytics/my-project-id/views?dateFrom=2024-01-01&dateTo=2024-02-01&limit=50&offset=0\" \\\n -H \"Authorization: Bearer mint_xxxxx\"" + } + ], "parameters": [ { "$ref": "#/components/parameters/projectId" @@ -1211,7 +1253,7 @@ "/v1/analytics/{projectId}/visitors": { "get": { "summary": "Get unique visitors", - "description": "Returns per-path and site-wide approximate distinct visitors by traffic type. The `total` field is deduplicated across human and AI (union of distinct visitor IDs with any qualifying content view).", + "description": "Returns per-path and site-wide approximate distinct visitors split by human and AI traffic. The `total` field is deduplicated across human and AI (union of distinct visitor IDs). Paginate using offset-based pagination: increment `offset` by `limit` while `hasMore` is `true`.", "tags": [ "Analytics" ], @@ -1220,6 +1262,13 @@ "bearerAuth": [] } ], + "x-codeSamples": [ + { + "lang": "bash", + "label": "cURL", + "source": "curl \"https://api.mintlify.com/v1/analytics/my-project-id/visitors?dateFrom=2024-01-01&dateTo=2024-02-01&limit=50&offset=0\" \\\n -H \"Authorization: Bearer mint_xxxxx\"" + } + ], "parameters": [ { "$ref": "#/components/parameters/projectId" diff --git a/api/agent/create-agent-job.mdx b/api/agent/create-agent-job.mdx deleted file mode 100644 index 6d0e1a1419..0000000000 --- a/api/agent/create-agent-job.mdx +++ /dev/null @@ -1,23 +0,0 @@ ---- -title: "Create agent job (v1)" -openapi: /admin-openapi.json POST /v1/agent/{projectId}/job -keywords: [ "agent job", "create", "automation", "automate" ] -tag: "deprecated" - ---- - -This endpoint is deprecated. Use the [v2 create agent job](/api/agent/v2/create-agent-job) endpoint instead. - -This endpoint creates an agent job based on provided messages and branch information. The job executes asynchronously and returns a streaming response with the execution details and results. - -If a branch doesn't exist, the agent creates one. If files are edited successfully, a pull request is automatically created at the end of the job. - -## Rate limits - -The agent API has the following limits: - -- 100 uses per Mintlify project per hour - -## Suggested usage - -For best results, use the [useChat hook from ai-sdk](https://ai-sdk.dev/docs/reference/ai-sdk-ui/use-chat#usechat) to send requests and handle responses. diff --git a/api/agent/get-agent-job.mdx b/api/agent/get-agent-job.mdx deleted file mode 100644 index a1ef4d92af..0000000000 --- a/api/agent/get-agent-job.mdx +++ /dev/null @@ -1,20 +0,0 @@ ---- -title: "Get agent job (v1)" -openapi: /admin-openapi.json GET /v1/agent/{projectId}/job/{id} -keywords: [ "agent job", "status", "retrieve", "details" ] -tag: "deprecated" - ---- - -This endpoint is deprecated. Use the [v2 get agent job](/api/agent/v2/get-agent-job) endpoint instead. - -## Usage - -This endpoint retrieves the details and status of a specific agent job by its unique identifier. Use this to check the progress, status, and results of a previously created agent job. - -## Job details - -The response includes information such as: -- Job execution status and completion state -- Branch information and pull request details -- Session metadata and timestamps diff --git a/api/agent/get-all-jobs.mdx b/api/agent/get-all-jobs.mdx deleted file mode 100644 index ab12075b47..0000000000 --- a/api/agent/get-all-jobs.mdx +++ /dev/null @@ -1,17 +0,0 @@ ---- -title: "List agent jobs (v1)" -openapi: /admin-openapi.json GET /v1/agent/{projectId}/jobs -keywords: [ "agent jobs", "list", "monitoring" ] -tag: "deprecated" - ---- - -This endpoint is deprecated. Use the [v2 get agent job](/api/agent/v2/get-agent-job) endpoint instead. - -## Usage - -This endpoint retrieves all agent jobs for the specified domain, providing an overview of all agent activities and their current status. This is useful for monitoring and managing multiple concurrent or historical agent jobs. - -## Response - -Use this endpoint to get a comprehensive view of all previous agent sessions. diff --git a/api/agent/v2/create-agent-job.mdx b/api/agent/v2/create-agent-job.mdx deleted file mode 100644 index ef6cd683c1..0000000000 --- a/api/agent/v2/create-agent-job.mdx +++ /dev/null @@ -1,23 +0,0 @@ ---- -title: "Create agent job" -openapi: /admin-openapi.json POST /v2/agent/{projectId}/job -keywords: ["agent job", "create", "automation", "automate"] - ---- - -This endpoint creates a background agent job. The job runs asynchronously — use the [get agent job](/api/agent/v2/get-agent-job) endpoint to poll for status updates. - -If the agent edits files successfully, Mintlify creates a pull request and populates the `prLink` field in the job response. - -## Rate limits - -- 100 uses per Mintlify project per hour - -## Usage - -```bash -curl -X POST https://api.mintlify.com/v2/agent/{projectId}/job \ - -H "Authorization: Bearer mint_xxxxx" \ - -H "Content-Type: application/json" \ - -d '{"prompt": "Add a quickstart guide for the Python SDK"}' -``` diff --git a/api/agent/v2/get-agent-job.mdx b/api/agent/v2/get-agent-job.mdx deleted file mode 100644 index 6fcc6650a5..0000000000 --- a/api/agent/v2/get-agent-job.mdx +++ /dev/null @@ -1,10 +0,0 @@ ---- -title: "Get agent job" -openapi: /admin-openapi.json GET /v2/agent/{projectId}/job/{id} -keywords: ["agent job", "status", "retrieve", "details", "poll"] - ---- - -Poll this endpoint to track the progress of an agent job. The `status` field transitions through `active` → `completed` or `failed`. - -After the agent creates a pull request, the `prLink` field contains the link. diff --git a/api/agent/v2/send-message.mdx b/api/agent/v2/send-message.mdx deleted file mode 100644 index 06663c457d..0000000000 --- a/api/agent/v2/send-message.mdx +++ /dev/null @@ -1,21 +0,0 @@ ---- -title: "Send follow-up message" -openapi: /admin-openapi.json POST /v2/agent/{projectId}/job/{id}/message -keywords: ["agent job", "message", "follow-up", "send"] - ---- - -Send a follow-up instruction to an existing agent job. The agent processes the message asynchronously. Poll the [get agent job](/api/agent/v2/get-agent-job) endpoint to track progress. - -## Rate limits - -- 100 uses per Mintlify project per hour - -## Usage - -```bash -curl -X POST https://api.mintlify.com/v2/agent/{projectId}/job/{id}/message \ - -H "Authorization: Bearer mint_xxxxx" \ - -H "Content-Type: application/json" \ - -d '{"prompt": "Also add error handling examples to the quickstart guide"}' -``` diff --git a/api/analytics/assistant-caller-stats.mdx b/api/analytics/assistant-caller-stats.mdx deleted file mode 100644 index 377fd12c29..0000000000 --- a/api/analytics/assistant-caller-stats.mdx +++ /dev/null @@ -1,19 +0,0 @@ ---- -title: "Get assistant caller stats" -openapi: /analytics.openapi.json GET /v1/analytics/{projectId}/assistant/caller-stats -keywords: ["analytics", "assistant", "caller", "stats", "export"] - ---- - -## Usage - -Use this endpoint to see how the system distributes assistant queries across different caller types. The response breaks down total queries into: - -- **web**: Queries from the documentation site -- **api**: Queries from direct API calls -- **other**: Queries from other sources (for example, integrations, SDKs) -- **total**: Sum of all query types - -## Filtering - -Filter by date range using `dateFrom` and `dateTo` parameters. diff --git a/api/analytics/assistant-conversations.mdx b/api/analytics/assistant-conversations.mdx deleted file mode 100644 index 14c33ae961..0000000000 --- a/api/analytics/assistant-conversations.mdx +++ /dev/null @@ -1,25 +0,0 @@ ---- -title: "Get assistant conversations" -openapi: /analytics.openapi.json GET /v1/analytics/{projectId}/assistant -keywords: ["analytics", "assistant", "conversations", "export", "AI"] - ---- - -## Usage - -Use this endpoint to export AI assistant conversation history from your documentation. Each conversation includes the user query, assistant response, sources cited, resolution status, and query category. - -Paginate through results using the `cursor` parameter returned in the response. Continue fetching while `hasMore` is `true`. - -## Filtering - -Filter conversations by date range using `dateFrom` and `dateTo` parameters. - -## Conversation data - -Each conversation includes: -- **query**: The user's question -- **response**: The assistant's answer -- **sources**: Pages referenced in the response, with title and URL -- **resolutionStatus**: Whether the assistant successfully answered the question. Either `answered` or `unanswered`. Use this field to track and analyze documentation gaps surfaced by user questions the assistant could not resolve. -- **queryCategory**: Classification of the query type (if available) diff --git a/api/analytics/feedback-by-page.mdx b/api/analytics/feedback-by-page.mdx deleted file mode 100644 index 02a299f4eb..0000000000 --- a/api/analytics/feedback-by-page.mdx +++ /dev/null @@ -1,18 +0,0 @@ ---- -title: "Get feedback by page" -openapi: /analytics.openapi.json GET /v1/analytics/{projectId}/feedback/by-page -keywords: ["analytics", "feedback", "export", "by page", "aggregated"] - ---- - -## Usage - -Use this endpoint to export user feedback aggregated by documentation page path. Each entry shows the total feedback count for a page, broken down by type. - -## Filtering - -Filter feedback by: -- **Date range**: Use `dateFrom` and `dateTo` to limit results to a specific time period -- **Source**: Filter by `code_snippet`, `contextual`, or `agent` feedback types -- **Status**: Filter by status values like `pending`, `in_progress`, `resolved`, or `dismissed` - diff --git a/api/analytics/feedback.mdx b/api/analytics/feedback.mdx deleted file mode 100644 index cffca87ea6..0000000000 --- a/api/analytics/feedback.mdx +++ /dev/null @@ -1,27 +0,0 @@ ---- -title: "Get feedback" -openapi: /analytics.openapi.json GET /v1/analytics/{projectId}/feedback -keywords: ["analytics", "feedback", "export", "user feedback"] - ---- - -## Usage - -Use this endpoint to export user feedback collected from your documentation. Feedback includes contextual feedback from page ratings, code snippet feedback, and agent feedback. - -Paginate through results using the `cursor` parameter returned in the response. Continue fetching while `hasMore` is `true`. - -## Filtering - -Filter feedback by: -- **Date range**: Use `dateFrom` and `dateTo` to limit results to a specific time period -- **Source**: Filter by `code_snippet`, `contextual`, or `agent` feedback types -- **Status**: Filter by status values like `pending`, `in_progress`, `resolved`, or `dismissed` - -## Response types - -The response contains different feedback types based on the source: - -- **Contextual feedback**: Includes `helpful` boolean and optional `contact` email -- **Code snippet feedback**: Includes `code`, `filename`, and `lang` fields -- **Agent feedback**: Includes a `comment` with the agent's feedback text and the `path` of the page it relates to diff --git a/api/analytics/searches.mdx b/api/analytics/searches.mdx deleted file mode 100644 index 33dfb889ca..0000000000 --- a/api/analytics/searches.mdx +++ /dev/null @@ -1,17 +0,0 @@ ---- -title: "Get search queries" -openapi: /analytics.openapi.json GET /v1/analytics/{projectId}/searches -keywords: ["analytics", "search", "export", "queries", "search terms"] - ---- - -## Usage - -Use this endpoint to export documentation search analytics. Results are ordered by hit count descending, showing which terms your users search for most. - -Paginate through results using the `nextCursor` parameter returned in the response. Continue fetching while `nextCursor` is not null. - -## Filtering - -Filter search data by date range using `dateFrom` and `dateTo` parameters. - diff --git a/api/analytics/views.mdx b/api/analytics/views.mdx deleted file mode 100644 index cdb50bfeae..0000000000 --- a/api/analytics/views.mdx +++ /dev/null @@ -1,17 +0,0 @@ ---- -title: "Get page views" -openapi: /analytics.openapi.json GET /v1/analytics/{projectId}/views -keywords: ["analytics", "views", "page views", "traffic", "export"] - ---- - -## Usage - -Use this endpoint to export page view analytics. Results include both site-wide totals and per-page breakdowns, split by human and AI traffic. - -Paginate through results using offset-based pagination. Increment `offset` by `limit` while `hasMore` is true. - -## Filtering - -Filter view data by date range using `dateFrom` and `dateTo` parameters. - diff --git a/api/analytics/visitors.mdx b/api/analytics/visitors.mdx deleted file mode 100644 index 5efb335650..0000000000 --- a/api/analytics/visitors.mdx +++ /dev/null @@ -1,17 +0,0 @@ ---- -title: "Get unique visitors" -openapi: /analytics.openapi.json GET /v1/analytics/{projectId}/visitors -keywords: ["analytics", "visitors", "unique visitors", "traffic", "export"] - ---- - -## Usage - -Use this endpoint to export unique visitor analytics. Results include both site-wide totals and per-page breakdowns, split by human and AI traffic. The `total` field is deduplicated across human and AI traffic. - -Paginate through results using offset-based pagination. Increment `offset` by `limit` while `hasMore` is true. - -## Filtering - -Filter visitor data by date range using `dateFrom` and `dateTo` parameters. - diff --git a/api/assistant/create-assistant-message.mdx b/api/assistant/create-assistant-message.mdx index e64593511d..b67d56eb44 100644 --- a/api/assistant/create-assistant-message.mdx +++ b/api/assistant/create-assistant-message.mdx @@ -1,14 +1,11 @@ --- -title: "Create assistant message (v1)" +title: "Assistant message (AI SDK v4)" openapi: /discovery-openapi.json POST /v1/assistant/{domain}/message -tag: "Deprecated" -keywords: [ "assistant message", "embed", "chat", "integrate", "ai sdk v4" ] - +keywords: ["assistant message", "embed", "chat", "integrate", "ai sdk v4", "useChat"] --- -Deprecated - The assistant message v1 endpoint is compatible with **AI SDK v4**. If you use AI SDK v5 or later, use the [assistant message v2 endpoint](/api/assistant/create-assistant-message-v2) instead. + Use this endpoint if you are on **AI SDK v4**. If you use AI SDK v5 or later, use the [assistant message v2 endpoint](/api/assistant/create-assistant-message-v2) instead. ## Integration with `useChat` diff --git a/api/assistant/get-page-content.mdx b/api/assistant/get-page-content.mdx index e64e3772c6..e48e9ca9eb 100644 --- a/api/assistant/get-page-content.mdx +++ b/api/assistant/get-page-content.mdx @@ -1,9 +1,5 @@ --- title: "Get page content" openapi: "/discovery-openapi.json POST /v1/page/{domain}" -keywords: [ "page", "content", "retrieve" ] - +keywords: ["page", "content", "retrieve", "page content"] --- - -## Rate limits -- 10,000 requests per Mintlify organization per hour diff --git a/api/assistant/search.mdx b/api/assistant/search.mdx index c1b048a4f8..60514a33b0 100644 --- a/api/assistant/search.mdx +++ b/api/assistant/search.mdx @@ -1,10 +1,5 @@ --- title: "Search documentation" openapi: "/discovery-openapi.json POST /v1/search/{domain}" -keywords: [ "search", "query" ] - +keywords: ["search", "query", "semantic search", "documentation search"] --- - -## Rate limits - -- 10,000 requests per Mintlify organization per hour diff --git a/api/introduction.mdx b/api/introduction.mdx index a163fdebf0..36b9613388 100644 --- a/api/introduction.mdx +++ b/api/introduction.mdx @@ -1,62 +1,46 @@ --- -title: "Mintlify REST API introduction" -description: "Use the Mintlify REST API to trigger deployments, embed an AI assistant, export analytics data, and manage documentation programmatically." -keywords: ["REST API", "endpoints", "API keys"] +title: "Mintlify REST API" +description: "Programmatically trigger deployments, embed an AI assistant, export analytics, and automate documentation edits." +keywords: ["REST API", "endpoints", "API keys", "authentication"] boost: 3 --- -The Mintlify REST (Representational State Transfer) API enables you to programmatically interact with your documentation, trigger updates, embed AI-powered chat experiences, and export analytics data. - -## Endpoints - -- [Trigger update](/api/update/trigger): Trigger an update of your site when desired. -- [Get update status](/api/update/status): Get the status of an update and other details about your docs. -- [Trigger preview deployment](/api/preview/trigger): Create or update a preview deployment for a specific branch. -- [Create agent job](/api/agent/v2/create-agent-job): Create an agent job to automatically edit your documentation. -- [Get agent job](/api/agent/v2/get-agent-job): Retrieve the details and status of a specific agent job. -- [Send follow-up message](/api/agent/v2/send-message): Send a follow-up message to an existing agent job. -- [Create assistant message](/api/assistant/create-assistant-message-v2): Embed the assistant, trained on your docs, into any application of your choosing. -- [Search documentation](/api/assistant/search): Search through your documentation. -- [Get page content](/api/assistant/get-page-content): Retrieve the full text content of a documentation page. -- [Get user feedback](/api/analytics/feedback): Export user feedback from your documentation. -- [Get feedback by page](/api/analytics/feedback-by-page): Export feedback counts aggregated by page. -- [Get assistant conversations](/api/analytics/assistant-conversations): Export AI assistant conversation history. -- [Get assistant caller stats](/api/analytics/assistant-caller-stats): Retrieve a breakdown of assistant query counts by caller type. -- [Get search queries](/api/analytics/searches): Export documentation search terms and analytics. -- [Get page views](/api/analytics/views): Export per-page and site-wide content view counts. -- [Get unique visitors](/api/analytics/visitors): Export per-page and site-wide unique visitor counts. - -### Common use cases - -- **Automated deployments**: Trigger site updates at set intervals or when events occur with [Trigger update](/api/update/trigger) and [Get update status](/api/update/status). -- **CI/CD integration**: Update documentation as part of your deployment pipeline when code changes with [Trigger update](/api/update/trigger). -- **Preview deployments**: Create or update preview deployments programmatically in your CI/CD pipeline with [Trigger preview deployment](/api/preview/trigger). -- **Custom integrations**: Embed the AI assistant into your product, support portal, or internal tools with [Create assistant message](/api/assistant/create-assistant-message-v2), [Search documentation](/api/assistant/search), and [Get page content](/api/assistant/get-page-content). -- **Automated editing**: Use agent jobs to programmatically update documentation at scale with [Create agent job](/api/agent/v2/create-agent-job), [Get agent job](/api/agent/v2/get-agent-job), and [Send follow-up message](/api/agent/v2/send-message). -- **Analytics export**: Export feedback, assistant conversations, search analytics, page views, and visitor data for external analysis with [Get user feedback](/api/analytics/feedback), [Get feedback by page](/api/analytics/feedback-by-page), [Get assistant conversations](/api/analytics/assistant-conversations), [Get assistant caller stats](/api/analytics/assistant-caller-stats), [Get search queries](/api/analytics/searches), [Get page views](/api/analytics/views), and [Get unique visitors](/api/analytics/visitors). +The Mintlify REST API lets you integrate your documentation platform into your own workflows and products. -## Authentication +## What you can do + +| Area | Endpoints | +|---|---| +| **Deployments** | Trigger updates, check deployment status, create preview deployments | +| **Agent** | Create and monitor agent jobs that automatically edit your docs | +| **Assistant** | Embed the AI assistant into any application; search and retrieve page content | +| **Analytics** | Export feedback, assistant conversations, search terms, page views, and visitor counts | -Generate API keys on the [API keys page](https://app.mintlify.com/settings/organization/api-keys) in your dashboard. Each API key belongs to an organization--you can use keys across multiple deployments within the same organization. +## Authentication -You can create up to 10 API keys per hour per organization. +Generate API keys on the [API keys page](https://app.mintlify.com/settings/organization/api-keys) in your dashboard. Keys belong to an organization and work across all projects in that organization. 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), [Trigger preview deployment](/api/preview/trigger), [Create agent job](/api/agent/v2/create-agent-job), [Get agent job](/api/agent/v2/get-agent-job), [Send follow-up message](/api/agent/v2/send-message), [Get user feedback](/api/analytics/feedback), [Get feedback by page](/api/analytics/feedback-by-page), [Get assistant conversations](/api/analytics/assistant-conversations), [Get assistant caller stats](/api/analytics/assistant-caller-stats), [Get search queries](/api/analytics/searches), [Get page views](/api/analytics/views), and [Get unique visitors](/api/analytics/visitors). - -Admin API keys begin with the `mint_` prefix. +Admin keys begin with `mint_`. Use them to authenticate requests to the **Deployments**, **Agent**, and **Analytics** endpoints. -The admin API key is a server-side secret. Do not expose it in client-side code. +Admin keys are server-side secrets. Do not expose them in client-side code. ### Assistant API key -Use the assistant API key to authenticate requests to [Create assistant message](/api/assistant/create-assistant-message-v2), [Search documentation](/api/assistant/search), and [Get page content](/api/assistant/get-page-content) endpoints. +Assistant keys begin with `mint_dsc_`. Use them to authenticate requests to the **Assistant** endpoints. -Assistant API keys begin with the `mint_dsc_` prefix. - -The assistant API key is a public token that you can reference in frontend code. +Assistant keys are public tokens safe for use in frontend code. - Calls using the assistant API token can incur costs: either using your assistant credits or incurring overages. + Assistant API calls consume assistant credits or incur overages on your plan. + +## Common use cases + +- **Automated deployments** — Trigger site updates on a schedule or when events occur. Use [Trigger update](/api-reference/deployments/trigger-update) and poll [Get update status](/api-reference/deployments/get-update-status) to confirm completion. +- **CI/CD integration** — Update documentation as part of your deployment pipeline. Integrate [Trigger update](/api-reference/deployments/trigger-update) into your existing workflows. +- **Preview deployments** — Create branch previews automatically when pull requests are opened. Use [Trigger preview deployment](/api-reference/deployments/trigger-preview-deployment) in CI. +- **Embed the assistant** — Add an AI assistant trained on your docs to your product, support portal, or internal tools. See [Assistant message (AI SDK v5+)](/api/assistant/create-assistant-message-v2) and [Assistant message (AI SDK v4)](/api/assistant/create-assistant-message). +- **Programmatic editing** — Use agent jobs to update documentation at scale. See [Create agent job](/api-reference/agent/create-agent-job) and [Get agent job](/api-reference/agent/get-agent-job). +- **Analytics export** — Pull feedback, conversation history, and traffic data into external dashboards or data warehouses. diff --git a/api/preview/trigger.mdx b/api/preview/trigger.mdx deleted file mode 100644 index 5144977183..0000000000 --- a/api/preview/trigger.mdx +++ /dev/null @@ -1,20 +0,0 @@ ---- -title: "Trigger preview deployment" -openapi: "/openapi.json POST /project/preview/{projectId}" -keywords: ["preview", "preview deployment", "branch preview", "staging"] - ---- - -Use this endpoint to programmatically create or update a preview deployment for a Git branch. If a preview already exists for the specified branch, the endpoint triggers a redeployment instead of creating a duplicate. - -The response includes a `statusId` that you can pass to [Get deployment status](/api/update/status) to track the deployment progress. - -## Use cases - -- **CI/CD pipelines**: Automatically create preview deployments when users open or update pull requests. -- **Scheduled previews**: Build previews from long-running feature branches on a schedule. -- **Custom tooling**: Integrate preview creation into internal workflows or Slack bots. - -## Rate limits - -This endpoint allows up to 5 requests per minute per organization. diff --git a/api/update/status.mdx b/api/update/status.mdx deleted file mode 100644 index b7c9ba75b0..0000000000 --- a/api/update/status.mdx +++ /dev/null @@ -1,6 +0,0 @@ ---- -title: "Get deployment status" -openapi: "/openapi.json GET /project/update-status/{statusId}" -keywords: [ "update status", "deployment status", "check status" ] - ---- diff --git a/api/update/trigger.mdx b/api/update/trigger.mdx deleted file mode 100644 index 44fe1c86f9..0000000000 --- a/api/update/trigger.mdx +++ /dev/null @@ -1,6 +0,0 @@ ---- -title: "Trigger deployment" -openapi: "/openapi.json POST /project/update/{projectId}" -keywords: [ "trigger", "update", "deployment", "programmatic" ] - ---- diff --git a/discovery-openapi.json b/discovery-openapi.json index 89c64242e9..2f86b621cb 100644 --- a/discovery-openapi.json +++ b/discovery-openapi.json @@ -18,8 +18,8 @@ "paths": { "/v1/assistant/{domain}/message": { "post": { - "summary": "Assistant message v1", - "description": "Generates a response message from the assistant for the specified domain. Compatible with AI SDK v4.", + "summary": "Assistant message (AI SDK v4)", + "description": "Generates a streaming assistant response for the specified domain. Compatible with AI SDK v4. If you are using AI SDK v5 or later, use the [v2 endpoint](/api/assistant/create-assistant-message-v2) instead.\n\n**Rate limit:** 10,000 requests per organization per hour; 10,000 requests per IP per day.", "parameters": [ { "name": "domain", @@ -449,13 +449,20 @@ } } } - } + }, + "x-codeSamples": [ + { + "lang": "bash", + "label": "cURL", + "source": "curl -X POST https://api.mintlify.com/discovery/v1/assistant/my-domain/message \\\n -H \"Authorization: Bearer mint_dsc_xxxxx\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"fp\": \"anonymous\",\n \"messages\": [{\"id\": \"1\", \"role\": \"user\", \"content\": \"How do I get started?\", \"parts\": [{\"type\": \"text\", \"text\": \"How do I get started?\"}]}],\n \"retrievalPageSize\": 5\n }'" + } + ] } }, "/v2/assistant/{domain}/message": { "post": { - "summary": "Assistant message", - "description": "Generates a response message from the assistant for the specified domain. Compatible with AI SDK v5+.", + "summary": "Assistant message (AI SDK v5+)", + "description": "Generates a streaming assistant response for the specified domain. Compatible with AI SDK v5+. If you are using AI SDK v4, use the [v1 endpoint](/api/assistant/create-assistant-message) instead.\n\n**Rate limit:** 10,000 requests per organization per hour; 10,000 requests per IP per day.", "parameters": [ { "name": "domain", @@ -737,13 +744,20 @@ } } } - } + }, + "x-codeSamples": [ + { + "lang": "bash", + "label": "cURL", + "source": "curl -X POST https://api.mintlify.com/discovery/v2/assistant/my-domain/message \\\n -H \"Authorization: Bearer mint_dsc_xxxxx\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"fp\": \"anonymous\",\n \"messages\": [{\"id\": \"1\", \"role\": \"user\", \"parts\": [{\"type\": \"text\", \"text\": \"How do I get started?\"}]}],\n \"retrievalPageSize\": 5\n }'" + } + ] } }, "/v1/page/{domain}": { "post": { "summary": "Get page content", - "description": "Retrieve the full text content of a specific documentation page by its path. Use this after a search to fetch the complete content of a matching page.", + "description": "Retrieve the full text content of a specific documentation page by its path. Use this after a search to fetch the complete content of a matching page.\n\n**Rate limit:** 10,000 requests per organization per hour; 10,000 requests per IP per day.", "parameters": [ { "name": "domain", @@ -811,7 +825,14 @@ } } } - } + }, + "x-codeSamples": [ + { + "lang": "bash", + "label": "cURL", + "source": "curl -X POST https://api.mintlify.com/discovery/v1/page/my-domain \\\n -H \"Authorization: Bearer mint_dsc_xxxxx\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"path\": \"quickstart\"}'" + } + ] } }, "/v1/search/{domain}": { @@ -822,7 +843,7 @@ } }, "summary": "Search documentation", - "description": "Perform semantic and keyword searches across your documentation with configurable filtering and pagination.", + "description": "Perform semantic and keyword searches across your documentation with configurable filtering and pagination.\n\n**Rate limit:** 10,000 requests per organization per hour; 10,000 requests per IP per day.", "parameters": [ { "name": "domain", @@ -912,7 +933,14 @@ } } } - } + }, + "x-codeSamples": [ + { + "lang": "bash", + "label": "cURL", + "source": "curl -X POST https://api.mintlify.com/discovery/v1/search/my-domain \\\n -H \"Authorization: Bearer mint_dsc_xxxxx\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"query\": \"how to configure custom domain\", \"pageSize\": 5}'" + } + ] } } }, diff --git a/docs.json b/docs.json index f2051ed4c1..b12118077d 100644 --- a/docs.json +++ b/docs.json @@ -373,21 +373,23 @@ ] }, { - "group": "Admin", + "group": "Deployments", "icon": "activity", + "openapi": "admin-openapi.json", "pages": [ - "api/update/trigger", - "api/update/status", - "api/preview/trigger" + "POST /v1/project/update/{projectId}", + "GET /v1/project/update-status/{statusId}", + "POST /v1/project/preview/{projectId}" ] }, { "group": "Agent", "icon": "pen-line", + "openapi": "admin-openapi.json", "pages": [ - "api/agent/v2/create-agent-job", - "api/agent/v2/get-agent-job", - "api/agent/v2/send-message" + "POST /v2/agent/{projectId}/job", + "GET /v2/agent/{projectId}/job/{id}", + "POST /v2/agent/{projectId}/job/{id}/message" ] }, { @@ -395,6 +397,7 @@ "icon": "bot-message-square", "pages": [ "api/assistant/create-assistant-message-v2", + "api/assistant/create-assistant-message", "api/assistant/search", "api/assistant/get-page-content" ] @@ -402,14 +405,15 @@ { "group": "Analytics", "icon": "chart-line", + "openapi": "analytics.openapi.json", "pages": [ - "api/analytics/feedback", - "api/analytics/feedback-by-page", - "api/analytics/assistant-conversations", - "api/analytics/assistant-caller-stats", - "api/analytics/searches", - "api/analytics/views", - "api/analytics/visitors" + "GET /v1/analytics/{projectId}/feedback", + "GET /v1/analytics/{projectId}/feedback/by-page", + "GET /v1/analytics/{projectId}/assistant", + "GET /v1/analytics/{projectId}/assistant/caller-stats", + "GET /v1/analytics/{projectId}/searches", + "GET /v1/analytics/{projectId}/views", + "GET /v1/analytics/{projectId}/visitors" ] } ] @@ -447,6 +451,11 @@ "href": "https://mintlify.com/docs" }, "api": { + "openapi": [ + "admin-openapi.json", + "analytics.openapi.json", + "discovery-openapi.json" + ], "mdx": { "auth": { "method": "bearer" diff --git a/openapi.json b/openapi.json deleted file mode 100644 index 6101b08d45..0000000000 --- a/openapi.json +++ /dev/null @@ -1,310 +0,0 @@ -{ - "openapi": "3.0.1", - "info": { - "title": "Mintlify External API", - "description": "An API for Mintlify documentation management and resource access.", - "version": "1.0.0" - }, - "servers": [ - { - "url": "https://api.mintlify.com/v1" - } - ], - "security": [ - { - "bearerAuth": [] - } - ], - "x-mcp": { - "enabled": true - }, - "paths": { - "/project/update/{projectId}": { - "post": { - "summary": "Trigger update", - "description": "Queue a deployment update for your documentation project. Returns a status ID that can be used to track the update progress. The update is triggered from your configured deployment branch.", - "parameters": [ - { - "name": "projectId", - "in": "path", - "description": "Your project ID. Can be copied from the [API keys](https://app.mintlify.com/settings/organization/api-keys) page in your dashboard.", - "required": true, - "schema": { - "type": "string" - } - } - ], - "responses": { - "202": { - "description": "A successful response", - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "statusId": { - "type": "string", - "description": "The status ID of the triggered updated." - } - } - } - } - } - } - } - } - }, - "/project/update-status/{statusId}": { - "get": { - "summary": "Get update status", - "description": "Get the status of an update from the status ID", - "parameters": [ - { - "name": "statusId", - "in": "path", - "description": "The status ID of a triggered update.", - "required": true, - "schema": { - "type": "string" - } - } - ], - "responses": { - "200": { - "description": "A successful response", - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "_id": { - "type": "string", - "description": "The status ID of the triggered updated." - }, - "projectId": { - "type": "string", - "description": "The documentation project ID." - }, - "createdAt": { - "type": "string", - "description": "An ISODate with the specified datetime in UTC" - }, - "endedAt": { - "type": "string", - "description": "An ISODate with the specified datetime in UTC" - }, - "status": { - "type": "string", - "enum": ["queued", "in_progress", "success", "failure"], - "description": "The status of the update." - }, - "summary": { - "type": "string", - "description": "Summary of the status of the update" - }, - "logs": { - "type": "array", - "description": "An array of logs.", - "items": { - "type": "string" - } - }, - "subdomain": { - "type": "string", - "description": "The subdomain of the docs being updated." - }, - "screenshot": { - "type": "string", - "description": "A screenshot of the docs." - }, - "screenshotLight": { - "type": "string", - "description": "A screenshot of the docs." - }, - "screenshotDark": { - "type": "string", - "description": "A screenshot of the docs in dark mode." - }, - "author": { - "type": "object", - "description": "The author of the update.", - "nullable": true, - "properties": { - "name": { - "type": "string", - "description": "The name of the author." - }, - "avatarUrl": { - "type": "string", - "description": "URL of the author's avatar image." - }, - "githubUserId": { - "type": "number", - "description": "The author's GitHub user ID." - } - } - }, - "commit": { - "type": "object", - "description": "The commit details", - "properties": { - "sha": { - "type": "string", - "description": "The SHA of the commit." - }, - "ref": { - "type": "string", - "description": "The ref of the commit." - }, - "message": { - "type": "string", - "description": "The commit message." - }, - "filesChanged": { - "type": "object", - "description": "Details on the changed files.", - "properties": { - "added": { - "type": "array", - "description": "New files added.", - "items": { - "type": "string" - } - }, - "modified": { - "type": "array", - "description": "Existing files that were modified.", - "items": { - "type": "string" - } - }, - "removed": { - "type": "array", - "description": "Files that were removed.", - "items": { - "type": "string" - } - } - } - } - } - }, - "source": { - "type": "string", - "description": "The source of the update trigger.", - "enum": [ - "internal", - "github-app-installation", - "api", - "github", - "dashboard", - "gitlab", - "onboarding" - ] - } - } - } - } - } - } - } - } - }, - "/project/preview/{projectId}": { - "post": { - "summary": "Trigger preview deployment", - "description": "Create or update a preview deployment for a specific branch. If a preview already exists for the branch, it triggers a redeployment. Returns a status ID to track progress and the preview URL.", - "parameters": [ - { - "name": "projectId", - "in": "path", - "description": "Your project ID. Can be copied from the [API keys](https://app.mintlify.com/settings/organization/api-keys) page in your dashboard.", - "required": true, - "schema": { - "type": "string" - } - } - ], - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { - "type": "object", - "required": ["branch"], - "properties": { - "branch": { - "type": "string", - "description": "The name of the Git branch to create a preview deployment for.", - "minLength": 1 - } - } - } - } - } - }, - "responses": { - "202": { - "description": "Preview deployment queued successfully.", - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "statusId": { - "type": "string", - "description": "The status ID for tracking the preview deployment. Use this with the [Get deployment status](/api/update/status) endpoint." - }, - "previewUrl": { - "type": "string", - "description": "The URL where the preview deployment is hosted." - } - } - } - } - } - }, - "400": { - "description": "Invalid request. The `branch` field is required.", - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "error": { - "type": "string" - } - } - } - } - } - }, - "403": { - "description": "Preview deployments are not available on your current plan.", - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "error": { - "type": "string" - } - } - } - } - } - } - } - } - } - }, - "components": { - "securitySchemes": { - "bearerAuth": { - "type": "http", - "scheme": "bearer", - "description": "The Authorization header expects a Bearer token. Use an admin API key (prefixed with `mint_`). This is a server-side secret key. Generate one on the [API keys page](https://app.mintlify.com/settings/organization/api-keys) in your dashboard." - } - } - } -} diff --git a/redirects.json b/redirects.json index 2daa8081d1..0253a2120b 100644 --- a/redirects.json +++ b/redirects.json @@ -1,458 +1,510 @@ [ - { - "source": "/optimize/search-boost", - "destination": "/optimize/search" - }, - { - "source": "/ai/assistant", - "destination": "/assistant/index" - }, - { - "source": "/agent/linear", - "destination": "/agent/index" - }, - { - "source": "/es/agent/linear", - "destination": "/es/agent/index" - }, - { - "source": "/fr/agent/linear", - "destination": "/fr/agent/index" - }, - { - "source": "/zh/agent/linear", - "destination": "/zh/agent/index" - }, - { - "source": "/guides/support-center", - "destination": "/guides/help-center" - }, - { - "source": "/content/components/accordions", - "destination": "/components/accordions" - }, - { - "source": "/content/components/callouts", - "destination": "/components/callouts" - }, - { - "source": "/content/components/cards", - "destination": "/components/cards" - }, - { - "source": "/content/components/card-groups", - "destination": "/components/columns" - }, - { - "source": "/content/components/code-groups", - "destination": "/components/code-groups" - }, - { - "source": "/content/components/examples", - "destination": "/components/examples" - }, - { - "source": "/content/components/expandables", - "destination": "/components/expandables" - }, - { - "source": "/content/components/fields", - "destination": "/components/fields" - }, - { - "source": "/content/components/frames", - "destination": "/components/frames" - }, - { - "source": "/content/components/icons", - "destination": "/components/icons" - }, - { - "source": "/content/components/mermaid-diagrams", - "destination": "/components/mermaid-diagrams" - }, - { - "source": "/content/components/steps", - "destination": "/components/steps" - }, - { - "source": "/content/components/tabs", - "destination": "/components/tabs" - }, - { - "source": "/content/components/tooltips", - "destination": "/components/tooltips" - }, - { - "source": "/content/components/update", - "destination": "/components/update" - }, - { - "source": "/api-playground/openapi/setup", - "destination": "/api-playground/openapi-setup" - }, - { - "source": "/api-playground/openapi/writing-openapi", - "destination": "/api-playground/openapi-setup" - }, - { - "source": "/settings/authentication-personalization/*", - "destination": "/deploy/authentication-setup" - }, - { - "source": "/authentication-personalization/*", - "destination": "/deploy/authentication-setup" - }, - { - "source": "/deploy/personalization-setup", - "destination": "/create/personalization" - }, - { - "source": "/ai-ingestion", - "destination": "/ai/llmstxt" - }, - { - "source": "/api-reference/chat/*", - "destination": "/api/assistant/*" - }, - { - "source": "/api-reference/*", - "destination": "/api/*" - }, - { - "source": "/fr/api-reference/*", - "destination": "/fr/api/*" - }, - { - "source": "/es/api-reference/*", - "destination": "/es/api/*" - }, - { - "source": "/zh/api-reference/*", - "destination": "/zh/api/*" - }, - { - "source": "/editor/inline-ai", - "destination": "/editor/index" - }, - { - "source": "/editor/comments", - "destination": "/editor/index" - }, - { - "source": "/editor/suggestions", - "destination": "/editor/index" - }, - { - "source": "/es/editor/inline-ai", - "destination": "/es/editor/index" - }, - { - "source": "/es/editor/comments", - "destination": "/es/editor/index" - }, - { - "source": "/es/editor/suggestions", - "destination": "/es/editor/index" - }, - { - "source": "/fr/editor/inline-ai", - "destination": "/fr/editor/index" - }, - { - "source": "/fr/editor/comments", - "destination": "/fr/editor/index" - }, - { - "source": "/fr/editor/suggestions", - "destination": "/fr/editor/index" - }, - { - "source": "/zh/editor/inline-ai", - "destination": "/zh/editor/index" - }, - { - "source": "/zh/editor/comments", - "destination": "/zh/editor/index" - }, - { - "source": "/zh/editor/suggestions", - "destination": "/zh/editor/index" - }, - { - "source": "/editor/getting-started", - "destination": "/editor/index" - }, - { - "source": "/editor/content-management", - "destination": "/editor/index" - }, - { - "source": "/editor/publishing", - "destination": "/editor/publish" - }, - { - "source": "/editor/troubleshooting", - "destination": "/editor/index" - }, - { - "source": "/guides/analytics", - "destination": "/optimize/analytics" - }, - { - "source": "/guides/assistant", - "destination": "/ai/assistant" - }, - { - "source": "/api-playground/customization/adding-sdk-examples", - "destination": "/api-playground/adding-sdk-examples" - }, - { - "source": "/api-playground/customization/complex-data-types", - "destination": "/api-playground/complex-data-types" - }, - { - "source": "/api-playground/customization/managing-page-visibility", - "destination": "/api-playground/managing-page-visibility" - }, - { - "source": "/api-playground/customization/multiple-responses", - "destination": "/api-playground/multiple-responses" - }, - { - "source": "/settings/broken-links", - "destination": "/create/broken-links" - }, - { - "source": "/guides/changelogs", - "destination": "/create/changelogs" - }, - { - "source": "/code", - "destination": "/create/code" - }, - { - "source": "/components/files", - "destination": "/create/files" - }, - { - "source": "/image-embeds", - "destination": "/create/image-embeds" - }, - { - "source": "/list-table", - "destination": "/create/list-table" - }, - { - "source": "/reusable-snippets", - "destination": "/create/reusable-snippets" - }, - { - "source": "/text", - "destination": "/create/text" - }, - { - "source": "/settings/custom-404-page", - "destination": "/customize/custom-404-page" - }, - { - "source": "/settings/custom-domain", - "destination": "/customize/custom-domain" - }, - { - "source": "/settings/custom-scripts", - "destination": "/customize/custom-scripts" - }, - { - "source": "/react-components", - "destination": "/customize/react-components" - }, - { - "source": "/themes", - "destination": "/customize/themes" - }, - { - "source": "/advanced/dashboard/permissions", - "destination": "/dashboard/permissions" - }, - { - "source": "/advanced/dashboard/roles", - "destination": "/dashboard/roles" - }, - { - "source": "/advanced/dashboard/sso", - "destination": "/dashboard/sso" - }, - { - "source": "/settings/ci", - "destination": "/deploy/ci" - }, - { - "source": "/advanced/subpath/cloudflare", - "destination": "/deploy/cloudflare" - }, - { - "source": "/guides/csp-configuration", - "destination": "/deploy/csp-configuration" - }, - { - "source": "/guides/deployments", - "destination": "/deploy/deployments" - }, - { - "source": "/settings/github", - "destination": "/deploy/github" - }, - { - "source": "/settings/gitlab", - "destination": "/deploy/gitlab" - }, - { - "source": "/guides/monorepo", - "destination": "/deploy/monorepo" - }, - { - "source": "/settings/preview-deployments", - "destination": "/deploy/preview-deployments" - }, - { - "source": "/guides/reverse-proxy", - "destination": "/deploy/reverse-proxy" - }, - { - "source": "/advanced/subpath/route53-cloudfront", - "destination": "/deploy/route53-cloudfront" - }, - { - "source": "/advanced/subpath/vercel", - "destination": "/deploy/vercel" - }, - { - "source": "/editor/branches", - "destination": "/guides/branches" - }, - { - "source": "/editor/git-concepts", - "destination": "/guides/git-concepts" - }, - { - "source": "/analytics/improving-docs", - "destination": "/guides/improving-docs" - }, - { - "source": "/api-playground/migrating-from-mdx", - "destination": "/guides/migrating-from-mdx" - }, - { - "source": "/guides/migration", - "destination": "/migration" - }, - { - "source": "/settings/seo", - "destination": "/optimize/seo" - }, - { - "source": "/guides/hidden-page-example", - "destination": "/organize/hidden-page-example" - }, - { - "source": "/guides/hidden-pages", - "destination": "/organize/hidden-pages" - }, - { - "source": "/navigation", - "destination": "/organize/navigation" - }, - { - "source": "/pages", - "destination": "/organize/pages" - }, - { - "source": "/settings", - "destination": "/organize/settings" - }, - { - "source": "/api-playground/mdx/:slug*", - "destination": "/api-playground/mdx-setup" - }, - { - "source": "/api-playground/asyncapi/setup", - "destination": "/api-playground/asyncapi-setup" - }, - { - "source": "/create/broken-links", - "destination": "/create/redirects" - }, - { - "source": "/ai/autopilot", - "destination": "/ai/suggestions" - }, - { - "source": "/ai/slack-app", - "destination": "/ai/slack-bot" - }, - { - "source": "/changelog/overview", - "destination": "/changelog" - }, - { - "source": "/ai/agent", - "destination": "/agent/index" - }, - { - "source": "/ai/suggestions", - "destination": "/agent/suggestions" - }, - { - "source": "/insights/overview", - "destination": "/optimize/analytics" - }, - { - "source": "/insights/feedback", - "destination": "/optimize/feedback" - }, - { - "source": "/migration-services/custom", - "destination": "/migration-services/enterprise" - }, - { - "source": "/agent/suggestions", - "destination": "/workflows/index" - }, - { - "source": "/agent/workflows", - "destination": "/workflows/index" - }, - { - "source": "/agent/workflows/:page", - "destination": "/workflows/:page" - }, - { - "source": "/agent/quickstart", - "destination": "/agent/index" - }, - { - "source": "/installation", - "destination": "/cli/install" - }, - { - "source": "/settings/global", - "destination": "/organize/settings" - }, - { - "source": "/editor/git-essentials", - "destination": "/editor/branching-and-publishing" - }, - { - "source": "/editor/publish", - "destination": "/editor/branching-and-publishing" - }, - { - "source": "/editor/media", - "destination": "/editor/pages" - }, - { - "source": "/workflows/enable", - "destination": "/workflows/manage" - } - ] + { + "source": "/optimize/search-boost", + "destination": "/optimize/search" + }, + { + "source": "/ai/assistant", + "destination": "/assistant/index" + }, + { + "source": "/agent/linear", + "destination": "/agent/index" + }, + { + "source": "/es/agent/linear", + "destination": "/es/agent/index" + }, + { + "source": "/fr/agent/linear", + "destination": "/fr/agent/index" + }, + { + "source": "/zh/agent/linear", + "destination": "/zh/agent/index" + }, + { + "source": "/guides/support-center", + "destination": "/guides/help-center" + }, + { + "source": "/content/components/accordions", + "destination": "/components/accordions" + }, + { + "source": "/content/components/callouts", + "destination": "/components/callouts" + }, + { + "source": "/content/components/cards", + "destination": "/components/cards" + }, + { + "source": "/content/components/card-groups", + "destination": "/components/columns" + }, + { + "source": "/content/components/code-groups", + "destination": "/components/code-groups" + }, + { + "source": "/content/components/examples", + "destination": "/components/examples" + }, + { + "source": "/content/components/expandables", + "destination": "/components/expandables" + }, + { + "source": "/content/components/fields", + "destination": "/components/fields" + }, + { + "source": "/content/components/frames", + "destination": "/components/frames" + }, + { + "source": "/content/components/icons", + "destination": "/components/icons" + }, + { + "source": "/content/components/mermaid-diagrams", + "destination": "/components/mermaid-diagrams" + }, + { + "source": "/content/components/steps", + "destination": "/components/steps" + }, + { + "source": "/content/components/tabs", + "destination": "/components/tabs" + }, + { + "source": "/content/components/tooltips", + "destination": "/components/tooltips" + }, + { + "source": "/content/components/update", + "destination": "/components/update" + }, + { + "source": "/api-playground/openapi/setup", + "destination": "/api-playground/openapi-setup" + }, + { + "source": "/api-playground/openapi/writing-openapi", + "destination": "/api-playground/openapi-setup" + }, + { + "source": "/settings/authentication-personalization/*", + "destination": "/deploy/authentication-setup" + }, + { + "source": "/authentication-personalization/*", + "destination": "/deploy/authentication-setup" + }, + { + "source": "/deploy/personalization-setup", + "destination": "/create/personalization" + }, + { + "source": "/ai-ingestion", + "destination": "/ai/llmstxt" + }, + { + "source": "/api-reference/chat/*", + "destination": "/api/assistant/*" + }, + { + "source": "/api-reference/*", + "destination": "/api/*" + }, + { + "source": "/fr/api-reference/*", + "destination": "/fr/api/*" + }, + { + "source": "/es/api-reference/*", + "destination": "/es/api/*" + }, + { + "source": "/zh/api-reference/*", + "destination": "/zh/api/*" + }, + { + "source": "/editor/inline-ai", + "destination": "/editor/index" + }, + { + "source": "/editor/comments", + "destination": "/editor/index" + }, + { + "source": "/editor/suggestions", + "destination": "/editor/index" + }, + { + "source": "/es/editor/inline-ai", + "destination": "/es/editor/index" + }, + { + "source": "/es/editor/comments", + "destination": "/es/editor/index" + }, + { + "source": "/es/editor/suggestions", + "destination": "/es/editor/index" + }, + { + "source": "/fr/editor/inline-ai", + "destination": "/fr/editor/index" + }, + { + "source": "/fr/editor/comments", + "destination": "/fr/editor/index" + }, + { + "source": "/fr/editor/suggestions", + "destination": "/fr/editor/index" + }, + { + "source": "/zh/editor/inline-ai", + "destination": "/zh/editor/index" + }, + { + "source": "/zh/editor/comments", + "destination": "/zh/editor/index" + }, + { + "source": "/zh/editor/suggestions", + "destination": "/zh/editor/index" + }, + { + "source": "/editor/getting-started", + "destination": "/editor/index" + }, + { + "source": "/editor/content-management", + "destination": "/editor/index" + }, + { + "source": "/editor/publishing", + "destination": "/editor/publish" + }, + { + "source": "/editor/troubleshooting", + "destination": "/editor/index" + }, + { + "source": "/guides/analytics", + "destination": "/optimize/analytics" + }, + { + "source": "/guides/assistant", + "destination": "/ai/assistant" + }, + { + "source": "/api-playground/customization/adding-sdk-examples", + "destination": "/api-playground/adding-sdk-examples" + }, + { + "source": "/api-playground/customization/complex-data-types", + "destination": "/api-playground/complex-data-types" + }, + { + "source": "/api-playground/customization/managing-page-visibility", + "destination": "/api-playground/managing-page-visibility" + }, + { + "source": "/api-playground/customization/multiple-responses", + "destination": "/api-playground/multiple-responses" + }, + { + "source": "/settings/broken-links", + "destination": "/create/broken-links" + }, + { + "source": "/guides/changelogs", + "destination": "/create/changelogs" + }, + { + "source": "/code", + "destination": "/create/code" + }, + { + "source": "/components/files", + "destination": "/create/files" + }, + { + "source": "/image-embeds", + "destination": "/create/image-embeds" + }, + { + "source": "/list-table", + "destination": "/create/list-table" + }, + { + "source": "/reusable-snippets", + "destination": "/create/reusable-snippets" + }, + { + "source": "/text", + "destination": "/create/text" + }, + { + "source": "/settings/custom-404-page", + "destination": "/customize/custom-404-page" + }, + { + "source": "/settings/custom-domain", + "destination": "/customize/custom-domain" + }, + { + "source": "/settings/custom-scripts", + "destination": "/customize/custom-scripts" + }, + { + "source": "/react-components", + "destination": "/customize/react-components" + }, + { + "source": "/themes", + "destination": "/customize/themes" + }, + { + "source": "/advanced/dashboard/permissions", + "destination": "/dashboard/permissions" + }, + { + "source": "/advanced/dashboard/roles", + "destination": "/dashboard/roles" + }, + { + "source": "/advanced/dashboard/sso", + "destination": "/dashboard/sso" + }, + { + "source": "/settings/ci", + "destination": "/deploy/ci" + }, + { + "source": "/advanced/subpath/cloudflare", + "destination": "/deploy/cloudflare" + }, + { + "source": "/guides/csp-configuration", + "destination": "/deploy/csp-configuration" + }, + { + "source": "/guides/deployments", + "destination": "/deploy/deployments" + }, + { + "source": "/settings/github", + "destination": "/deploy/github" + }, + { + "source": "/settings/gitlab", + "destination": "/deploy/gitlab" + }, + { + "source": "/guides/monorepo", + "destination": "/deploy/monorepo" + }, + { + "source": "/settings/preview-deployments", + "destination": "/deploy/preview-deployments" + }, + { + "source": "/guides/reverse-proxy", + "destination": "/deploy/reverse-proxy" + }, + { + "source": "/advanced/subpath/route53-cloudfront", + "destination": "/deploy/route53-cloudfront" + }, + { + "source": "/advanced/subpath/vercel", + "destination": "/deploy/vercel" + }, + { + "source": "/editor/branches", + "destination": "/guides/branches" + }, + { + "source": "/editor/git-concepts", + "destination": "/guides/git-concepts" + }, + { + "source": "/analytics/improving-docs", + "destination": "/guides/improving-docs" + }, + { + "source": "/api-playground/migrating-from-mdx", + "destination": "/guides/migrating-from-mdx" + }, + { + "source": "/guides/migration", + "destination": "/migration" + }, + { + "source": "/settings/seo", + "destination": "/optimize/seo" + }, + { + "source": "/guides/hidden-page-example", + "destination": "/organize/hidden-page-example" + }, + { + "source": "/guides/hidden-pages", + "destination": "/organize/hidden-pages" + }, + { + "source": "/navigation", + "destination": "/organize/navigation" + }, + { + "source": "/pages", + "destination": "/organize/pages" + }, + { + "source": "/settings", + "destination": "/organize/settings" + }, + { + "source": "/api-playground/mdx/:slug*", + "destination": "/api-playground/mdx-setup" + }, + { + "source": "/api-playground/asyncapi/setup", + "destination": "/api-playground/asyncapi-setup" + }, + { + "source": "/create/broken-links", + "destination": "/create/redirects" + }, + { + "source": "/ai/autopilot", + "destination": "/ai/suggestions" + }, + { + "source": "/ai/slack-app", + "destination": "/ai/slack-bot" + }, + { + "source": "/changelog/overview", + "destination": "/changelog" + }, + { + "source": "/ai/agent", + "destination": "/agent/index" + }, + { + "source": "/ai/suggestions", + "destination": "/agent/suggestions" + }, + { + "source": "/insights/overview", + "destination": "/optimize/analytics" + }, + { + "source": "/insights/feedback", + "destination": "/optimize/feedback" + }, + { + "source": "/migration-services/custom", + "destination": "/migration-services/enterprise" + }, + { + "source": "/agent/suggestions", + "destination": "/workflows/index" + }, + { + "source": "/agent/workflows", + "destination": "/workflows/index" + }, + { + "source": "/agent/workflows/:page", + "destination": "/workflows/:page" + }, + { + "source": "/agent/quickstart", + "destination": "/agent/index" + }, + { + "source": "/installation", + "destination": "/cli/install" + }, + { + "source": "/settings/global", + "destination": "/organize/settings" + }, + { + "source": "/editor/git-essentials", + "destination": "/editor/branching-and-publishing" + }, + { + "source": "/editor/publish", + "destination": "/editor/branching-and-publishing" + }, + { + "source": "/editor/media", + "destination": "/editor/pages" + }, + { + "source": "/workflows/enable", + "destination": "/workflows/manage" + }, + { + "source": "/api/update/trigger", + "destination": "/api-reference/deployments/trigger-update" + }, + { + "source": "/api/update/status", + "destination": "/api-reference/deployments/get-update-status" + }, + { + "source": "/api/preview/trigger", + "destination": "/api-reference/deployments/trigger-preview-deployment" + }, + { + "source": "/api/agent/v2/create-agent-job", + "destination": "/api-reference/agent/create-agent-job" + }, + { + "source": "/api/agent/v2/get-agent-job", + "destination": "/api-reference/agent/get-agent-job" + }, + { + "source": "/api/agent/v2/send-message", + "destination": "/api-reference/agent/send-follow-up-message" + }, + { + "source": "/api/analytics/feedback", + "destination": "/api-reference/analytics/get-user-feedback" + }, + { + "source": "/api/analytics/feedback-by-page", + "destination": "/api-reference/analytics/get-feedback-by-page" + }, + { + "source": "/api/analytics/assistant-conversations", + "destination": "/api-reference/analytics/get-assistant-conversations" + }, + { + "source": "/api/analytics/assistant-caller-stats", + "destination": "/api-reference/analytics/get-assistant-caller-stats" + }, + { + "source": "/api/analytics/searches", + "destination": "/api-reference/analytics/get-search-queries" + }, + { + "source": "/api/analytics/views", + "destination": "/api-reference/analytics/get-page-views" + }, + { + "source": "/api/analytics/visitors", + "destination": "/api-reference/analytics/get-unique-visitors" + } +] From 1796a34ed14d608d74c0a786c31e4a81e0b4cf8a Mon Sep 17 00:00:00 2001 From: Ethan Palm <56270045+ethanpalm@users.noreply.github.com> Date: Thu, 4 Jun 2026 17:15:07 -0700 Subject: [PATCH 2/2] split out assistant --- analytics.openapi.json | 5 +++++ api/assistant/create-assistant-message-v2.mdx | 10 ++++++---- api/assistant/create-assistant-message.mdx | 6 +++++- docs.json | 8 +++++++- 4 files changed, 23 insertions(+), 6 deletions(-) diff --git a/analytics.openapi.json b/analytics.openapi.json index 4559e14bba..a4ecbf4b6c 100644 --- a/analytics.openapi.json +++ b/analytics.openapi.json @@ -11,6 +11,11 @@ "description": "Production" } ], + "security": [ + { + "bearerAuth": [] + } + ], "components": { "securitySchemes": { "bearerAuth": { diff --git a/api/assistant/create-assistant-message-v2.mdx b/api/assistant/create-assistant-message-v2.mdx index e0af95cb14..f1df395941 100644 --- a/api/assistant/create-assistant-message-v2.mdx +++ b/api/assistant/create-assistant-message-v2.mdx @@ -1,5 +1,5 @@ --- -title: "Create assistant message" +title: "Assistant message (AI SDK v5+)" openapi: /discovery-openapi.json POST /v2/assistant/{domain}/message keywords: [ @@ -14,10 +14,12 @@ keywords: --- + + Each request consumes assistant credits or incurs overages on your plan. + + - The assistant message v2 endpoint is compatible with **AI SDK v5+**. If you - use AI SDK v4, use the [assistant message v1 - endpoint](/api/assistant/create-assistant-message) instead. + This endpoint is compatible with **AI SDK v5+**. If you use AI SDK v4, use the [assistant message (AI SDK v4)](/api/assistant/create-assistant-message) endpoint instead. ## Integration with `useChat` diff --git a/api/assistant/create-assistant-message.mdx b/api/assistant/create-assistant-message.mdx index b67d56eb44..d270bfa08e 100644 --- a/api/assistant/create-assistant-message.mdx +++ b/api/assistant/create-assistant-message.mdx @@ -4,8 +4,12 @@ openapi: /discovery-openapi.json POST /v1/assistant/{domain}/message keywords: ["assistant message", "embed", "chat", "integrate", "ai sdk v4", "useChat"] --- + + Each request consumes assistant credits or incurs overages on your plan. + + - Use this endpoint if you are on **AI SDK v4**. If you use AI SDK v5 or later, use the [assistant message v2 endpoint](/api/assistant/create-assistant-message-v2) instead. + This endpoint is compatible with **AI SDK v4**. If you use AI SDK v5 or later, use the [assistant message (AI SDK v5+)](/api/assistant/create-assistant-message-v2) endpoint instead. ## Integration with `useChat` diff --git a/docs.json b/docs.json index b12118077d..8a41702f62 100644 --- a/docs.json +++ b/docs.json @@ -397,7 +397,13 @@ "icon": "bot-message-square", "pages": [ "api/assistant/create-assistant-message-v2", - "api/assistant/create-assistant-message", + "api/assistant/create-assistant-message" + ] + }, + { + "group": "Search", + "icon": "search", + "pages": [ "api/assistant/search", "api/assistant/get-page-content" ]