Create agent job (v2)

Create an agent job that runs in the background and returns immediately with status for polling.

POST /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": "<string>",
  "createdAt": "2023-11-07T05:31:56Z",
  "archivedAt": "2023-11-07T05:31:56Z"
}

This endpoint creates an agent job that runs in the background. Unlike the v1 API which streams responses, the v2 API returns immediately with a job ID that you can use to poll for status.

Key differences from v1

• Fire-and-forget: The request returns immediately with the job ID
• Polling-based: Use Get agent job to check status and retrieve the PR link
• Simplified request: Uses a single prompt string instead of a messages array
• Conversational: Send follow-up messages with Send message

Workflow

1. Create a job with this endpoint
2. Store the returned id
3. Poll the Get agent job endpoint until status is completed or failed
4. Retrieve the prLink from the response once the PR is created

Rate limits

The agent API has the following limits:

• 100 uses per Mintlify project per hour

Example polling workflow

async function runAgentJob(projectId, prompt, apiKey) {
  // Create the job
  const createResponse = await fetch(
    `https://api.mintlify.com/v2/agent/${projectId}/job`,
    {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${apiKey}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({ prompt })
    }
  );
  
  const job = await createResponse.json();
  const jobId = job.id;
  
  // Poll for completion
  while (true) {
    const statusResponse = await fetch(
      `https://api.mintlify.com/v2/agent/${projectId}/job/${jobId}`,
      {
        headers: { 'Authorization': `Bearer ${apiKey}` }
      }
    );
    
    const status = await statusResponse.json();
    
    if (status.status === 'completed' || status.status === 'failed') {
      return status;
    }
    
    // Wait before polling again
    await new Promise(resolve => setTimeout(resolve, 5000));
  }
}

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 task instructions for the agent to execute.

Response

201

application/json

Agent job created successfully. The job runs in the background.

id · string

Unique identifier for the agent job.

status · enum<string>

Current status of the agent job.

Available options: active, completed, archived, failed

source · object

Information about the source repository.

Show child attributes

model · string

The AI model used for this job.

prLink · string | null

URL of the pull request created by the agent. Null until the PR is created.

createdAt · string<date-time>

Timestamp when the job was created.

archivedAt · string<date-time> | null

Timestamp when the job was archived. Null if still active.