Introduction

Trigger updates, embed AI assistant, and more

The Mintlify REST API enables you to programmatically interact with your documentation, trigger updates, and embed AI-powered chat experiences.

Endpoints

• Trigger update: Trigger an update of your site when desired.
• Get update status: Get the status of an update and other details about your docs.
• Create agent job: Create an agent job to automatically edit your documentation.
• Get agent job: Retrieve the details and status of a specific agent job.
• Get all agent jobs: Retrieve all agent jobs for a domain.
• Generate assistant message: Embed the assistant, trained on your docs, into any application of your choosing.
• Search documentation: Search through your documentation.

Authentication

You can generate an API key through the dashboard. API keys are associated with an entire organization and can be used across multiple deployments.

Admin API key

The admin API key is used for the Trigger update, Get update status, and all agent endpoints.

Admin API keys begin with the mint_ prefix. Keep your admin API keys secret.

Example request:

curl https://api.mintlify.com/v1/project/update/your-project-id \
  -H "Authorization: Bearer mint_your_api_key" \
  -H "Content-Type: application/json" \
  -X POST

Assistant API key

The assistant API key is used for the Generate assistant message and Search documentation endpoints.

Assistant API keys begin with the mint_dsc_ prefix.

The assistant API key is a server-side token that should be kept secret.

The assistant API token is a public token that can be referenced in your frontend code.

Example request:

curl https://api.mintlify.com/v1/assistant/message \
  -H "Authorization: Bearer mint_dsc_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "domain": "docs.example.com",
    "message": "How do I get started?"
  }' \
  -X POST

Calls using the assistant API token can incur costs: either using your AI assistant credits or incurring overages.

Rate limits

API requests are rate limited to prevent abuse:

Endpoint Type	Rate Limit
Admin endpoints	100 requests per minute
Assistant endpoints	1000 requests per minute

When you exceed the rate limit, you’ll receive a 429 Too Many Requests response.

Error handling

The API uses standard HTTP status codes to indicate success or failure:

Status Code	Description
200	Success
400	Bad request - check your request parameters
401	Unauthorized - invalid or missing API key
403	Forbidden - API key doesn’t have access to this resource
404	Not found - resource doesn’t exist
429	Too many requests - rate limit exceeded
500	Internal server error - contact support

Error response format:

{
  "error": {
    "code": "invalid_request",
    "message": "The project ID is invalid",
    "details": {
      "field": "projectId",
      "reason": "Project not found"
    }
  }
}

Handling errors in your code:

JavaScript

try {
  const response = await fetch('https://api.mintlify.com/v1/project/update/project-id', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer mint_your_api_key',
      'Content-Type': 'application/json'
    }
  });

  if (!response.ok) {
    const error = await response.json();
    console.error('API Error:', error.error.message);
    
    if (response.status === 429) {
      // Handle rate limit - implement retry with backoff
      console.log('Rate limited. Retrying after delay...');
    }
  }

  const data = await response.json();
  console.log('Success:', data);
} catch (error) {
  console.error('Network error:', error);
}

Best practices

Secure your API keys

• Never commit API keys to version control
• Use environment variables to store keys
• Rotate keys regularly
• Use separate keys for development and production

Implement retry logic

Network requests can fail. Implement exponential backoff for retries:

1. Wait 1 second after first failure
2. Wait 2 seconds after second failure
3. Wait 4 seconds after third failure
4. Give up after 3-5 attempts

Monitor usage

Track your API usage to:

• Identify performance issues
• Optimize request patterns
• Stay within rate limits
• Monitor costs (for assistant endpoints)