Create or update one item

Upserts one item of a snapshot and busts the flow's config cache. Admin only: the handler calls requireKYBConfigAdmin, which resolves the caller and then checks Storage.IsAdminAccount. A non-admin gets 403 common.forbidden. Both path segments are validated before the admin check. The server OVERWRITES five fields of the body: flow_id and name from the path, active to TRUE, and created_by / modified_by from the caller. An item therefore cannot be deactivated through this route. The response echoes the amended input struct rather than re-reading the stored row. The cache is ALWAYS invalidated on success, whatever the body carried. The handler hands the item to the repository by pointer and only reads FlowName back afterwards; because it always sets FlowID from the {flow_id} path segment, resolveItemFlowIdentity takes the by-id branch and fillFlowNameFromFlowID writes the name into that same struct before the row is written. The one real caveat is ordering: the invalidation happens AFTER the write and is not rolled back if it fails, so a cache that cannot be reached leaves the write committed and the config stale.

Authorization

bearerAuth

AuthorizationBearer <token>

In: header

Path Parameters

flow_id*string

A flows_config snapshot id. Must parse as a non-nil UUID; the nil UUID is rejected 400.

item_name*string

Step name within the snapshot. Must be non-empty.

Request Body

application/json

Item fields.

TypeScript Definitions

Use the request body type in TypeScript.

REQUEST shape of PUT /v1/kyb/config/flows/{flow_id}/items/{item_name} only. Same properties as KYBItemInput, but name is NOT required: the handler overwrites whatever the body carries with the {item_name} path segment. Use KYBItemInput for the import array, where nothing supplies a name and it therefore is required.

id?string

Row id, generated by the server when the body carries none.

flow_name?string

Flow this item belongs to. Set by the server on import.

flow_id?string

Owning flows_config snapshot. On PUT the server OVERWRITES the body value with the path segment.

name?string

Step name, unique within the flow. On PUT the server OVERWRITES the body value with the {item_name} path segment.

type*string

Question/node type. Free-form here; the flow engine matches it against its own set (single, multiple, text, textarea, number, date, yesno, dropdown, lookup, multi-lookup, file, …) and an unknown value fails at navigation time, not on write.

Question text, localised map. Omitted when unset.

description?

Description, localised map. Omitted when unset.

schema?

JSON Schema for the answer form. Omitted when unset.

ui_schema?

RJSF uiSchema. Omitted when unset.

form_data?

Prefilled form data. Omitted when unset.

section?

Section assignment. Omitted when unset.

next?unknown

Routing to the next step. Untyped in Go (any), so it may be a string, an object or an array of conditions. Omitted when unset.

update_config?

Omitted when unset.

before_submit?

Submit-action block run before saving. Omitted when unset.

after_submit?

Submit-action block run after saving. Omitted when unset.

custom_function?

Omitted when unset.

custom_api?

Omitted when unset.

options?

Per-step options as stored. See FlowStepOptions for the keys and their casing. Omitted when unset.

message?

Inline message block. Omitted when unset.

buttons?array<>

Omitted when empty.

position?

Canvas position. Omitted when unset.

sort_order*integer

Order within the flow; the item list is sorted by it.

active?boolean

On PUT the server FORCES this to true. Deactivate with DELETE /v1/kyb/config/flows/{flow_id}/items/{item_name}.

system?boolean

Platform-owned flag. WRITTEN ONLY WHEN THE ROW IS CREATED: sqlKYBItemUpsert lists system in the INSERT column list but NOT in its ON CONFLICT (flow_id, name) DO UPDATE SET clause, so a PUT against an existing ACTIVE item silently drops the value and keeps what is stored. The 200 echoes the amended INPUT rather than a fresh read, so it will confirm the change you did not make. Nothing validates the field, so a caller with the config-admin grant can set it on a NEW item.

created_at?string

Server-maintained audit column, set on insert. Ignored on a request body.

created_by?string

Deleted from the response body by auth.RemoveAuditFieldsHandler for any caller without the internal role — the default configuration, unless app-config auth.audit_fields_internal is explicitly false. It triggers on the Content-Type: application/json that apireply.WithJSON always sets, re-marshals the whole body and deletes the key at every nesting depth. Absent, not null, when stripped.

modified_at?string

Server-maintained audit column, restamped on every write. Ignored on a request body.

modified_by?string

Response Body

`application/json`

curl -X PUT "https://example.com/v1/kyb/config/flows/497f6eca-6276-4993-bfeb-53cbbbba6f08/items/string" \  -H "Content-Type: application/json" \  -d '{    "type": "string",    "sort_order": 0  }'

{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "flow_name": "string",
  "flow_id": "0746f03b-16cc-49fb-9833-df3713d407d2",
  "name": "string",
  "type": "string",
  "q": {},
  "description": {},
  "schema": {},
  "ui_schema": {},
  "form_data": {},
  "section": {},
  "next": null,
  "update_config": {},
  "before_submit": {},
  "after_submit": {},
  "custom_function": {},
  "custom_api": {},
  "options": {},
  "message": {},
  "buttons": [
    {}
  ],
  "position": {
    "x": 0.1,
    "y": 0.1
  },
  "sort_order": 0,
  "active": true,
  "system": true,
  "created_at": "2019-08-24T14:15:22Z",
  "created_by": "ee824cad-d7a6-4f48-87dc-e8461a9201c4",
  "modified_at": "2019-08-24T14:15:22Z",
  "modified_by": "e8d4374d-93a1-4e98-a6c6-fdcf00c5059f"
}

{
  "status": 400,
  "message": "Invalid input",
  "code": "common.invalid_input",
  "class": "validation"
}

{
  "status": 401,
  "message": "Unauthorized",
  "code": "common.unauthorized",
  "class": "business"
}

{
  "status": 403,
  "message": "Access denied",
  "code": "common.forbidden",
  "class": "business"
}

{
  "status": 404,
  "message": "Record not found",
  "code": "common.record_not_found",
  "class": "business"
}

{
  "status": 429,
  "message": "Rate limit for 203.0.113.7 to POST:/v1/kyb/navigate exceeded.",
  "code": "rate_limits_m.exceeded",
  "class": "temporary",
  "retryable": true
}

{
  "status": 500,
  "message": "Internal server error",
  "code": "common.server_error",
  "class": "business"
}

{
  "overall_status": "unhealthy",
  "message": "Service is shutting down",
  "timestamp": "2026-08-27T15:04:05Z"
}

Authorization

Path Parameters

Request Body

Response Body

200application/json

400application/json

401application/json

403application/json

404application/json

429application/json

500application/json

503application/json

Graceful shutdown — LifecycleMiddleware, root router, not the envelope

ensureCacheAvailable could not reach the auth cache — the envelope

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`