mirror of
https://github.com/mintlify/docs.git
synced 2026-09-14 13:35:46 +08:00
Ethan Palm
735 lines
26 KiB
JSON
735 lines
26 KiB
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."
|
|
}
|
|
}
|
|
}
|
|
}
|