Declare a trigger payload contract

Declares the stored payload contract for the trigger, changes how it is enforced, or both, in one call. fields and enforcement are both optional, so arming enforcement is { "enforcement": "strict" }. While a PUBLISHED automation consumes the trigger the change must stay backward compatible (the ratchet below); loosening is always allowed.

Use when you want generated types, a dry-run validator (validateTriggerPayload) and drift detection for the JSON your service fires, or when you flip enforcement. Draft the tree from a real payload with inferPayloadContract. Trigger contracts MUST keep a top-level { key: "email", type: "string", required: true } field so automations can resolve a recipient.

Input fields is a tree: scalars (string, int, float, boolean, date, enum), object nodes with children, array nodes with children (object elements), itemType (scalar elements) or neither. The tree is validated BEFORE any write: unknown-typed nodes are refused, keys are unique per level, an object declares at least one child. enforcement: off (advisory, the default for a new contract), prune (drop undeclared keys before the run), strict (reject a payload carrying them). A fallbackValue satisfies required in EVERY mode: a producer that omits the key never fails a fire, every recipient gets the fallback. The version bumps only when the behavioral surface changes (keys, types, required, fallbacks; not descriptions or examples). Declaring a contract never changes fire behavior by itself. Loosening is the escape hatch when strict rejects a drifted producer in production.

Returns 200 with the same body a follow-up getTriggerContract returns plus warnings[] (always present, often empty): ENFORCEMENT_LOOSENED_WHILE_PUBLISHED when enforcement went down while published automations consume the trigger (tightening back is refused until they are unpublished or detached), and one REQUIRED_FIELD_SATISFIED_BY_FALLBACK per required field that declares a fallback (field is its dotted path). Ratchet while a published automation consumes the trigger: tighten off→prune, off→strict, prune→strict = 409; loosen = 200 + warning; remove, retype or enum-narrow a field, or add a required field WITHOUT a fallback = 409; add an optional field, widen a type, add an enum value, or add a required field WITH a fallback = 200 (+ warning per fallback). With no published consumer every change is 200.

Errors 409 CONTRACT_LOCKED_BY_PUBLISHED_AUTOMATIONS for a change the ratchet refuses (message names the incompatibility; unpublish or detach the consumers, or make a compatible change); 404 TRIGGER_EVENT_NOT_FOUND; 400 INVALID_REQUEST (param: "fields") when the tree fails structural validation, or when a body with no fields targets a trigger that has no stored contract yet.

See also getTriggerContract, validateTriggerPayload, inferPayloadContract, updateAutomation (publishing a consumer starts the ratchet).

PUT /v1/automations/triggers/{triggerEventId}/contract

Declare a trigger payload contract

cURL

curl --request PUT \
  --url https://brew.new/api/v1/automations/triggers/{triggerEventId}/contract \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "fields": [
    {
      "key": "email",
      "type": "string",
      "required": true
    },
    {
      "key": "plan",
      "type": "enum",
      "required": false,
      "enumValues": [
        "free",
        "pro"
      ],
      "fallbackValue": "free",
      "description": "Billing plan at signup time."
    },
    {
      "key": "order",
      "type": "object",
      "required": false,
      "children": [
        {
          "key": "total",
          "type": "float",
          "required": true
        }
      ]
    }
  ]
}
'

200

Example

{
  "subjectKind": "trigger",
  "subjectId": "user_signed_up",
  "source": "stored",
  "format": "json",
  "typeName": "UserSignedUpPayload",
  "contractHash": "22545d11e1d174ba0717ed37c9c4b460c96bed51ae31ea0af18266ebba30f76a",
  "version": 3,
  "enforcement": "prune",
  "fields": [
    {
      "key": "email",
      "type": "string",
      "required": true
    },
    {
      "key": "plan",
      "type": "enum",
      "required": false,
      "enumValues": [
        "free",
        "pro"
      ],
      "fallbackValue": "free"
    },
    {
      "key": "order",
      "type": "object",
      "required": false,
      "children": [
        {
          "key": "total",
          "type": "float",
          "required": true
        }
      ]
    }
  ],
  "warnings": [
    {
      "code": "ENFORCEMENT_LOOSENED_WHILE_PUBLISHED",
      "message": "Enforcement loosened from strict to prune while 1 published automation(s) consume this trigger. Loosening is allowed as the operator escape hatch, but tightening back to strict will be refused with 409 CONTRACT_LOCKED_BY_PUBLISHED_AUTOMATIONS until they are unpublished or detached."
    }
  ]
}

Authorizations

bearerAuthapiKeyAuth

Authorization · string · header · default: Bearer brew_your_api_key · required

Send your Brew API key as Authorization: Bearer brew_xxx.

Headers

X-Brand-Id · string

The brand this request acts on. REQUIRED for organization-scoped credentials (otherwise 400 BRAND_ID_REQUIRED — there is no default brand); list ids with GET /v1/brands. Brand-scoped credentials may omit it, and sending a different brand returns 403 BRAND_SCOPE_MISMATCH. A brand outside your organization returns 404 BRAND_NOT_FOUND.

Required string length: 1 - 64

Path Parameters

triggerEventId · string · required

Trigger id returned by POST /v1/automations/triggers (integration triggers use composite ids — URL-encode the colons).

Required string length: 1 - 256

Example:

"user_signed_up"

Body

application/json

fields · object[]

Required array length: 1 - 100 elements

Show child attributes

name · string

Required string length: 1 - 160

enforcement · enum<string>

Available options: off, prune, strict

Response

200

application/json

Stored. The contract as a follow-up GET would return it, plus warnings[] about the write.

subjectKind · enum<string> · required

Available options: trigger

subjectId · string · required

Minimum string length: 1

source · enum<string> · required

Available options: stored, derived_from_schema, derived_from_template

typeName · string · required

Minimum string length: 1

format · enum<string> · required

Available options: json, ts, zod, jsonschema, skill

warnings · object[] · required

Show child attributes

contractHash · string

Required string length: 64

version · integer

Required range: x >= 1

enforcement · enum<string>

Available options: off, prune, strict

driftStatus · enum<string>

Available options: fresh, stale

fields · object[]

Show child attributes

content · string