Create agent job

Create an agent job to automatically edit your documentation

This endpoint creates an agent job based on provided messages and branch information. The job executes asynchronously and returns a streaming response with the execution details and results.

If a branch doesn’t exist, the agent creates one. If files are edited successfully, a pull request is automatically created at the end of the job.

Rate limits

The agent API has the following limits:

• 100 uses per Mintlify project per hour

Suggested usage

For best results, use the useChat hook from ai-sdk to send requests and handle responses.

cURL

curl -X POST https://api.mintlify.com/v1/agent/{projectId}/job \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "branch": "agent-update-docs",
    "messages": [
      {
        "role": "user",
        "content": "Update the introduction page to include information about our new API endpoint"
      }
    ],
    "asDraft": false,
    "model": "sonnet"
  }'

Endpoint

projectId · string · required

Your project ID. Can be copied from the API keys page in your dashboard.

Request Body

branch · string · required

The name of the Git branch that the agent should work on. Will be automatically created if it doesn’t exist.

messages · array · required

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.

Show message object

role · string · required

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 · string · required

The content of the message.

asDraft · boolean · default: "false"

Control whether the pull request is created in draft or non-draft mode. When true, creates a draft pull request. When false (default), creates a regular pull request ready for review.

model · string · default: "sonnet"

The AI model to use for the agent job. Use sonnet for faster, cost-effective processing. Use opus for more capable, but slower processing.

Response

The endpoint returns a streaming text response containing the agent job execution details and results. The response includes an X-Message-Id header containing the message identifier for the created job.

Streaming Response

Agent job started...
Reading documentation files...
Updating introduction.mdx...
Creating pull request...
Pull request created: https://github.com/your-org/your-repo/pull/123
Agent job completed successfully.

Authentication

This endpoint requires an admin API key (prefixed with mint_). Generate one on the API keys page in your dashboard.