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://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"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/workflow/{projectId}/{workflowSchemaId}/trigger": {
      "post": {
        "summary": "Trigger automation",
        "description": "Trigger a scheduled automation to run immediately, instead of waiting for its next scheduled time. Useful for running automations from CI/CD pipelines, like a GitHub Action that runs on every merge to your default branch. Only scheduled (custom schedule) automations can be triggered. The run picks up changes since the last completed run, identical to a regular scheduled run.",
        "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"
            }
          },
          {
            "name": "workflowSchemaId",
            "in": "path",
            "description": "The ID of the automation to trigger. Can be copied from the automation's settings panel on the [Automations](https://app.mintlify.com/products/automations) page in your dashboard.",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "202": {
            "description": "Automation run queued successfully.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "schemaId": {
                      "type": "string",
                      "description": "The ID of the triggered automation."
                    },
                    "instanceId": {
                      "type": "string",
                      "description": "The ID of the queued automation run. Appears in the run history on the [Automation Runs](https://app.mintlify.com/products/automations) page."
                    },
                    "jobId": {
                      "type": "string",
                      "description": "The ID of the background job processing the run."
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid request. The automation ID is malformed, the automation is not active, or the automation is not configured with a custom schedule.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "The automation was not found or does not belong to this project.",
            "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."
      }
    }
  }
}