Skip to main content

Create Gate

Create a review gate with POST /v1/structuring/gates, scoped to one schema. Add rules afterwards to set thresholds; a rule-less gate auto-approves everything.

POST /v1/structuring/gates creates a review gate that decides, per structuring result, whether the record auto-approves or is flagged for manual review. A gate is scoped to one schema and starts with no rules; attach rules via [POST /v1/structuring/gates/{id}/rules](gate-rules) to define the actual thresholds. The on_approve and on_flag fields are action labels recorded on the gate (defaults export and queue) that downstream tooling reads to decide what passing and flagged results should do.

Gate evaluation runs automatically after a result's validation checks complete: every active rule must pass for the gate to record an auto_approved decision; any failing rule records a pending decision carrying per-rule outcomes and a validation summary. Because rules are ANDed, model your policy as a small set of independent conditions — e.g. one min_confidence rule plus one validation_pass rule — rather than one complex rule.

A newly created gate has an empty rules array, and a gate with no active rules passes vacuously: every result is auto-approved. Create the gate and attach its first rule in the same deployment step, or you will silently ship an always-open gate.
POST/v1/structuring/gates

Body parameters

name*stringGate name.
user_schema_id*uuidSchema this gate applies to. Must be a valid UUID; fixed for the life of the gate.
on_approvestringAction label on approval. Defaults to export.
on_flagstringAction label on flag. Defaults to queue.
auto_approve_after_hoursnumberOptional auto-approval window in hours recorded on the gate. Omit to leave unset.
destination_iduuidOptional delivery destination to associate with this gate.

curl

curl -s -X POST https://api.talonic.com/v1/structuring/gates \
  -H "Authorization: Bearer tlnc_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Finance approval gate",
    "user_schema_id": "36ef3a00-a4dc-4e49-af6a-66ae20f9b58a",
    "auto_approve_after_hours": 24
  }'

Response

Response fields (201 Created)

idstringGate UUID.
namestringGate name.
user_schema_idstringSchema this gate applies to.
destination_idstring | nullAssociated delivery destination, if provided.
on_approvestringAction label on approval.
on_flagstringAction label on flag.
auto_approve_after_hoursnumber | nullAuto-approval window in hours, if configured.
is_activebooleanAlways true for newly created gates.
rulesarrayEmpty array — rules must be added separately.
created_atstringISO 8601 creation timestamp.
updated_atstringISO 8601 last update timestamp.
linksobjectRelated resource URLs (self, rules).

Response (201 Created)

{
  "id": "4014c518-7f75-425c-bf67-3052464b95a0",
  "name": "Finance approval gate",
  "user_schema_id": "36ef3a00-a4dc-4e49-af6a-66ae20f9b58a",
  "destination_id": null,
  "on_approve": "export",
  "on_flag": "queue",
  "auto_approve_after_hours": 24,
  "is_active": true,
  "rules": [],
  "created_at": "2026-08-29T11:35:09.040Z",
  "updated_at": "2026-08-29T11:35:09.040Z",
  "links": {
    "self": "/v1/structuring/gates/4014c518-7f75-425c-bf67-3052464b95a0",
    "rules": "/v1/structuring/gates/4014c518-7f75-425c-bf67-3052464b95a0/rules"
  }
}

Errors

Error responses

400VALIDATION_ERRORA required field is missing or malformed (name, user_schema_id), or a master-view API key was used on a create operation.
401unauthorizedMissing or invalid API key.
429rate_limitedToo many requests. Retry after the period indicated in the Retry-After header.

The typical setup sequence is: create the gate, then immediately add a min_confidence rule (config key min, e.g. { "min": 0.85 }) and a validation_pass rule ({ "scope": "all", "max_failures": 0 }). From then on, low-confidence rows and rows with failing checks park as pending decisions, visible check-by-check in the [pending review queue](pending-approvals), while clean rows auto-approve without human touch.

Gates only govern results produced after they exist — creating a gate does not retroactively evaluate earlier runs, and deleting one does not retract decisions it already recorded. When rolling a gate out over live traffic, create it with rules attached in the same maintenance window as your check changes, so every result in a run is judged by the same policy.

Frequently asked questions

What is the typical workflow after creating a gate?+
Attach rules immediately via POST /v1/structuring/gates/{id}/rules — usually a min_confidence rule and a validation_pass rule. Until at least one rule is active, the gate auto-approves every result. Then monitor GET /v1/structuring/approvals/pending and action flagged results with the approve/reject endpoints.
Can I create multiple gates for the same schema?+
Yes. Multiple gates can target the same user_schema_id. Each gate evaluates independently and records its own decision per result, so you can separate concerns — e.g. one confidence gate and one compliance gate — and approve them independently by gate_id.
Is user_schema_id required when creating a gate?+
Yes. Both name and user_schema_id are required; the gate only evaluates structuring results produced against that schema. The schema scope cannot be changed later via PUT — create a new gate for another schema.
Do on_approve and on_flag validate against a fixed list?+
No — they are free-form action labels with defaults export and queue. They describe intent for downstream tooling; the gate mechanics themselves (decision recording, queueing of failures) behave the same regardless of the labels.

Related

List Gates
Get / Update / Delete Gate
Manage Gate Rules
Delivery Destinations
Approve / Reject a Result