segments

Lint a Segment predicate

POST /v1/segments/validate

Auth required api.segments.view

Parses and analyses a candidate SendQL predicate against the org's attribute registry and returns positioned diagnostics plus the attributes the predicate reads. Nothing is persisted, no contacts are read, and no sample is returned — this is the cheap loop to run while writing a predicate, before POST /v1/segments/preview sizes it and POST /v1/segments commits it.

Always 200, including for a predicate that does not compile: valid is the answer, and the diagnostics say where and why. The one 422 is a body with no source at all.

Request body

Content type: application/json

source string required

The candidate SendQL predicate to lint.

Responses

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

200 The lint result — valid or not, with diagnostics application/json

valid boolean required

Whether the predicate compiles.

eval_class string enum optional

How membership would be reconciled. Absent when the predicate does not compile.

One of: incremental, sweep, both

diagnostics array<object> required

Every finding, in source order. Empty for a predicate that lints clean.

Each entry in diagnostics:

severity string enum required

One of: error, warning

line integer required

1-based line of the fault; 0 when the finding carries no position.

column integer required

1-based column of the fault; 0 when the finding carries no position.

message string required

referenced_attributes array<string> required

The contact attributes the predicate reads (attr.<name>), in analyzer order — the attributes that have to stay populated for the Segment to keep meaning what it says. Empty when the predicate does not compile.

401 Missing, malformed, or unknown API key application/problem+json

403 Key lacks the required scope or plan limit violated 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

{ "valid": true, "eval_class": "incremental", "diagnostics": [ { "severity": "error", "line": 0, "column": 0, "message": "string" } ], "referenced_attributes": [ "string" ] }