Create agent job

Create an agent job that runs in the background and automatically creates a pull request with documentation changes.

POST /v2/agent/{projectId}/job

Create agent job

cURL

curl --request POST \
  --url https://api.mintlify.com/v2/agent/{projectId}/job \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "prompt": "<string>"
}
'

201

{
  "id": "<string>",
  "status": "active",
  "source": {
    "repository": "<string>",
    "ref": "<string>"
  },
  "model": "<string>",
  "prLink": "https://github.com/org/repo/pull/123",
  "createdAt": "2023-11-07T05:31:56Z",
  "archivedAt": "2023-11-07T05:31:56Z"
}

This endpoint creates a background agent job. The job runs asynchronously — use the get agent job endpoint to poll for status updates.

If the agent edits files successfully, a pull request is automatically created and the prLink field is populated in the job response.

Rate limits

• 100 uses per Mintlify project per hour

Usage

curl -X POST https://api.mintlify.com/v2/agent/{projectId}/job \
  -H "Authorization: Bearer mint_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{"prompt": "Add a quickstart guide for the Python SDK"}'

Authorizations

Authorization · string · header · required

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 in your dashboard.

Path Parameters

projectId · string · required

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

Body

application/json

prompt · string · required

The instruction for the agent to execute.

Minimum string length: 1

Response

201

application/json

Agent job created successfully

id · string

Unique identifier for the agent job.

status · enum<string>

Current status of the job. active — the agent is currently processing the prompt. completed — the agent finished successfully and a PR may have been created (check prLink). failed — the agent encountered an unrecoverable error. Poll until status is completed or failed.

Available options: active, completed, failed

source · object

Source repository information.

Show child attributes

model · string

The AI model used for this job.

prLink · string<uri> | null

GitHub pull request URL created by the agent. null while the job is still active or if no files were changed. Populated once the agent successfully creates a PR.

Example:

"https://github.com/org/repo/pull/123"

createdAt · string<date-time>

Timestamp when the job was created.

archivedAt · string<date-time> | null

Timestamp when the job was archived.