mintlify__docs/admin-openapi.json

{
  "openapi": "3.0.1",
  "info": {
    "title": "Mintlify Admin API",
    "description": "An API for administrative operations including documentation updates and agent management.",
    "version": "1.0.0"
  },
  "servers": [
    {
      "url": "https://api.mintlify.com/v1"
    }
  ],
  "security": [
    {
      "bearerAuth": []
    }
  ],
  "paths": {
    "/agent/{projectId}/job": {
      "post": {
        "summary": "Create agent job",
        "description": "Creates a new agent job that can generate and edit documentation based on provided messages and branch information.",
        "parameters": [
          {
            "name": "projectId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Your project ID. Can be copied from the [API keys](https://dashboard.mintlify.com/settings/organization/api-keys) page in your dashboard."
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "branch",
                  "messages"
                ],
                "properties": {
                  "branch": {
                    "type": "string",
                    "description": "The name of the Git branch that the agent should work on, will be automatically created if it doesn't exist"
                  },
                  "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"],
                          "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)."
                        },
                        "content": {
                          "type": "string",
                          "description": "The content of the message."
                        }
                      }
                    }
                  },
                  "asDraft": {
                    "type": "boolean",
                    "default": true,
                    "description": "Control whether the pull request is created in draft or non-draft mode. When true, creates a draft pull request. When false, creates a regular (non-draft) 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 (streaming response). X-Session-Id Header is sent back in the response",
            "headers": {
              "X-Message-Id": {
                "schema": {
                  "type": "string"
                },
                "description": "Message identifier for the created job"
              }
            },
            "content": {
              "text/plain": {
                "schema": {
                  "type": "string",
                  "description": "Streaming response containing the agent job execution details and results."
                }
              }
            }
          }
        }
      }
    },
    "/agent/{projectId}/job/{id}": {
      "get": {
        "summary": "Get agent job by ID",
        "description": "Retrieves the details and status of a specific agent job by its ID.",
        "parameters": [
          {
            "name": "projectId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Your project ID. Can be copied from the [API keys](https://dashboard.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."
          }
        ],
        "responses": {
          "200": {
            "description": "Agent job details retrieved successfully",
            "content": {
              "application/json": {
                "schema": {
                  "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"],
                      "description": "Reason for session halt."
                    },
                    "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."
                          }
                        }
                      }
                    },
                    "createdAt": {
                      "type": "string",
                      "format": "date-time",
                      "description": "Timestamp when the session was created."
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/agent/{projectId}/jobs": {
      "get": {
        "summary": "Get all agent jobs",
        "description": "Retrieves all agent jobs for the specified domain, including their status and details.",
        "parameters": [
          {
            "name": "projectId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Your project ID. Can be copied from the [API keys](https://dashboard.mintlify.com/settings/organization/api-keys) page in your dashboard."
          }
        ],
        "responses": {
          "200": {
            "description": "All agent jobs retrieved 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"],
                            "description": "Reason for session halt."
                          },
                          "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."
                                }
                              }
                            }
                          },
                          "createdAt": {
                            "type": "string",
                            "format": "date-time",
                            "description": "Timestamp when the session was created."
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "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."
      }
    }
  }
}