Create an automation

Módulo Platform

POST/automationsautomations.create

An automation (Section 7.3, ADR 0047): when a domain event of the trigger type happens in the org and the conditions hold, the actions run in order as the owner through public API operations, so row level security and capabilities decide every write. The owner is whoever last changed what it does or turned it on. Needs the automations plan feature (Pro and above) to create, change or turn on (plan_feature_required: 422); without it an automation can still be turned off and deleted. Saving validates the documents as automation.schema.json does (automation_conditions_invalid, automation_actions_invalid: 422) and checks the actions fit the trigger (automation_action_needs_record, automation_action_needs_commentable_subject, automation_person_not_member, automation_webhook_unknown: 422). Creates an automation. Requires `Idempotency-Key`; a replay returns the original response. The organization is derived from the credential or the parent row, never from the body.

Requiere la capacidad org.automations.write.
Alcances de OAuth: org.
Envía el encabezado Idempotency-Key. Una repetición con la misma clave devuelve la respuesta original.
Estados de error: 400, 401, 409, 422, 429. Los errores son detalles de problema RFC 9457.

Cuerpo de la solicitud: AutomationCreate

automations.create: AutomationCreate
Campo	Tipo	Obligatorio	Descripción
name	string	Sí	Name shown in Settings, Automations.Restricciones: length 1 to 120
description	string \| null	No	What the automation is for.Restricciones: length 1 to 500
trigger_event_type	string	Sí	Domain event type that starts a run, from the catalog webhooks use (webhookEventTypes.list).Restricciones: pattern ^[a-z][a-z_]\.[a-z][a-z_]$
enabled	boolean	No	True while new events start runs.
conditions	AutomationConditions	Sí	An automation's conditions: {"all": [...]} or {"any": [...]} of conditions and one-level groups, at most 20 in all. An empty list always holds.
actions	AutomationActions	Sí	An automation's 1 to 10 actions, in the order they run.

{
  "name": "Pick up new tasks",
  "description": "Comments on every new task.",
  "trigger_event_type": "record.created",
  "enabled": true,
  "conditions": {
    "all": [
      {
        "field": "data.record_kind",
        "operator": "eq",
        "value": "Task"
      }
    ]
  },
  "actions": [
    {
      "type": "add_comment",
      "body": "Picked up {{data.title}}."
    }
  ]
}

Respuesta 201: Automation

automations.create: Automation
Campo	Tipo	Obligatorio	Descripción
id	string (uuid)	Sí	Identifier of the automation.
org_id	string (uuid)	Sí	Identifier of the owning organization, derived from the parent row and never accepted from the caller.
created_at	string (date-time)	Sí	When the row was created.
created_by	string (uuid) \| null	Sí	Identifier of the person who created the row.
updated_at	string (date-time)	Sí	When the row was last updated.
updated_by	string (uuid) \| null	Sí	Identifier of the person who last updated the row.
name	string	Sí	Name shown in Settings, Automations.Restricciones: length 1 to 120
description	string \| null	Sí	What the automation is for.Restricciones: length 1 to 500
trigger_event_type	string	Sí	Domain event type that starts a run, from the catalog webhooks use (webhookEventTypes.list).Restricciones: pattern ^[a-z][a-z_]\.[a-z][a-z_]$
condition_match	"all" \| "any"	Sí	How the top-level conditions combine; set from the conditions document.
owner_person_id	string (uuid)	Sí	Identifier of the person the actions run as.
enabled	boolean	Sí	True while new events start runs.
paused_at	string (date-time) \| null	Sí	When the engine turned the automation off because a run could not act as the owner; null otherwise. Turning it on again clears it.
pause_reason	string \| null	Sí	Why the engine paused it: owner_left_org, owner_lost_capability, owner_cannot_sign_in or owner_access_refused.Restricciones: pattern ^[a-z][a-z0-9_]*$
conditions	AutomationConditions	Sí	An automation's conditions: {"all": [...]} or {"any": [...]} of conditions and one-level groups, at most 20 in all. An empty list always holds.
actions	AutomationActions	Sí	An automation's 1 to 10 actions, in the order they run.

{
  "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f",
  "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f",
  "created_at": "2026-10-08T14:30:00Z",
  "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f",
  "updated_at": "2026-10-08T14:30:00Z",
  "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f",
  "name": "Pick up new tasks",
  "description": "Comments on every new task.",
  "trigger_event_type": "record.created",
  "condition_match": "all",
  "owner_person_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f",
  "enabled": true,
  "paused_at": "2026-10-08T14:30:00Z",
  "pause_reason": "owner_left_org",
  "conditions": {
    "all": [
      {
        "field": "data.record_kind",
        "operator": "eq",
        "value": "Task"
      }
    ]
  },
  "actions": [
    {
      "type": "add_comment",
      "body": "Picked up {{data.title}}."
    }
  ]
}

Ejemplos de código

curl -X POST "$XOS_BASE_URL/automations" \
  -H "Authorization: Bearer $XOS_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"name":"Pick up new tasks","description":"Comments on every new task.","trigger_event_type":"record.created","enabled":true,"conditions":{"all":[{"field":"data.record_kind","operator":"eq","value":"Task"}]},"actions":[{"type":"add_comment","body":"Picked up {{data.title}}."}]}'

const { data } = await xos.automations.create({
    "name": "Pick up new tasks",
    "description": "Comments on every new task.",
    "trigger_event_type": "record.created",
    "enabled": true,
    "conditions": {
      "all": [
        {
          "field": "data.record_kind",
          "operator": "eq",
          "value": "Task"
        }
      ]
    },
    "actions": [
      {
        "type": "add_comment",
        "body": "Picked up {{data.title}}."
      }
    ]
  });

response = xos.automations.create({"name": "Pick up new tasks", "description": "Comments on every new task.", "trigger_event_type": "record.created", "enabled": True, "conditions": {"all": [{"field": "data.record_kind", "operator": "eq", "value": "Task"}]}, "actions": [{"type": "add_comment", "body": "Picked up {{data.title}}."}]})

xos automations create --data '{"name":"Pick up new tasks","description":"Comments on every new task.","trigger_event_type":"record.created","enabled":true,"conditions":{"all":[{"field":"data.record_kind","operator":"eq","value":"Task"}]},"actions":[{"type":"add_comment","body":"Picked up {{data.title}}."}]}'