canonical: https://jentic.com/apis/mintlify.com/mintlify

# Mintlify API

Mintlify publishes official OpenAPI specifications for its REST API, split by surface and listed under 'OpenAPI Specs' in mintlify.com/docs/llms.txt. This Jentic specification is a curated, agent-optimized variant: it merges the four documents an agent needs (openapi.json, admin-openapi.json, discovery-openapi.json and analytics.openapi.json) into one, folding each document's server prefix into absolute paths so all 9 operations are callable from a single base URL. Mintlify is a documentation platform that publishes developer docs sites and ships an AI assistant for end users. These operations cover deployment triggers, agent-driven documentation editing jobs, an assistant message endpoint, search over published docs, and analytics over feedback and assistant conversations. Useful for keeping docs deployed, programmatically editable, and queryable from automation.

## For AI agents

Trigger documentation deployments, run agent-driven doc edit jobs, query the AI assistant, and pull feedback analytics from a Mintlify project.

## Scope

Does not handle source code hosting, CI pipelines, or end-user authentication - use for documentation deployments, agent edits, and docs assistant queries only.

## Capabilities

- Trigger a fresh documentation deployment with POST `/v1/project/update/{projectId}` and poll status via GET `/v1/project/update-status/{statusId}`
- Create a Mintlify agent job to edit docs programmatically with POST `/v2/agent/{projectId}/job`
- Send a follow-up message into an existing agent job using POST `/v2/agent/{projectId}/job/{id}/message`
- Ask the docs AI assistant a question through POST `/discovery/v2/assistant/{domain}/message`
- Search a published documentation site with POST `/discovery/v1/search/{domain}`
- Pull thumbs-up and thumbs-down feedback from analytics via GET `/v1/analytics/{projectId}/feedback`
- Retrieve assistant conversation history with GET `/v1/analytics/{projectId}/assistant`

## Use cases

### CI-Triggered Docs Deployment

Kick off a Mintlify deployment from a CI pipeline by calling POST `/v1/project/update/{projectId}` after a docs commit lands. The status id returned can be polled until the build finishes, gating the release on a clean docs publish. Removes the need for a UI click on every release.

Example prompt: POST `/v1/project/update/{projectId}` after merge, then poll GET `/v1/project/update-status/{statusId}` every 10 seconds until status is success

### Agent-Authored Documentation Edits

Create a Mintlify agent job to draft new pages or fix existing ones with natural-language instructions via POST `/v2/agent/{projectId}/job.` Reviewers refine the output by sending follow-up messages into the same job, producing a doc PR without hand-editing markdown.

Example prompt: POST `/v2/agent/{projectId}/job` with instructions to add a webhooks page, then send refinement messages with POST `/v2/agent/{projectId}/job/{id}/message`

### Embedded Docs Q&A

Power an in-product help widget by calling the assistant message endpoint at POST `/discovery/v2/assistant/{domain}/message` with the user's question and the published docs domain. The response is a grounded answer over your documentation. Reduces support load by letting users self-serve common questions inside your app.

Example prompt: POST `/discovery/v2/assistant/{domain}/message` with the user's question and surface the answer in the in-product help drawer

### Docs Search Integration

Surface Mintlify-hosted docs results inside another tool with POST `/discovery/v1/search/{domain}.` The endpoint returns matching pages and snippets so the calling app can render its own search UI without forcing users to leave for the docs site.

Example prompt: POST `/discovery/v1/search/{domain}` with the query string and render the top 5 results inline in the developer dashboard

### Agent-Driven Docs Operations

An AI agent uses Jentic to keep docs healthy: deploy after every release, edit pages on demand from PR descriptions, and report on feedback. The Mintlify admin and assistant tokens stay in your Jentic One instance so the agent never holds them directly.

Example prompt: Search Jentic for 'trigger a docs deployment', load the Mintlify update schema, and deploy projectId after the release tag is pushed

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| POST | `/v1/project/update/{projectId}` | Trigger a docs deployment |
| GET | `/v1/project/update-status/{statusId}` | Get deployment status |
| POST | `/v2/agent/{projectId}/job` | Create an agent docs job |
| POST | `/v2/agent/{projectId}/job/{id}/message` | Send a follow-up message |
| POST | `/discovery/v2/assistant/{domain}/message` | Ask the docs assistant |
| POST | `/discovery/v1/search/{domain}` | Search published docs |
| GET | `/v1/analytics/{projectId}/feedback` | Get user feedback |

## Key resources

- **Project** — Trigger and monitor documentation deployments
- **Agent** — Create and continue agent-driven documentation edit jobs
- **Assistant** — Ask grounded questions of the docs AI assistant
- **Search** — Search published docs by domain
- **Analytics** — Retrieve feedback ratings and assistant conversations

## Why Jentic

