Criar Activity Generation Config

Cria uma activity generation config somente de ciclo de vida com os três pilares.

POST /api/activity-generation-configs

Cria uma activity generation config. A operação é transacional: a AGC e os três pilares de ciclo de vida (com seus filhos) são criados juntos, ou nada é criado.

A AGC é criada no projeto ativo, sempre com status: "draft" (veja Status). Para que ela rode, publique-a.

Auth: Obrigatório — permissão activity-generation-config:create

Invariante dos três pilares. activation, engagement e resurrection são todos obrigatórios. Omitir qualquer um retorna 400 Bad Request. Não há como criar uma AGC sem os três pilares.

Os corpos de requisição são snake_case. Na UI de administração, o wizard preenche cada pilar com valores padrão sensatos a partir de GET /api/lifecycle-defaults; o administrador então edita e envia os dados completos. Os valores de user_retention_status_config_id referenciam entradas no catálogo de status de retenção do tenant.

Corpo da Requisição

Campo	Tipo	Obrigatório	Descrição
`name`	string	Sim	Nome da config
`description`	string	Não	Descrição em texto livre
`audience_id`	UUID	Não	Audiência própria da AGC; deve ser uma audiência do projeto ativo. Sem ela, a AGC roda sobre a audiência raiz do projeto (veja Audiência efetiva)
`activation`	object	Sim	Pilar de ativação (ver abaixo)
`engagement`	object	Sim	Pilar de engajamento (ver abaixo)
`resurrection`	object	Sim	Pilar de ressurreição (ver abaixo)

source_config_id, usage_type e qualquer campo de template/clone não são aceitos. Uma AGC é criada apenas com dados completos de ciclo de vida.

Também não são aceitos status, projectId nem project_id: a AGC é sempre criada no projeto ativo e em draft. Enviar qualquer um deles responde 400.

Objeto `activation`

Campo	Tipo	Obrigatório	Descrição
`name`	string	Sim	Nome do pilar
`description`	string	Não	Descrição em texto livre
`source_table`	string	Sim	Tabela de origem dos dados de ativação
`source_columns`	string[]	Não	Colunas usadas para calcular a ativação
`date_column`	string	Sim	Coluna de data usada para o windowing
`aggregation_method`	enum	Sim	`nunique`, `count`, `sum` ou `active_weeks`
`moments`	object[]	Sim	Momentos de ativação (ver abaixo)

Cada item em moments:

Campo	Tipo	Obrigatório	Descrição
`status_code`	string	Sim	Código de status de retenção atribuído por este momento
`user_retention_status_config_id`	UUID	Não	Entrada do catálogo de status de retenção. Se omitido, a API o deriva de `status_code`; se enviado, deve ser a entrada desse `status_code`
`min_actions`	int ≥ 0	Não	Mínimo de ações para atingir este momento
`window_days`	int ≥ 0	Não	Janela de look-back em dias
`time_window`	int ≥ 0	Não	Janela de tempo do momento
`priority`	int ≥ 0	Sim	Prioridade de resolução (o menor vence)

Objeto `engagement`

Campo	Tipo	Obrigatório	Descrição
`name`	string	Sim	Nome do pilar
`description`	string	Não	Descrição em texto livre
`source_table`	string	Sim	Tabela de origem dos dados de engajamento
`source_columns`	string[]	Não	Colunas usadas para calcular o engajamento
`date_column`	string	Sim	Coluna de data usada para o windowing
`engagement_window_days`	int ≥ 1	Sim	Janela móvel para a contagem de engajamento
`min_lifetime_actions_for_engaged`	int ≥ 1	Sim	Mínimo de ações vitalícias para ser considerado engaged (padrão da plataforma `1`)
`counting_method`	enum	Sim	`event_ids`, `active_days` ou `active_weeks`
`levels`	object[]	Sim	Níveis de engajamento (ver abaixo)

Cada item em levels:

