DocsAPI reference

Playground chat

One real turn, streamed with exactly the widget's frames.

post/api/agents/{agent_id}/playground/chat
Authentication
Bearer token
Retries
Idempotency-Key
Body
application/json
Version
2026-09-03

Path parameters#

  • agent_idstringrequired

Headers#

  • Idempotency-Keystring

    A unique key of your choosing, so this request can be retried safely. The first request with a given key executes; every replay returns that first response unchanged, with Idempotent-Replay: true set.

    Generate one key per action, not per session - reusing a key with a different body is refused with 422 rather than silently replaying the wrong answer. Keys are remembered for 24 hours. A request that failed releases its key, so a retry after fixing the payload runs normally.

    Up to 255 characters

Request body#

application/json · required

PlaygroundChat

  • messagestringrequired

    1–4000 characters

  • session_idstringrequired

    8–64 characters·Pattern: ^[A-Za-z0-9_-]+$

  • modelstring | null

    Up to 128 characters

  • overridesPlaygroundOverrides | null

    The behaviour fields a test may try. Bounds match AgentUpdate.

    9 fieldsPlaygroundOverrides
    • fallback_messagestring | null

      Up to 1000 characters

    • languagestring | null

      Up to 16 characters

    • lead_capture_configLeadCaptureConfig | null
      7 fieldsLeadCaptureConfig
      • ask_in_chatboolean

        Default: true

      • enabledboolean

        Default: false

      • fieldsarray of LeadCaptureField

        Up to 10 items

        5 fieldsLeadCaptureField
        • keystringrequired

          1–40 characters·Pattern: ^[a-z][a-z0-9_]*$

        • labelstringrequired

          1–100 characters

        • placeholderstring | null

          Up to 120 characters

        • requiredboolean

          Default: false

        • typestring

          One of: text, email, phone, select, number·Default: text

      • introstring | null

        Up to 300 characters

      • titlestring | null

        Up to 120 characters

      • triggerstring

        One of: before_chat, after_n_messages, manual·Default: manual

      • trigger_valueinteger | null

        Default: 2·≥ 1 and ≤ 50

    • max_tokensinteger | null

      ≥ 64 and ≤ 32768

    • strict_kb_modeboolean | null
    • suggest_followupsboolean | null
    • system_promptstring | null

      Up to 20000 characters

    • temperaturenumber | null

      ≥ 0 and ≤ 2

    • thinking_enabledboolean | null

Responses#

  • 200OKapplication/json

    any

    5 response headers
    RateLimit-Limit

    Requests permitted in the current window.

    RateLimit-Remaining

    Requests left in the current window. Back off before it reaches 0.

    RateLimit-Reset

    Seconds until the current window resets.

    X-API-Version

    The dated version of the API contract that served this response, e.g. 2026-09-03. Pin against it; it changes only when a response shape changes incompatibly.

    X-Request-ID

    Quote this in a support request to identify the call.

  • 422Validation error

    The shared error envelope, served as application/problem+json with error.code set to validation_error. Its details name each field that failed and why.

Errors#

Failures use one envelope on every endpoint, described in Retries, versioning and limits. The codes you are most likely to meet here:

  • validation_error · 422 — The payload was well-formed JSON but failed schema validation.
  • unauthenticated · 401 — The request carried no API key, or one the API could not verify.
  • forbidden · 403 — The key is valid, but it is not allowed to do this — either the scope is missing or the resource belongs to another workspace.
  • idempotency_key_reused · 422 — This `Idempotency-Key` was used before, for a request with a different body.
  • rate_limited · 429 — Too many requests in the current window. The limit is per workspace, and some endpoints add a per-agent limit on top.

More Playground endpoints#

Something unclear or missing? Tell us and we’ll fix it.