Skip to main content
PUT
/
v1
/
trace
/
config
Set Trace config for an agent (or the org default)
curl --request PUT \
  --url https://api.pyai.com/v1/trace/config \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "agent_id": "<string>",
  "enabled": false,
  "channels": [
    "voice"
  ],
  "rule_packs": {},
  "guardrails": {
    "mode": "warn",
    "block_pii": {
      "patterns": []
    },
    "mandatory_disclosures": [
      {
        "text": "<string>",
        "required_within_seconds": 123
      }
    ],
    "blocked_phrases": [
      "<string>"
    ],
    "fail_open": true,
    "inline_timeout_ms": 10
  }
}
'
{
  "object": "trace.config",
  "agent_id": "<string>",
  "enabled": true,
  "etag": "<string>",
  "updated_at": 123,
  "config": {
    "agent_id": "<string>",
    "enabled": false,
    "channels": [
      "voice"
    ],
    "rule_packs": {},
    "guardrails": {
      "mode": "warn",
      "block_pii": {
        "patterns": []
      },
      "mandatory_disclosures": [
        {
          "text": "<string>",
          "required_within_seconds": 123
        }
      ],
      "blocked_phrases": [
        "<string>"
      ],
      "fail_open": true,
      "inline_timeout_ms": 10
    }
  }
}

Authorizations

Authorization
string
header
required

Use Authorization: Bearer pyai_live_... (or pyai_test_...).

Body

application/json

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
default:false
channels
enum<string>[]
Available options:
voice,
text
rule_packs
object

Map of pack_id → { enabled, version }, e.g. { tcpa: { enabled: true } }.

guardrails
object

Inline guardrails compiled into a synthesized rule pack (spec §5.1).

Response

Stored config

object
string
Example:

"trace.config"

agent_id
string | null
enabled
boolean
mode
enum<string>
Available options:
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
object

Per-agent Trace config (spec §5.1). May be wrapped as { agent_id, config } or sent raw.