Campo	Tipo	Obrigatório	Descrição
`status_code`	string	Sim	Código de status de retenção para este nível
`user_retention_status_config_id`	UUID	Não	Entrada do catálogo de status de retenção. Se omitido, a API o deriva de `status_code`; se enviado, deve ser a entrada desse `status_code`
`label`	string	Sim	Rótulo de exibição
`min_threshold`	int ≥ 0	Sim	Limite inferior (inclusivo) do nível
`max_threshold`	int ≥ 0	Não	Limite superior; omitir para o nível mais alto
`order`	int ≥ 0	Sim	Ordem de classificação do nível

Objeto `resurrection`

Campo	Tipo	Obrigatório	Descrição
`name`	string	Sim	Nome do pilar
`description`	string	Não	Descrição em texto livre
`source_table`	string	Sim	Tabela de origem dos dados de ressurreição
`source_columns`	string[]	Não	Colunas usadas para calcular a ressurreição
`date_column`	string	Sim	Coluna de data usada para o windowing
`thresholds`	object[]	Sim	Limites de ressurreição (ver abaixo)

Cada item em thresholds:

Campo	Tipo	Obrigatório	Descrição
`status_code`	string	Sim	Código de status de retenção para este limite
`user_retention_status_config_id`	UUID	Não	Entrada do catálogo de status de retenção. Se omitido, a API o deriva de `status_code`; se enviado, deve ser a entrada desse `status_code`
`label`	string	Sim	Rótulo de exibição
`threshold_days`	int ≥ 1	Sim	Dias de inatividade que disparam este status
`order`	int ≥ 0	Sim	Ordem de classificação do limite

Exemplo

curl -X POST https://api.reten.ai/api/activity-generation-configs \
  -H "Authorization: Bearer <token>" \
  -H "x-tenant-id: <tenant-id>" \
  -H "x-project-id: <project-id>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Default lifecycle",
    "description": "Activation, engagement and resurrection for the main funnel",
    "audience_id": "1f0d2c3b-4a59-4687-9c12-abcdef012345",
    "activation": {
      "name": "Activation",
      "source_table": "events",
      "source_columns": ["user_id", "event_id"],
      "date_column": "occurred_at",
      "aggregation_method": "nunique",
      "moments": [
        {
          "status_code": "aha",
          "user_retention_status_config_id": "aa11bb22-cc33-4d44-9e55-ff66aa77bb88",
          "min_actions": 3,
          "window_days": 7,
          "time_window": 30,
          "priority": 1
        },
        {
          "status_code": "setup",
          "user_retention_status_config_id": "bb22cc33-dd44-4e55-9f66-aa88bb99ccaa",
          "min_actions": 1,
          "priority": 2
        }
      ]
    },
    "engagement": {
      "name": "Engagement",
      "source_table": "events",
      "source_columns": ["user_id", "event_id"],
      "date_column": "occurred_at",
      "engagement_window_days": 28,
      "min_lifetime_actions_for_engaged": 1,
      "counting_method": "active_days",
      "levels": [
        {
          "status_code": "casual",
          "user_retention_status_config_id": "cc33dd44-ee55-4f66-a077-bb99ccaaddbb",
          "label": "Casual",
          "min_threshold": 1,
          "max_threshold": 7,
          "order": 1
        },
        {
          "status_code": "core",
          "user_retention_status_config_id": "dd44ee55-ff66-4077-b188-ccaaddbbeecc",
          "label": "Core",
          "min_threshold": 8,
          "order": 2
        }
      ]
    },
    "resurrection": {
      "name": "Resurrection",
      "source_table": "events",
      "source_columns": ["user_id"],
      "date_column": "occurred_at",
      "thresholds": [
        {
          "status_code": "dormant",
          "user_retention_status_config_id": "ee55ff66-aa77-4188-c299-ddbbeeccffdd",
          "label": "Dormant",
          "threshold_days": 30,
          "order": 1
        },
        {
          "status_code": "churned",
          "user_retention_status_config_id": "ff66aa77-bb88-4299-d3aa-eeccffdd00ee",
          "label": "Churned",
          "threshold_days": 90,
          "order": 2
        }
      ]
    }
  }'

