admin-openapi.json

{
  "openapi": "3.0.1",
  "info": {
    "title": "Mintlify Admin API",
    "description": "API for managing documentation deployments and agent jobs.",
    "version": "2.0.0"
  },
  "servers": [
    {
      "url": "https://api.mintlify.com"
    }
  ],
  "security": [
    {
      "bearerAuth": []
    }
  ],
  "x-mcp": {
    "enabled": true
  },
  "paths": {
    "/v1/project/update/{projectId}": {
      "post": {
        "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",
              "example": "my-project-id"
            }
          }
        ],
        "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"
                    }
                  }
                }
              }
            }
          }
        },
        "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/project/update-status/{statusId}": {
      "get": {
        "summary": "Get update status",
        "description": "Get the status and details of a documentation update by its status ID.",
        "operationId": "getUpdateStatus",
        "tags": ["Deployments"],
        "parameters": [
          {
            "name": "statusId",
            "in": "path",
            "description": "The status ID returned by [Trigger update](#operation/triggerUpdate).",
            "required": true,
            "schema": {
              "type": "string",
              "example": "abc123def456"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Update details.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "_id": {
                      "type": "string",
                      "description": "The status ID of the update.",
                      "example": "abc123def456"
                    },
                    "projectId": {
                      "type": "string",
                      "description": "The documentation project ID.",
                      "example": "my-project-id"
                    },
                    "createdAt": {
                      "type": "string",
                      "description": "ISO 8601 timestamp when the update was created.",
                      "example": "2024-06-04T12:00:00.000Z"
                    },
                    "endedAt": {
                      "type": "string",
                      "description": "ISO 8601 timestamp when the update completed. Null if still in progress.",
                      "example": "2024-06-04T12:01:30.000Z"
                    },
                    "status": {
                      "type": "string",
                      "enum": ["queued", "in_progress", "success", "failure"],
                      "description": "Current status of the update.",
                      "example": "success"
                    },
                    "summary": {
                      "type": "string",
                      "description": "Summary of the update result.",
                      "example": "Deployed 3 changed pages"
                    },
                    "logs": {
                      "type": "array",
                      "description": "Array of log messages from the build.",
                      "items": {
                        "type": "string"
                      }
                    },
                    "subdomain": {
                      "type": "string",
                      "description": "The subdomain of the docs being updated.",
                      "example": "my-org"
                    },
                    "screenshotLight": {
                      "type": "string",
                      "description": "URL of a screenshot of the docs in light mode.",
                      "example": "https://cdn.mintlify.com/screenshots/abc123.png"
                    },
                    "screenshotDark": {
                      "type": "string",
                      "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/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",
              "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": {
          "202": {
            "description": "Preview deployment queued successfully.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "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": "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",
              "example": "my-project-id"
            },
            "description": "Your project ID. Copy it from the [API keys](https://app.mintlify.com/settings/organization/api-keys) page in your dashboard."
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["prompt"],
                "properties": {
                  "prompt": {
                    "type": "string",
                    "minLength": 1,
                    "description": "The instruction for the agent to execute.",
                    "example": "Add a quickstart guide for the Python SDK"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "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" }
              }
            }
          },
          "400": {
            "description": "Invalid request.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/Error" }
              }
            }
          },
          "429": {
            "description": "Rate limit exceeded.",
            "content": {
              "application/json": {
                "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": "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",
              "example": "my-project-id"
            },
            "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",
              "example": "job_abc123"
            },
            "description": "The unique identifier of the agent job."
          }
        ],
        "responses": {
          "200": {
            "description": "Agent job details.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/AgentJob" }
              }
            }
          },
          "404": {
            "description": "Job not found.",
            "content": {
              "application/json": {
                "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": "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",
              "example": "my-project-id"
            },
            "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",
              "example": "job_abc123"
            },
            "description": "The unique identifier of the agent job to send a message to."
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["prompt"],
                "properties": {
                  "prompt": {
                    "type": "string",
                    "minLength": 1,
                    "description": "The follow-up instruction for the agent.",
                    "example": "Also add error handling examples to the quickstart guide"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Message sent. Poll [Get agent job](#operation/getAgentJob) to track progress.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/AgentJob" }
              }
            }
          },
          "400": {
            "description": "Invalid request.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/Error" }
              }
            }
          },
          "404": {
            "description": "Job not found.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/Error" }
              }
            }
          },
          "429": {
            "description": "Rate limit exceeded.",
            "content": {
              "application/json": {
                "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" }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "AgentJob": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "Unique identifier for the agent job.",
            "example": "job_abc123"
          },
          "status": {
            "type": "string",
            "enum": ["active", "completed", "archived", "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",
            "description": "Source repository information.",
            "properties": {
              "repository": {
                "type": "string",
                "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,
                "example": "agent/add-python-quickstart"
              }
            }
          },
          "model": {
            "type": "string",
            "description": "The AI model used for this job.",
            "example": "claude-sonnet-4-5"
          },
          "prLink": {
            "type": "string",
            "format": "uri",
            "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.",
            "example": "2024-06-04T12:00:00.000Z"
          },
          "archivedAt": {
            "type": "string",
            "format": "date-time",
            "description": "Timestamp when the job was archived.",
            "nullable": true,
            "example": null
          }
        }
      },
      "Error": {
        "type": "object",
        "properties": {
          "error": {
            "type": "string",
            "description": "Error message.",
            "example": "Invalid request body"
          }
        }
      }
    },
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "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."
      }
    }
  }
}