Edit an activity-property definition

Search Documentation

Search across all developer documentation
activity-properties

Edit an activity-property definition

PUT /v1/activity-properties/{id}
Auth required api.activities.manage

Edits a promoted property's type, enum values, and description. The identity key (activity_name, property_name) is not editable. The registry is authoritative: the edit always applies — it is never blocked. Each edit is classified by its impact on dependent Segments and the class is returned as mutation_class:

  • free — no effect on any predicate (description change, enum widen, or moving between string and enum, which compile to the same cast).
  • safe_but_stale — an enum value was removed; predicates stay valid but may compare against a value that can no longer be written.
  • disruptive — a cast-class change (e.g. string→number). Segments that reference the property keep evaluating best-effort but carry a standing eval_warning until their predicate is re-saved. For a disruptive edit the response includes an impact block (affected segments). Preview the impact first via /v1/activity-properties/{id}/preview.

Path parameters

id string required

The property's UUID or the dotted activity.property form (for example order.total) — the same spelling a SendQL predicate uses, minus its leading activity. prefix. Split on the LAST dot, since an activity name may contain one and a property name may not. Unknown handles read as 404 not_found.

Request body

Content type: application/json

type string enum required

One of: string, number, bool, datetime, enum

enum_values array<string> optional

Required when type is enum; must be empty/omitted otherwise.

description string optional

Responses

Errors follow the RFC 7807 problem format — see the error reference.

200 The updated definition with the mutation class and (for a disruptive edit) the impact application/json
property object required

A promoted activity-property definition — the typed schema a Segment's SendQL predicate references as activity.<activity_name>.<property_name>.

Fields of property:

id string<uuid> required
activity_name string required

The custom activity whose property this promotes; a lowercase identifier.

property_name string required

The property key inside the activity's properties; a lowercase identifier.

type string enum required

One of: string, number, bool, datetime, enum

enum_values array<string> optional

Allowed values when type is enum; omitted otherwise.

description string required
created_at string<date-time> required
updated_at string<date-time> required
mutation_class string enum required

How an edit affects dependent Segment predicates: free (no effect), safe_but_stale (an enum value was removed; predicates stay valid), or disruptive (a cast-class change or a demote that raises a standing per-segment warning).

One of: free, safe_but_stale, disruptive

impact object optional

Present only for a disruptive edit; the committed impact.

401 Missing, malformed, or unknown API key application/problem+json
403 Key lacks the required scope or plan limit violated application/problem+json
404 Resource not found application/problem+json
409 The mutation is rejected by a state rule rather than a bad request. The code is conflict. application/problem+json
422 A query parameter, path value or body field failed validation. The body is a validation_failed Problem. When the refusal is about a reference — a segment key, template slug, topic or attribute name the organization does not have — it additionally carries validation_code, field, line/column, missing, candidates and next_step, so a client can correct the call without a second round of guessing. See ValidationProblem. application/problem+json
429 Per-org rate limit exceeded application/problem+json
500 Unexpected server-side failure. The code is internal_error. The request_id field can be quoted to SendOps support to investigate. application/problem+json