Skip to main content
POST
Create a synthesis template
Creates a template and answers 201 with it. name must not be blank; name and description are stored trimmed. status defaults to active. Each constraint is {path, evaluator, value, message?}. path is the dot-path into the synthesis spec, one segment per item (for example ["name"]). value follows the evaluator: The Spec Linter skips a constraint it cannot evaluate (an empty or invalid regex, an empty allowlist), so this route refuses one with 400 instead of storing it. The body is strict: an unknown field is 400. Without an Idempotency-Key, a repeat creates a second template, as in the Console: send a key. Needs synthesis:manage, and the credential’s scopes must also reach platform:read, because the answer is a read of what was written; a credential missing either is refused 403 before anything runs. Both must then be held at the platform scope: a grant that covers only some org units receives 403 naming the first one missing, and nothing is written. A Personal key writes as its owner; an External App or platform key is recorded as itself (see Who wrote it). Send an Idempotency-Key to make a retry safe: the same key and body within 24 hours returns the recorded answer only while your scopes still reach platform:read and you still hold platform:read and synthesis:manage at the platform scope; otherwise 409 idempotency_result_unavailable, and the write never runs twice. The same key with a different body is 422. See Synthesis settings writes.

Authorizations

Authorization
string
header
required

An External App: the JWT it obtains from POST /oauth/token with OAuth2 client_credentials. Pass as Authorization: Bearer <jwt>. An app's static companion key also authenticates as the app, but is deprecated and is not protected by Idempotency-Key.

Headers

Idempotency-Key
string

Optional logical intent key. A same-key retry within 24 hours returns the recorded result without writing again.

Required string length: 1 - 255

Body

application/json
name
string
required

Shown in Console; stored trimmed; at most 200 characters.

Maximum string length: 200
description
string
required

What the template enforces; stored trimmed; at most 2000 characters.

Maximum string length: 2000
appliesTo
enum<string>
required

The primitive kind the template governs.

Available options:
skill,
agent,
procedure
enforcement
enum<string>
required

hard blocks the Builder's dispatch on a violation; warn only reports it.

Available options:
hard,
warn
constraints
object[]
required

At most 50 constraints, all evaluated with the same enforcement.

Maximum array length: 50
status
enum<string>

Defaults to active; only active templates are enforced.

Available options:
active,
disabled,
draft

Response

The created template

data
object
required
meta
object
required