Configure the inference hook

⚠️
Preview — this feature is being built; the design below is the spec.
PUT https://app.syntic.ai/v1/organizations/inference_hook

Create or replace the organization’s inference policy hook: an HTTPS endpoint of yours that receives each model request and answers allow, deny or allow with redactions before the model runs. The first creation returns a signing_secret for verifying the calls Syntic makes to your endpoint. Enterprise plans only.

For how this fits into a full workflow, see Inference policy hooks.

Headers

HeaderRequiredValue
AuthorizationYesBearer <admin key>: an Admin API key (sk_admin_...). Inference keys are refused with 403 admin_key_required. See Admin API keys.
syntic-betaYes, while in previewadmin-2026-11-01. Without it the call fails with 400 beta_required. See Versioning.
Content-TypeYesapplication/json

Body parameters

ParameterTypeRequiredNotes
urlstringYesHTTPS URL that resolves to a public address.
enabledbooleanYesTurn the hook on or off.
timeout_msintegerNo100 to 5000, default 1500.
failure_modestringNofail_closed (default: deny when the hook fails) or fail_open.
include_contentbooleanNoDefault true: send messages and tools; false sends metadata only.
post_responsebooleanNoAlso send replies. Default false.
workspace_idsarray of stringsNoApply only to these workspaces. Default: all.
sample_ratenumberNo0.01 to 1.0. Unsampled requests are allowed. Default 1.0.

Response

200 OK, Content-Type: application/json

{
  "type": "inference_hook",
  "url": "https://ai-gateway.example.com/syntic-hook",
  "enabled": true,
  "timeout_ms": 1000,
  "failure_mode": "fail_closed",
  "include_content": true,
  "post_response": false,
  "workspace_ids": [],
  "sample_rate": 1.0,
  "updated_at": "2026-11-05T10:00:00Z",
  "signing_secret": "whsec_Hk3...redacted"
}

signing_secret appears only when the hook is first created and after rotating the secret.

Examples

curl -sS -X PUT https://app.syntic.ai/v1/organizations/inference_hook \
  -H "Authorization: Bearer $SYNTIC_ADMIN_KEY" \
  -H "syntic-beta: admin-2026-11-01" \
  -H "Content-Type: application/json" \
  -d '{
      "url": "https://ai-gateway.example.com/syntic-hook",
      "enabled": true,
      "timeout_ms": 1000,
      "failure_mode": "fail_closed"
    }'

Errors

Errors use the error envelope and carry a request_id. Codes specific to this operation:

StatustypecodeWhen
400invalid_request_errorbeta_requiredThe syntic-beta header is missing.
400invalid_request_errorinvalid_urlNot HTTPS or not a public address.
400invalid_request_errorinvalid_parameterA value out of range; param names it.
403permission_errorrole_requiredOnly keys created by an Owner may change this.
403permission_errorplan_requiredInference hooks need an Enterprise plan.
401authentication_errorinvalid_api_keyThe admin key is missing, unknown, revoked or expired.
403permission_erroradmin_key_requiredAn inference key was used.
429rate_limit_errorrate_limitedToo many requests; wait for Retry-After. See Rate-limit headers.
Was this page helpful?