Automation

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/sendraven-ai/json-schema/sendraven-ai-automation-schema.json",
  "title": "Automation",
  "x-generated": "2026-10-31",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/sendraven-ai-api-openapi.json#/components/schemas/Automation",
  "type": "object",
  "required": [
    "id",
    "name",
    "slug",
    "status",
    "trigger",
    "identity_id",
    "from",
    "reply_to",
    "steps",
    "exit_on_reply",
    "topic_key",
    "exit_tags",
    "required_tags",
    "reenrollment",
    "default_variables",
    "enrollments",
    "created_at",
    "updated_at"
  ],
  "properties": {
    "id": {
      "type": "string",
      "format": "uuid",
      "description": "Every path takes this, not the name or slug."
    },
    "name": {
      "type": "string"
    },
    "slug": {
      "type": "string"
    },
    "status": {
      "type": "string",
      "enum": [
        "draft",
        "active",
        "paused"
      ],
      "description": "Only active automations enrol anyone or send steps."
    },
    "trigger": {
      "type": "object",
      "required": [
        "kind",
        "audience_id",
        "event_name",
        "tag",
        "date_attribute",
        "offset_days",
        "recurring_yearly"
      ],
      "properties": {
        "kind": {
          "type": "string",
          "enum": [
            "api",
            "contact_added",
            "event",
            "tag_added",
            "date"
          ]
        },
        "audience_id": {
          "type": [
            "string",
            "null"
          ],
          "description": "Set for contact_added and date, null otherwise."
        },
        "event_name": {
          "type": [
            "string",
            "null"
          ],
          "description": "Set for event, null otherwise."
        },
        "tag": {
          "type": [
            "string",
            "null"
          ],
          "description": "Set for tag_added (normalised), null otherwise."
        },
        "date_attribute": {
          "type": [
            "string",
            "null"
          ],
          "description": "Set for date, null otherwise."
        },
        "offset_days": {
          "type": [
            "integer",
            "null"
          ],
          "description": "Set for date (0 when not given), null otherwise."
        },
        "recurring_yearly": {
          "type": [
            "boolean",
            "null"
          ],
          "description": "Set for date, null otherwise."
        }
      }
    },
    "identity_id": {
      "type": "string"
    },
    "from": {
      "type": "string"
    },
    "reply_to": {
      "type": [
        "string",
        "null"
      ],
      "description": "Where replies go when not from. When it is an address SendRaven does not receive for, exit_on_reply cannot fire."
    },
    "steps": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/AutomationStep"
      }
    },
    "exit_on_reply": {
      "type": "boolean"
    },
    "topic_key": {
      "type": [
        "string",
        "null"
      ]
    },
    "exit_tags": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Empty when none."
    },
    "required_tags": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Empty when none."
    },
    "reenrollment": {
      "type": "string",
      "enum": [
        "after_completion",
        "never"
      ],
      "description": "Who can come back in. after_completion: someone whose enrolment completed or was cancelled can be enrolled again and starts from the first step; only an active enrolment blocks a new one. never: each address goes through the sequence once, and enrolling someone who has already had it answers enrolled false with reason previously_enrolled. Applies to the enrol endpoint, POST /v1/events, contact_added, tag_added and date alike. An automation created before the field existed reads as after_completion."
    },
    "default_variables": {
      "type": "object",
      "additionalProperties": {
        "type": "string",
        "maxLength": 10000
      },
      "maxProperties": 100,
      "description": "Template values every enrolment gets, under whatever an enrolment passes in variables (which wins for the same name). Read when each step is sent, so a change reaches people already enrolled from their next step. Names are letters, digits, _ and . as in a template placeholder; keys are returned as written. contact_added, tag_added and date enrol with no variables of their own, so for those every placeholder the steps use (their subjects, html and templates) must have a value here, or the call answers 422 missing_variables naming the missing ones. {} when none."
    },
    "enrollments": {
      "type": "object",
      "required": [
        "active",
        "completed",
        "canceled",
        "failed"
      ],
      "properties": {
        "active": {
          "type": "integer",
          "minimum": 0
        },
        "completed": {
          "type": "integer",
          "minimum": 0
        },
        "canceled": {
          "type": "integer",
          "minimum": 0
        },
        "failed": {
          "type": "integer",
          "minimum": 0
        }
      },
      "description": "Enrolment counts by status, on every automation response (list, create, retrieve and update). Every status is present, 0 when it has none, so a new automation has all four at 0."
    },
    "created_at": {
      "type": "string",
      "format": "date-time"
    },
    "updated_at": {
      "type": [
        "string",
        "null"
      ],
      "format": "date-time",
      "description": "Last change, including a status change or any PATCH. Null until the first change."
    }
  },
  "$defs": {
    "AutomationStep": {
      "type": "object",
      "required": [
        "id",
        "delay_minutes",
        "subject",
        "html",
        "template_slug",
        "condition"
      ],
      "description": "A step as stored and returned. Steps are read each time one comes due, so a template edit reaches people partway through.",
      "properties": {
        "id": {
          "type": "string",
          "description": "The step's stable id. People mid-sequence are kept on a step by its id, so an edit that passes it back keeps them on that step wherever it moves, and a step without one is new. 1 to 40 letters, digits, _ and -. A step created before step ids existed reads as step-1, step-2 and so on by its position, and keeps that id once passed back. Messages a step sends carry it as the step_id tag."
        },
        "condition": {
          "description": "The one yes/no question this step asks when it comes due. True sends it; false skips it (nothing is sent) and the person moves on to the next step, which waits its own delay from then. Exits are checked first, so a condition never sends to someone an exit removes. has_tag / lacks_tag: the contact carries tag (normalised as contact tags are); someone with no contact record has no tags. engaged / not_engaged: the person opened or clicked any message this enrolment has been sent so far, counting only opens and clicks the scanner check counted, so a security gateway fetching every link is not engagement; not allowed on the first step, which has no earlier message. attribute_equals: the contact attribute key equals value, compared as text (3 equals \"3\"); a missing attribute never matches. null when the step has none.",
          "anyOf": [
            {
              "allOf": [
                {
                  "$ref": "#/$defs/AutomationStepCondition"
                }
              ]
            },
            {
              "type": "null"
            }
          ]
        },
        "delay_minutes": {
          "type": "integer",
          "minimum": 0,
          "maximum": 525600,
          "description": "From enrolment for the first step, from the previous step being sent for the rest."
        },
        "subject": {
          "type": "string"
        },
        "html": {
          "type": [
            "string",
            "null"
          ]
        },
        "template_slug": {
          "type": [
            "string",
            "null"
          ]
        }
      }
    },
    "AutomationStepCondition": {
      "type": "object",
      "required": [
        "type",
        "tag",
        "key",
        "value"
      ],
      "description": "A step's condition as stored. Every field is present; the ones its type does not use are null.",
      "properties": {
        "type": {
          "type": "string",
          "enum": [
            "has_tag",
            "lacks_tag",
            "engaged",
            "not_engaged",
            "attribute_equals"
          ]
        },
        "tag": {
          "type": [
            "string",
            "null"
          ],
          "description": "Set for has_tag and lacks_tag (normalised), null otherwise."
        },
        "key": {
          "type": [
            "string",
            "null"
          ],
          "description": "Set for attribute_equals, null otherwise."
        },
        "value": {
          "description": "Set for attribute_equals, null otherwise.",
          "anyOf": [
            {
              "oneOf": [
                {
                  "type": "string"
                },
                {
                  "type": "number"
                },
                {
                  "type": "boolean"
                }
              ]
            },
            {
              "type": "null"
            }
          ]
        }
      }
    }
  }
}