import axios from 'axios';

const body = {
  name: 'Default lifecycle',
  description: 'Activation, engagement and resurrection for the main funnel',
  audience_id: '1f0d2c3b-4a59-4687-9c12-abcdef012345',
  activation: {
    name: 'Activation',
    source_table: 'events',
    source_columns: ['user_id', 'event_id'],
    date_column: 'occurred_at',
    aggregation_method: 'nunique',
    moments: [
      {
        status_code: 'aha',
        user_retention_status_config_id: 'aa11bb22-cc33-4d44-9e55-ff66aa77bb88',
        min_actions: 3,
        window_days: 7,
        time_window: 30,
        priority: 1,
      },
      {
        status_code: 'setup',
        user_retention_status_config_id: 'bb22cc33-dd44-4e55-9f66-aa88bb99ccaa',
        min_actions: 1,
        priority: 2,
      },
    ],
  },
  engagement: {
    name: 'Engagement',
    source_table: 'events',
    source_columns: ['user_id', 'event_id'],
    date_column: 'occurred_at',
    engagement_window_days: 28,
    min_lifetime_actions_for_engaged: 1,
    counting_method: 'active_days',
    levels: [
      {
        status_code: 'casual',
        user_retention_status_config_id: 'cc33dd44-ee55-4f66-a077-bb99ccaaddbb',
        label: 'Casual',
        min_threshold: 1,
        max_threshold: 7,
        order: 1,
      },
      {
        status_code: 'core',
        user_retention_status_config_id: 'dd44ee55-ff66-4077-b188-ccaaddbbeecc',
        label: 'Core',
        min_threshold: 8,
        order: 2,
      },
    ],
  },
  resurrection: {
    name: 'Resurrection',
    source_table: 'events',
    source_columns: ['user_id'],
    date_column: 'occurred_at',
    thresholds: [
      {
        status_code: 'dormant',
        user_retention_status_config_id: 'ee55ff66-aa77-4188-c299-ddbbeeccffdd',
        label: 'Dormant',
        threshold_days: 30,
        order: 1,
      },
      {
        status_code: 'churned',
        user_retention_status_config_id: 'ff66aa77-bb88-4299-d3aa-eeccffdd00ee',
        label: 'Churned',
        threshold_days: 90,
        order: 2,
      },
    ],
  },
};

const response = await axios.post(
  'https://api.reten.ai/api/activity-generation-configs',
  body,
  { headers: { Authorization: 'Bearer <token>', 'x-tenant-id': '<tenant-id>', 'x-project-id': '<project-id>' } },
);
const created = response.data;

Resposta `201 Created`

Retorna a AGC criada com sua configuração aninhada completa — incluindo projectId e status: "draft" — no mesmo formato camelCase que GET /:id, mas sem effectiveAudienceId nem configHashes: leia a AGC com GET /:id para obtê-los.

Respostas de Erro

Status	Descrição
`400`	Validação falhou, ou falta um pilar obrigatório (`activation` / `engagement` / `resurrection`)
`400`	`status`, `projectId` ou `project_id` no corpo
`400`	Um `status_code` não é um código ativo do catálogo de status de retenção do tenant — `status_code "<code>" no es un user retention status válido y activo para este tenant`
`400`	Um `user_retention_status_config_id` não é a entrada do catálogo do seu `status_code` — `user_retention_status_config_id no corresponde al status_code "<code>"`
`400`	`audience_id` não é uma audiência do projeto ativo — `La audiencia no existe en este proyecto.`
`409`	Outra AGC do projeto ativo já tem esse nome — `An activity generation config with name "<name>" already exists`