---
title: "Set Trace config for an agent (or the org default)"
method: PUT
path: "/v1/trace/config"
tags: ["Trace"]
---

# Set Trace config for an agent (or the org default)

`PUT /v1/trace/config`

## Request

- Base URL: `https://api.pyai.com`
- URL: `https://api.pyai.com/v1/trace/config`
- Auth: one of:
  - HTTP bearer
  - API key in header `x-api-key`

Upsert the per-agent Trace config (spec §5.1). The body is the §5.1 object (optionally
wrapped as `{ agent_id, config }`). Modes: `warn` (log only, never blocks) · `modify`
(redact PII / inject disclosures) · `block` · `human_handoff`. Always fail-open; the
deterministic inline gate runs models-side, the platform only distributes config.
Returns the stored config with its content `ETag` (the models-side pull pins this).
Requires the `trace:configure` scope.

## Request body

- TraceConfigInput: Per-agent Trace config (spec §5.1). May be wrapped as { agent_id, config } or sent raw.
  - `agent_id` string: Agent to configure; omit for the org-wide default.
  - `enabled` boolean
  - `channels` string[]
  - `rule_packs` object: Map of pack_id → { enabled, version }, e.g. { tcpa: { enabled: true } }.
  - `guardrails` TraceGuardrails: Inline guardrails compiled into a synthesized rule pack (spec §5.1).
    - `mode` 'warn' | 'modify' | 'block' | 'human_handoff': warn = log only (never blocks); modify = redact/inject; block = suppress; human_handoff = escalate.
    - `block_pii` object
      - `patterns` string[]: Deterministically-redactable PII (context-dependent PII like DOB is Tier-2, not inline).
    - `mandatory_disclosures` object[]
      - `text` string, required: Phrase the agent must speak, e.g. an AI / recording disclosure.
      - `trigger` 'call_start' | 'any': call_start = must appear on the first agent turn.
      - `required_within_seconds` number: Deadline in seconds; otherwise a 2-turn default applies.
    - `blocked_phrases` string[]: Phrases the agent must never say.
    - `fail_open` boolean: Trace down must never make a call worse, log 'unavailable' instead of blocking.
    - `inline_timeout_ms` number: Inline budget; the in-process gate is ~14µs p99, far under this.

## Response `200`

Stored config

- TraceConfig
  - `object` string
  - `agent_id` string, nullable
  - `enabled` boolean
  - `mode` 'warn' | 'modify' | 'block' | 'human_handoff'
  - `etag` string: Content hash the models-side gate pins (version-pinned, ETag-cached pull).
  - `updated_at` integer: Unix ms.
  - `config` TraceConfigInput: Per-agent Trace config (spec §5.1). May be wrapped as { agent_id, config } or sent raw.
    - `agent_id` string: Agent to configure; omit for the org-wide default.
    - `enabled` boolean
    - `channels` string[]
    - `rule_packs` object: Map of pack_id → { enabled, version }, e.g. { tcpa: { enabled: true } }.
    - `guardrails` TraceGuardrails: Inline guardrails compiled into a synthesized rule pack (spec §5.1).
      - `mode` 'warn' | 'modify' | 'block' | 'human_handoff': warn = log only (never blocks); modify = redact/inject; block = suppress; human_handoff = escalate.
      - `block_pii` object
        - `patterns` string[]: Deterministically-redactable PII (context-dependent PII like DOB is Tier-2, not inline).
      - `mandatory_disclosures` object[]
        - `text` string, required: Phrase the agent must speak, e.g. an AI / recording disclosure.
        - `trigger` 'call_start' | 'any': call_start = must appear on the first agent turn.
        - `required_within_seconds` number: Deadline in seconds; otherwise a 2-turn default applies.
      - `blocked_phrases` string[]: Phrases the agent must never say.
      - `fail_open` boolean: Trace down must never make a call worse, log 'unavailable' instead of blocking.
      - `inline_timeout_ms` number: Inline budget; the in-process gate is ~14µs p99, far under this.

## Other responses

- `400`: Invalid request (bad field, unsupported value)
- `401`: Missing or invalid API key (`code: unauthorized`)
- `404`: agent_id does not belong to this tenant.

---

[API](https://skmtc.dev/pyai/apis/pyai-api.md) · [All operations](https://skmtc.dev/pyai/apis/pyai-api/llms.txt) · [OpenAPI document](https://skmtc.dev/pyai/apis/pyai-api/revisions/819d8e7c4d09?raw)