# Crear tarea de agente (/es/api/agent/v2/create-agent-job)

<!-- agent-signals: reading_time_min: 3 · est_tokens: 1343 · updated: 2026-07-30 -->

Este endpoint crea una tarea de agente en segundo plano. La tarea se ejecuta de forma asíncrona. Usa el endpoint [get agent job](/es/api/agent/v2/get-agent-job) para consultar las actualizaciones de estado.

Si el agente edita los archivos correctamente, se crea automáticamente una solicitud de extracción y se rellena el campo `prLink` en la respuesta de la tarea.

<div id="rate-limits">
  ## Límites de uso [#límites-de-uso]
</div>

* 100 usos por hora por proyecto de Mintlify

<div id="usage">
  ## Uso [#uso]
</div>

```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`

Crea un nuevo trabajo del agente que se ejecuta en segundo plano. El trabajo procesa el prompt de forma asíncrona; consulta periódicamente el endpoint get job para seguir el progreso. Si el agente edita archivos correctamente, se crea automáticamente una solicitud de extracción.

Autentícate con una clave de API de administrador.

## OpenAPI

```json
{
  "security": [
    {
      "bearerAuth": []
    }
  ],
  "parameters": [
    {
      "name": "projectId",
      "in": "path",
      "required": true,
      "schema": {
        "type": "string"
      },
      "description": "El ID de tu proyecto. Puedes copiarlo desde la página de [API keys](https://dashboard.mintlify.com/settings/organization/api-keys) en tu dashboard."
    }
  ],
  "requestBody": {
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "type": "object",
          "required": [
            "prompt"
          ],
          "properties": {
            "prompt": {
              "type": "string",
              "minLength": 1,
              "description": "La instrucción que debe ejecutar el agente."
            }
          }
        }
      }
    }
  },
  "responses": {
    "201": {
      "description": "Trabajo del agente creado correctamente",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "id": {
                "type": "string",
                "description": "Identificador único del trabajo del agente."
              },
              "status": {
                "type": "string",
                "enum": [
                  "active",
                  "completed",
                  "archived",
                  "failed"
                ],
                "description": "Estado actual del trabajo. `active` — el agente está procesando la instrucción en este momento. `completed` — el agente finalizó correctamente y es posible que se haya creado una PR (verificar `prLink`). `archived` — el trabajo se ha archivado. `failed` — el agente encontró un error irrecuperable. Consulte periódicamente hasta que el estado sea `completed`, `archived` o `failed`."
              },
              "source": {
                "type": "object",
                "description": "Información del repositorio de origen.",
                "properties": {
                  "repository": {
                    "type": "string",
                    "description": "URL completa del repositorio de GitHub."
                  },
                  "ref": {
                    "type": "string",
                    "description": "branch de Git en la que trabaja el agente.",
                    "nullable": true
                  }
                }
              },
              "model": {
                "type": "string",
                "description": "El modelo de IA utilizado para esta tarea."
              },
              "prLink": {
                "type": "string",
                "format": "uri",
                "example": "https://github.com/org/repo/pull/123",
                "description": "URL de la solicitud de extracción de GitHub creada por el agente. `null` mientras la tarea siga `active` o si no se ha cambiado ningún archivo. Se completa cuando el agente crea correctamente una PR.",
                "nullable": true
              },
              "createdAt": {
                "type": "string",
                "format": "date-time",
                "description": "Marca de tiempo de creación de la tarea."
              },
              "archivedAt": {
                "type": "string",
                "format": "date-time",
                "description": "Marca de tiempo de archivado de la tarea.",
                "nullable": true
              }
            }
          }
        }
      }
    },
    "400": {
      "description": "Solicitud no válida",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "error": {
                "type": "string",
                "description": "Mensaje de error."
              }
            }
          }
        }
      }
    },
    "429": {
      "description": "superar el límite de solicitudes",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "error": {
                "type": "string",
                "description": "Mensaje de error."
              }
            }
          }
        }
      }
    }
  }
}
```