Create an Automation

Create a named, durable recurring cause of work: an agent_definition target launches a fresh Session and initial Run per firing, while a schedule-only dream target curates a MemoryStore and creates no Session at all. The evaluator setup is symmetric with Agent DeliveryScreen configuration: a webhook AdmissionFilter Check names a model routing profile, optional tier (default default), instructions, and a required failure disposition because relevance has no universally safe default; optional input.outcome supplies the definition-of-done rubric for another agent to evaluate at the fixed planning tier under the admitted agent release. The AdmissionFilter is a single-shot counter-metered gate before the agent; Outcome remains an iterative, usage-ledgered grader over completed work. Trigger kind and target kind are immutable after creation; schedule agent inputs are prompt snapshots, webhook and subscription inputs are prompt templates, and optional input.mounts freeze File, Project, and MemoryStore declarations into each fresh managed Session. Mounted agent inputs cannot target a ConnectedRuntime because that lane has no Checkfu-owned resource materialization plane. A webhook trigger must supply its own whsec_ ingest secret, which is encrypted at rest and never returned afterward. An optional external_id claims a workspace-unique, caller-chosen reconcile key: a second create naming a key already held conflicts, and the key is immutable afterward, so a caller that reconciles from its own system looks the Automation up by that key rather than keeping the platform id in a row it can lose. Optional metadata is a organization-owned correlation bag of at most 16 pairs, keys up to 64 characters and values up to 512, stored and returned verbatim and never read by the platform. Accepts an optional Idempotency-Key.

Checkfu support posture: alpha; hosted. Required evidence journey: automation-firing. Deployment-specific readiness and the latest proven release are available from GET /v1/support/capabilities.

POST /v1/automations

Create an Automation

cURL

curl --request POST \
  --url https://api.checkfu.com/v1/automations \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'checkfu-version: <checkfu-version>' \
  --data '
{
  "name": "<string>",
  "created_by": "<string>",
  "identity": {
    "acted_as": "<string>"
  },
  "target": {
    "kind": "agent_definition",
    "agent_deployment_id": "<string>",
    "agent_deployment_revision_selection": {
      "type": "current"
    }
  },
  "trigger": {
    "kind": "schedule",
    "cron": "<string>",
    "timezone": "<string>",
    "dedupe_key": "<unknown>",
    "source": "<unknown>",
    "filter": "<unknown>"
  },
  "input": {
    "kind": "snapshot",
    "prompt": "<string>",
    "mounts": [
      {
        "kind": "project",
        "project_id": "<string>",
        "mount_path": "<string>",
        "revision_policy": {
          "kind": "latest"
        },
        "writeback": null
      }
    ],
    "prompt_template": "<unknown>"
  },
  "description": "<string>",
  "external_id": "<string>",
  "environment_id": "<string>",
  "connected_runtime": "<string>",
  "metadata": {},
  "surface_scope_id": "<string>",
  "ingest_secret": "<unknown>"
}
'

201

{
  "id": "<string>",
  "workspace_id": "<string>",
  "version": 1,
  "name": "<string>",
  "description": "<string>",
  "external_id": "<string>",
  "created_by": "<string>",
  "identity": {
    "acted_as": "<string>"
  },
  "connected_runtime": "<string>",
  "status": "active",
  "paused_reason": {
    "kind": "manual",
    "error_type": "<unknown>"
  },
  "last_run_at": "<string>",
  "last_session_id": "<string>",
  "last_run_id": "<string>",
  "next_run_at": "<string>",
  "created_at": "<string>",
  "updated_at": "<string>",
  "target": {
    "kind": "agent_definition",
    "agent_deployment_id": "<string>",
    "agent_deployment_revision_selection": {
      "type": "current"
    },
    "budget": {
      "limit": 1,
      "metric": "model_tokens"
    }
  },
  "surface_scope_id": "<string>",
  "trigger": {
    "kind": "schedule",
    "cron": "<string>",
    "timezone": "<string>",
    "dedupe_key": "<unknown>",
    "source": "<unknown>",
    "filter": "<unknown>"
  },
  "input": {
    "kind": "snapshot",
    "prompt": "<string>",
    "outcome": {
      "rubric": "<string>",
      "max_iterations": 10,
      "deliverables": [
        "<string>"
      ],
      "report": {
        "extraction": "json",
        "outputs": [
          {
            "key": "<string>",
            "title": "<string>",
            "type": "string",
            "description": "<string>",
            "acceptance": {
              "kind": "one_of",
              "values": [
                "<string>"
              ]
            }
          }
        ]
      }
    },
    "flow_review": {
      "model_routing_profile_key": "<string>",
      "criteria": [
        {
          "key": "<string>",
          "description": "<string>",
          "severity": "low"
        }
      ],
      "tier": "default"
    },
    "mounts": [
      {
        "kind": "project",
        "project_id": "<string>",
        "mount_path": "<string>",
        "revision_policy": {
          "kind": "latest"
        },
        "access": "read_only",
        "writeback": null
      }
    ],
    "prompt_template": "<unknown>"
  },
  "environment_id": "<string>",
  "metadata": {}
}

Authorizations

Authorization · string · header · required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Headers

checkfu-version · enum<string> · required

Available options: 2026-08-27

idempotency-key · string

Maximum string length: 255

Body

application/json

Option 1

Option 2

Option 3

Option 4

Option 5

Option 6

name · string · required

Required string length: 1 - 255

created_by · string · required

Pattern: ^prin_[0-9a-f]{32}$

identity · object · required

Show child attributes

target · object · required

Show child attributes

trigger · object · required

Show child attributes

input · object · required

Show child attributes

description · string | null

Required string length: 1 - 4096

external_id · string

Pattern: ^[a-z0-9](?:[a-z0-9._-]{0,93})$

environment_id · string

Pattern: ^env_[0-9a-f]{32}$

connected_runtime · string | null

Pattern: ^crt_[0-9a-f]{32}$

metadata · object

at most 16 correlation pairs with keys of 1 to 64 characters

Show child attributes

surface_scope_id · string | null

Pattern: ^surf_[0-9a-f]{32}$

ingest_secret · any

Response

201

application/json

Automation

Option 1

Option 2

Option 3

Option 4

Option 5

Option 6

id · string · required

Pattern: ^auto_[0-9a-f]{32}$

workspace_id · string · required

Pattern: ^wrkspc_[0-9a-f]{32}$

version · integer · required

Required range: x > 0

name · string · required

Required string length: 1 - 255

description · string | null · required

Required string length: 1 - 4096

external_id · string | null · required

Pattern: ^[a-z0-9](?:[a-z0-9._-]{0,93})$

created_by · string · required

Pattern: ^prin_[0-9a-f]{32}$

identity · object · required

Show child attributes

connected_runtime · string | null · required

Pattern: ^crt_[0-9a-f]{32}$

status · enum<string> · required

Available options: active, paused

paused_reason · object · required

Option 1

Option 2

Show child attributes

last_run_at · string | null · required

last_session_id · string | null · required

Pattern: ^sess_[0-9a-f]{32}$

last_run_id · string | null · required

Pattern: ^run_[0-9a-f]{32}$

next_run_at · string | null · required

created_at · string · required

updated_at · string · required

target · object · required

Show child attributes

surface_scope_id · string | null · required

Pattern: ^surf_[0-9a-f]{32}$

trigger · object · required

Show child attributes

input · object · required

Show child attributes

environment_id · string

Pattern: ^env_[0-9a-f]{32}$

metadata · object

at most 16 correlation pairs with keys of 1 to 64 characters

Show child attributes