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.

Git-backed definitions are read-only here (409 conflict) — edit them in the connected repo.

Path parameters

id string<uuid> required

Resource UUID. An unparseable id reads as a clean 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
origin string enum optional

Where the property is authored: managed (via the API/dashboard) or git (synced from a connected repo and read-only via the API).

One of: managed, git

source_path string optional

Repo-relative source file, for git-backed properties only.

last_synced_at string<date-time> optional

Time of the last git sync, for git-backed properties only.

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 — e.g. editing a git-backed (read-only) definition. The code is conflict. application/problem+json
422 Query parameter or path value failed validation 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