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

# Crear task

> Crear una nueva tarea automática para un agente.

## Endpoint

```
POST /api/tasks
```

## Headers

<ParamField header="Authorization" type="string" required>
  Bearer token con tu API key. Formato: `Bearer sk_live_xxx`
</ParamField>

<ParamField header="Content-Type" type="string" required>
  `application/json`
</ParamField>

## Request Body

<ParamField body="agentId" type="string" required>
  ID del agente que ejecutará la tarea
</ParamField>

<ParamField body="type" type="string" required>
  Tipo de trigger. Valores: `schedule`, `integration_event`, `webhook`, `conversation_start`, `conversation_resolved`, `lead_captured`, `form_submitted`
</ParamField>

<ParamField body="name" type="string" required>
  Nombre de la tarea (máx 100 caracteres)
</ParamField>

<ParamField body="description" type="string">
  Descripción opcional (máx 500 caracteres)
</ParamField>

<ParamField body="prompt" type="string" required>
  Instrucciones que el agente ejecutará cuando se active el trigger
</ParamField>

<ParamField body="config" type="object">
  Configuración específica del tipo de trigger

  <Expandable title="Opciones de config">
    <ParamField body="config.cronExpression" type="string">
      Expresión cron para triggers tipo `schedule` (ej: `0 9 * * *`)
    </ParamField>

    <ParamField body="config.timezone" type="string">
      Zona horaria (ej: `America/Argentina/Buenos_Aires`)
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="isEnabled" type="boolean" default="true">
  Si la tarea debe estar activa al crearla
</ParamField>

<ParamField body="eventConfig" type="object">
  Configuración para triggers tipo `integration_event`

  <Expandable title="Opciones de eventConfig">
    <ParamField body="eventConfig.profileId" type="string" required>
      ID del perfil de Composio conectado
    </ParamField>

    <ParamField body="eventConfig.connectedAccountId" type="string" required>
      ID de la cuenta conectada
    </ParamField>

    <ParamField body="eventConfig.triggerSlug" type="string" required>
      Slug del trigger de Composio (ej: `gmail_new_email`)
    </ParamField>

    <ParamField body="eventConfig.triggerConfig" type="object">
      Configuración adicional del trigger
    </ParamField>
  </Expandable>
</ParamField>

<RequestExample>
  ```bash cURL - Tarea programada theme={null}
  curl -X POST https://app.horneross.com/api/tasks \
    -H "Authorization: Bearer sk_live_xxx" \
    -H "Content-Type: application/json" \
    -d '{
      "agentId": "agent_abc123",
      "type": "schedule",
      "name": "Resumen diario",
      "description": "Genera resumen de conversaciones cada mañana",
      "prompt": "Genera un resumen de las conversaciones de ayer y envialo por email",
      "config": {
        "cronExpression": "0 9 * * *",
        "timezone": "America/Argentina/Buenos_Aires"
      }
    }'
  ```

  ```javascript JavaScript - Tarea programada theme={null}
  const response = await fetch('https://app.horneross.com/api/tasks', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer sk_live_xxx',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      agentId: 'agent_abc123',
      type: 'schedule',
      name: 'Resumen diario',
      prompt: 'Genera un resumen de las conversaciones de ayer',
      config: {
        cronExpression: '0 9 * * *',
        timezone: 'America/Argentina/Buenos_Aires',
      },
    }),
  });

  const { trigger } = await response.json();
  console.log('Task creada:', trigger.id);
  ```

  ```python Python - Tarea programada theme={null}
  import requests

  response = requests.post(
      'https://app.horneross.com/api/tasks',
      headers={
          'Authorization': 'Bearer sk_live_xxx',
          'Content-Type': 'application/json',
      },
      json={
          'agentId': 'agent_abc123',
          'type': 'schedule',
          'name': 'Resumen diario',
          'prompt': 'Genera un resumen de las conversaciones de ayer',
          'config': {
              'cronExpression': '0 9 * * *',
              'timezone': 'America/Argentina/Buenos_Aires'
          }
      }
  )

  trigger = response.json()['trigger']
  print(f'Task creada: {trigger["id"]}')
  ```
</RequestExample>

## Response

<ResponseField name="trigger" type="object" required>
  La tarea creada

  <Expandable title="Propiedades">
    <ResponseField name="trigger.id" type="string" required>
      ID único de la tarea
    </ResponseField>

    <ResponseField name="trigger.agentId" type="string" required>
      ID del agente
    </ResponseField>

    <ResponseField name="trigger.type" type="string" required>
      Tipo de trigger
    </ResponseField>

    <ResponseField name="trigger.name" type="string" required>
      Nombre
    </ResponseField>

    <ResponseField name="trigger.config" type="object" required>
      Configuración completa
    </ResponseField>

    <ResponseField name="trigger.isEnabled" type="boolean" required>
      Estado de activación
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseExample>
  ```json 201 - Created theme={null}
  {
    "trigger": {
      "id": "trigger_new123",
      "agentId": "agent_abc123",
      "type": "schedule",
      "name": "Resumen diario",
      "description": "Genera resumen de conversaciones cada mañana",
      "config": {
        "prompt": "Genera un resumen de las conversaciones de ayer",
        "cronExpression": "0 9 * * *",
        "timezone": "America/Argentina/Buenos_Aires"
      },
      "isEnabled": true,
      "createdAt": "2024-01-21T16:00:00Z",
      "agent": {
        "id": "agent_abc123",
        "name": "Asistente de Ventas",
        "iconUrl": null
      }
    }
  }
  ```

  ```json 400 - Nombre duplicado theme={null}
  {
    "error": "A task with this name already exists for this agent. Please choose a different name."
  }
  ```

  ```json 404 - Agente no encontrado theme={null}
  {
    "error": "Agent not found"
  }
  ```
</ResponseExample>

## Expresiones Cron

Formato: `minuto hora día-del-mes mes día-de-semana`

| Expresión     | Descripción                      |
| ------------- | -------------------------------- |
| `0 9 * * *`   | Todos los días a las 9:00 AM     |
| `0 9 * * 1-5` | Lunes a Viernes a las 9:00 AM    |
| `0 */2 * * *` | Cada 2 horas                     |
| `0 9 1 * *`   | Primer día del mes a las 9:00 AM |
| `30 14 * * 0` | Domingos a las 2:30 PM           |