# Create agent job (/api/agent/v2/create-agent-job)

<!-- agent-signals: reading_time_min: 2 · est_tokens: 1245 · updated: 2026-07-30 -->
Related: [Get agent job](/api/agent/v2/get-agent-job.md), [Send follow-up message](/api/agent/v2/send-message.md), [Guides](/guides.md)

This endpoint creates a background agent job. The job runs asynchronously. Use the [get agent job](/api/agent/v2/get-agent-job) endpoint to poll for status updates.

If the agent edits files successfully, Mintlify creates a pull request and populates the `prLink` field in the job response.

## Rate limits [#rate-limits]

* 100 uses per Mintlify project per hour

## Usage [#usage]

```bash
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"}'
```

`POST /v2/agent/{projectId}/job`

Creates a new agent job that runs in the background. The job processes the prompt asynchronously — poll the get job endpoint to track progress. If the agent edits files successfully, a pull request is automatically created.

Authenticate with an admin API key.

## OpenAPI

```json
{
  "security": [
    {
      "bearerAuth": []
    }
  ],
  "parameters": [
    {
      "name": "projectId",
      "in": "path",
      "required": true,
      "schema": {
        "type": "string"
      },
      "description": "Your project ID. Can be copied from the [API keys](https://app.mintlify.com/settings/organization/api-keys) page in your dashboard."
    }
  ],
  "requestBody": {
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "type": "object",
          "required": [
            "prompt"
          ],
          "properties": {
            "prompt": {
              "type": "string",
              "minLength": 1,
              "description": "The instruction for the agent to execute."
            }
          }
        }
      }
    }
  },
  "responses": {
    "201": {
      "description": "Agent job created successfully",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "id": {
                "type": "string",
                "description": "Unique identifier for the agent job."
              },
              "status": {
                "type": "string",
                "enum": [
                  "active",
                  "completed",
                  "archived",
                  "failed"
                ],
                "description": "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`). `archived` — the job has been archived. `failed` — the agent encountered an unrecoverable error. Poll until status is `completed`, `archived`, or `failed`."
              },
              "source": {
                "type": "object",
                "description": "Source repository information.",
                "properties": {
                  "repository": {
                    "type": "string",
                    "description": "Full URL of the GitHub repository."
                  },
                  "ref": {
                    "type": "string",
                    "description": "Git branch the agent is working on.",
                    "nullable": true
                  }
                }
              },
              "model": {
                "type": "string",
                "description": "The AI model used for this job."
              },
              "prLink": {
                "type": "string",
                "format": "uri",
                "example": "https://github.com/org/repo/pull/123",
                "description": "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.",
                "nullable": true
              },
              "createdAt": {
                "type": "string",
                "format": "date-time",
                "description": "Timestamp when the job was created."
              },
              "archivedAt": {
                "type": "string",
                "format": "date-time",
                "description": "Timestamp when the job was archived.",
                "nullable": true
              }
            }
          }
        }
      }
    },
    "400": {
      "description": "Invalid request",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "error": {
                "type": "string",
                "description": "Error message."
              }
            }
          }
        }
      }
    },
    "429": {
      "description": "Rate limit exceeded",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "error": {
                "type": "string",
                "description": "Error message."
              }
            }
          }
        }
      }
    }
  }
}
```