> ## Documentation Index
> Fetch the complete documentation index at: https://www.mintlify.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Create agent job (v1)

> Deprecated: use [v2 create agent job](/api/agent/v2/create-agent-job) instead. Creates a new agent job that can generate and edit documentation based on provided messages and branch information.

<Warning>This endpoint is deprecated. Use the [v2 create agent job](/api/agent/v2/create-agent-job) endpoint instead.</Warning>

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](https://ai-sdk.dev/docs/reference/ai-sdk-ui/use-chat#usechat) to send requests and handle responses.


## OpenAPI

````yaml /admin-openapi.json POST /v1/agent/{projectId}/job
openapi: 3.0.1
info:
  title: Mintlify Admin API
  description: >-
    An API for administrative operations including documentation updates and
    agent management.
  version: 2.0.0
servers:
  - url: https://api.mintlify.com
security:
  - bearerAuth: []
paths:
  /v1/agent/{projectId}/job:
    post:
      summary: Create agent job (v1)
      description: >-
        Deprecated: use [v2 create agent job](/api/agent/v2/create-agent-job)
        instead. Creates a new agent job that can generate and edit
        documentation based on provided messages and branch information.
      parameters:
        - name: projectId
          in: path
          required: true
          schema:
            type: string
          description: >-
            Your project ID. Can be copied from the [API
            keys](https://dashboard.mintlify.com/settings/organization/api-keys)
            page in your dashboard.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - messages
              properties:
                branch:
                  type: string
                  description: >-
                    The name of the Git branch that the agent should work on. If
                    omitted, the agent generates a branch name based on the
                    message content.
                messages:
                  type: array
                  description: >-
                    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.
                  items:
                    type: object
                    required:
                      - role
                      - content
                    properties:
                      role:
                        type: string
                        enum:
                          - system
                          - user
                          - assistant
                        description: >-
                          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). Use `assistant`
                          to provide example assistant responses for few-shot
                          prompting.
                      content:
                        type: string
                        description: The content of the message.
                asDraft:
                  type: boolean
                  default: false
                  description: >-
                    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:
                  type: string
                  enum:
                    - sonnet
                    - opus
                  default: sonnet
                  description: >-
                    The AI model to use for the agent job. Use `sonnet` for
                    faster, cost-effective processing. Use `opus` for more
                    capable, but slower processing.
      responses:
        '200':
          description: >-
            Agent job created successfully. Returns a streaming response with
            Server-Sent Events.
          headers:
            X-Session-Id:
              schema:
                type: string
              description: Unique session identifier for the created agent job.
            X-Branch-Name:
              schema:
                type: string
              description: Git branch name where the agent is making changes.
          content:
            text/event-stream:
              schema:
                type: string
                description: >-
                  Server-Sent Events stream containing the agent job execution
                  details and results.
      deprecated: true
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: >-
        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](https://dashboard.mintlify.com/settings/organization/api-keys) in
        your dashboard.

````

## Related topics

- [Introduction](/docs/api/introduction.md)
- [Visibility](/docs/components/visibility.md)
- [Create agent job](/docs/api/agent/v2/create-agent-job.md)