Conversations

The Conversations API lets you list and retrieve conversation records for your Agent, and pause or resume the Agent on a specific conversation. Conversations are identified by an internal UUID and optionally by your own external_id (the same value you pass as metadata.conversation on chat completions).

Base path: /api/v1/conversations on your Agent’s domain.

Authentication #

See Authentication on the Overview page for how to authenticate Fusion API requests. An API key is always required for Conversations endpoints — same-origin requests are not exempt. Results are limited to the authenticated Agent (and its team).

List Conversations #

Use GET /api/v1/conversations to get a paginated list of conversations for the authenticated Agent, ordered by started_at descending.

curl \
--header 'x-api-key: apg_xxxxxxxxxxxxxxxxxxxxxxxxxxxx' \
--url 'https://my.gospel.bot/api/v1/conversations?page=1&per_page=50'

Pagination #

Parameter	Type	Default	Max	Description
page	integer	1	—	Page number
per_page	integer	50	100	Records per page

Response #

{
    "data": [
        {
            "id": "11111111-1111-1111-1111-111111111111",
            "external_id": "conv-123",
            "agent_id": 7,
            "team_id": 3,
            "tags": null,
            "started_at": "2026-07-22 12:00:00",
            "ended_at": null,
            "agent_paused": false,
            "agent_paused_at": null,
            "agent_resumed_at": null
        }
    ],
    "total": 1,
    "page": 1,
    "per_page": 50
}

total reflects the full count for the Agent (not just the current page).

Get Conversation #

Use GET /api/v1/conversations/{id} to retrieve a single conversation. The path accepts either:

• Internal UUID (id)
• Your external_id string (team-scoped)

If the conversation does not exist for this Agent, a 404 is returned.

curl \
--header 'x-api-key: apg_xxxxxxxxxxxxxxxxxxxxxxxxxxxx' \
--url https://my.gospel.bot/api/v1/conversations/conv-123

Response #

{
    "data": { /* conversation object */ }
}

Conversation Object #

Field	Type	Description
id	string (UUID)	Internal conversation identifier
external_id	string | null	Your conversation identifier (matches metadata.conversation on completions)
agent_id	integer	Agent that owns the conversation
team_id	integer	Team that owns the conversation
tags	array | null	Applied tag ids when present
started_at	string	UTC timestamp when the conversation started
ended_at	string | null	UTC timestamp when the conversation ended, if any
agent_paused	boolean	Whether the Agent is currently paused on this conversation
agent_paused_at	string | null	UTC timestamp of the current pause (null when not paused)
agent_resumed_at	string | null	UTC timestamp of the most recent resume (null while paused or never resumed)

Pause and Resume the Agent #

When the Agent is paused on a conversation, subsequent chat completions for that conversation (identified via metadata.conversation) skip LLM generation and responder routing. Opted-in prompt guardrails, CTAs, and automations can still run and return content; channel delivery skips sending when there is no guardrail/CTA payload to show.

Pause and resume also return the updated conversation object. Both accept the conversation’s UUID or external_id in the path.

Pause #

Use POST /api/v1/conversations/{id}/pause (no request body required):

curl \
--request POST \
--header 'x-api-key: apg_xxxxxxxxxxxxxxxxxxxxxxxxxxxx' \
--url https://my.gospel.bot/api/v1/conversations/conv-123/pause

On success, agent_paused is true, agent_paused_at is set, and agent_resumed_at is cleared. If the path uses an external_id that does not yet exist for this Agent, a conversation row may be created and then paused. Unknown internal UUIDs return 404. An external_id already owned by another Agent on the same team returns 404.

Resume #

Use POST /api/v1/conversations/{id}/resume (no request body required):

curl \
--request POST \
--header 'x-api-key: apg_xxxxxxxxxxxxxxxxxxxxxxxxxxxx' \
--url https://my.gospel.bot/api/v1/conversations/conv-123/resume

On success, agent_paused is false, agent_resumed_at is set, and agent_paused_at is cleared. The conversation must already exist for this Agent; otherwise a 404 is returned.

Response #

{
    "data": {
        "id": "11111111-1111-1111-1111-111111111111",
        "external_id": "conv-123",
        "agent_id": 7,
        "team_id": 3,
        "tags": null,
        "started_at": "2026-07-22 12:00:00",
        "ended_at": null,
        "agent_paused": true,
        "agent_paused_at": "2026-07-22 15:30:00",
        "agent_resumed_at": null
    }
}

CTAs, guardrails, and automations configured in Apologist Ignite can also pause or resume the Agent when they fire (pause_agent / resume_agent on the trigger). Some triggers may be configured to continue running while the Agent is paused (run_while_agent_paused).

Error Responses #

Status	Meaning
403	Missing or invalid API key
404	Conversation not found for this Agent
500	Internal server error
503	Agent not found or inactive for the request’s host