---
title: "Chat with a Mammoth agent"
method: POST
path: "/agents/chat"
tags: ["AI", "Agents"]
---

# Chat with a Mammoth agent

`POST /agents/chat`

## Request

- Base URL: `https://app.mammoth.io/api/v2`
- URL: `https://app.mammoth.io/api/v2/agents/chat`
- Auth: one of:
  - HTTP bearer
  - API key in header `X-API-KEY` and API key in header `X-API-SECRET` and API key in header `X-WORKSPACE-ID`

Starts an agent turn and returns its ids at once; the turn's events are read from the turn events endpoint. A retry with the same request_key returns the same turn.

## Request body

- AgentChatRequest
  - `request_key` string, required
  - `agent_key` string, nullable
  - `session_id` string, nullable
  - `message` string
  - `scope` AgentScope, required
    - `type` 'workspace' | 'user' | 'account', required: What a chat session is fundamentally scoped to. ``WORKSPACE`` — the most common shape; chat is bound to a single workspace_id (the FE page lives inside that workspace). ``USER`` — questions about the user themselves (cross-workspace profile, activity, etc.). ``ACCOUNT`` — questions spanning the user's account-level visibility (rarely used; account-scope queries fall back to per-domain user-scoped filters or trigger the required-context hint).
    - `workspace_id` integer, nullable
    - `user_id` integer, nullable
  - `client_context` object
  - `selection` AgentSelection
    - `request_id` string, nullable
    - `answers` object, nullable
    - `widget_id` string, nullable
    - `kind` 'CHOICE' | 'NEW_DATA_CHOICE' | 'ADD_DATA' | 'DATA_FINDER' | 'CONNECTOR_CREDENTIAL' | 'CONNECTOR_RECIPE' | 'CONNECTOR_VALIDATE' | 'SAMPLE_PICKER' | 'PUBLIC_DATA_PICKER' | 'PASTE_INPUT' | 'WEBHOOK_SETUP' | 'COMPARE_GATE' | 'COMBINE' | 'COLLECTOR' | 'INTERPRETER' | 'AUTOMATION_CHOICE' | 'AUTOMATION_SCHEDULE' | 'DASHBOARD_OPTIONS' | 'CONNECTOR_SPEC_PREVIEW' | 'DELIVERY_PREVIEW' | 'DELIVERY_TEST_SEND' | 'BUILD_PICKER' | 'ANSWER' | 'CONTACT_SUPPORT' | 'EXPLORE_CARDS' | 'DATA_PROFILE' | 'DASHBOARD_BRIEF': Every inline interactive card the agent can attach to a block. Wire values are frozen ``UPPER_SNAKE`` keys mirroring ``WIDGET_KIND`` in the frontend's ``agent-chat.constants.js``; member names deliberately match them so the two cannot drift. Every kind is declared even where no rendering component exists yet — emitting an unbuilt kind is safe (the card renders nothing and the block's prose still shows), but a *misspelled* kind is indistinguishable from that, which is why nothing may build one by hand. The mapping from this project's design catalog names (``resource_selection`` → ``DATA_FINDER``, ``connector_validation`` → ``CONNECTOR_VALIDATE``, …) lives in the initiative's contract-reconciliation document, not here.
    - `value` unknown
  - `is_system_event` boolean
  - `attachments` union[]
    - union
      - DatasetAttachment
        - `dataset_id` integer, required
        - `name` string, required
        - `view_id` integer, nullable
      - BiWorkbookAttachment
        - `kind` 'bi_workbook', required
        - `attachment_id` integer, required
        - `filename` string, required
        - `name` string, required
      - SourceFileAttachment
        - `kind` 'source_file', required
        - `file_id` integer, required
        - `name` string, required
        - `reading` string, nullable
      - ImageAttachment
        - `kind` 'image', required
        - `ref` string, required
        - `name` string, required
      - DocumentAttachment
        - `kind` 'document', required
        - `ref` string, required
        - `name` string, required
  - `plan_ref` PlanRef
    - `plan_id` string, required
    - `n` integer, nullable
    - `action` 'skip' | 'discard' | 'build' | 'null', nullable
    - `leave_out` integer[]
  - `credentials` object, nullable
  - `selected_columns` string[], nullable

## Response `202`

Request accepted, processing continues off-line

- AgentTurnStartedResponse
  - `session_id` string, required
  - `turn_id` string, required

## Other responses

- `400`: Bad request syntax or unsupported method
- `403`: Request forbidden -- authorization will not help

---

[API](https://skmtc.dev/mammoth/apis/mammoth-analytics.md) · [All operations](https://skmtc.dev/mammoth/apis/mammoth-analytics/llms.txt) · [OpenAPI document](https://skmtc.dev/mammoth/apis/mammoth-analytics/revisions/fe078afe239b?raw)