openapi.json

{
  "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://dashboard.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://dashboard.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://dashboard.mintlify.com/settings/organization/api-keys) in your dashboard."
      }
    }
  }
}