- **Setup:** Wiring Mintlify by hand means managing two separate bearer tokens, admin and assistant, and picking the right one for deploys, agent jobs, and assistant queries against api.mintlify.com yourself. Through Jentic you install once, import Mintlify from the API Directory, store both tokens once, and your agent calls it.
- **Permission scoping:** Mintlify puts the project id and job id in the URL path (`/v1/project/update/{projectId}`, `/v2/agent/{projectId}/job/{id}`), so a rule can pin your agent to one project. You choose the operations it may call, so triggering a deployment is not included unless you add it.
- **Credential handling:** Your Mintlify admin and assistant bearer tokens are stored once, encrypted, by your own Jentic One instance and the correct one is injected per operation at execution time. They never enter the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'trigger a docs deployment' or 'ask the docs assistant', and Jentic returns the matching Mintlify operation with its input schema and the matching token already wired so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **Stoplight** — Stoplight focuses on API design and reference docs derived from OpenAPI
- **Notion** — Notion stores internal source content that can feed into Mintlify pages
- **Linear** — Linear tracks the engineering work that lands in each docs deployment

## FAQ

### Does Mintlify publish an official OpenAPI specification?

Yes. Mintlify publishes six OpenAPI documents, one per surface, listed under 'OpenAPI Specs' in mintlify.com/docs/llms.txt: openapi.json, admin-openapi.json, discovery-openapi.json, analytics.openapi.json, index-openapi.json and static-export-openapi.json. The specification Jentic serves here is a curated variant rather than a copy of any one of them: it merges the four documents that cover deployments, agent jobs, the assistant and analytics into a single file and rewrites each server prefix as an absolute path, so an agent can reach all 9 operations from one base URL instead of switching between three. Every operation here appears in Mintlify's own documents; the vendor set also carries 19 operations this variant does not, including preview deployments, static export and the wider analytics exports.

### Is there a Mintlify MCP server?

Yes. Mintlify runs a hosted admin MCP server at mcp.mintlify.com that AI tools connect to over an interactive OAuth login, and its documented tools edit pages, restructure navigation, update docs.json and open pull requests. Connecting Mintlify API directly through Jentic reaches a different surface: your agent gets all 9 REST operations from the spec, including the deployment trigger, agent jobs, the assistant, docs search and the analytics exports, which the admin MCP's documented tools do not cover. Connecting direct also keeps another server's tool definitions out of your agent's context, because Jentic returns operations on demand, and your own rules decide which of them the agent may call, where an admin MCP session inherits whatever permissions your Mintlify account already carries. Adding the next API is another import rather than another install and login.

### What authentication does the Mintlify API use?

HTTP bearer tokens in the Authorization header. Mintlify documents three API key types, and two of them apply to the 9 operations here: the admin key (prefix `mint_`) authenticates the project, agent and analytics operations, and the assistant key (prefix `mint_dsc_`) authenticates the discovery assistant and search operations. The third, the Index key (prefix `mint_us_`), belongs to Mintlify's separate Index API on a different host and is not used by anything on this page. Your own Jentic One instance holds both keys and injects the right one per operation.

### Do I need a paid Mintlify plan to call these operations?

Yes. Mintlify's REST API introduction states that 'The platform REST API requires a Pro or Enterprise plan', and all 9 operations on this page sit on that platform surface: deployments, agent jobs, the assistant, docs search and the analytics exports. A project on any other plan cannot call them, so confirm the organization's plan before you wire an agent to Mintlify. Plan tiers are listed at mintlify.com/pricing.

### Can I deploy my docs from CI with the Mintlify API?

Yes. Call POST `/v1/project/update/{projectId}` after the docs commit lands; the response returns a status id. Poll GET `/v1/project/update-status/{statusId}` until it reports a successful build.

### How do agent jobs differ from a normal deployment?

Agent jobs at POST `/v2/agent/{projectId}/job` ask Mintlify's documentation agent to draft or edit pages from natural-language instructions. The agent produces a draft you can refine via follow-up messages on `/v2/agent/{projectId}/job/{id}/message.` Deployments simply rebuild and publish the current source.

### How do I query the docs assistant through Jentic?

Install Jentic One on your own machine, import Mintlify API from the Jentic API Directory, then have your agent search by intent for 'ask the docs assistant'. Jentic returns POST `/discovery/v2/assistant/{domain}/message` with its input schema and the assistant key already wired. Provide the published docs domain and the user question; the answer comes back grounded on the docs content.

### How do I monitor docs feedback and assistant conversations?

GET `/v1/analytics/{projectId}/feedback` returns thumbs-up and thumbs-down ratings on docs pages, while GET `/v1/analytics/{projectId}/assistant` returns conversation history. Schedule the agent to pull both endpoints daily and report on quality trends.

### Can I limit what my agent is allowed to do with the Mintlify API?

Yes. Because you run Jentic One yourself, your own rules decide which Mintlify operations and tokens the agent may use. Mintlify puts the project id and job id in the URL path, such as POST `/v1/project/update/{projectId}` and POST `/v2/agent/{projectId}/job`, so a rule can pin the agent to a single project. You pick the exact operations it can call, so a high-impact action like triggering a deployment is available only if you add it, while you keep read-only calls such as GET `/v1/analytics/{projectId}/feedback` separate.