Introduction

The Agentic API is GWI’s beta REST surface for Agent Spark: a streaming chat endpoint that runs Spark as an agent over audience data. It targets products that need conversational answers, visible progress while Spark works, and structured citations in the same response.

​

What is the Agentic API?

The Agentic API exposes Agent Spark at POST /beta/spark-api/agents/spark. You send a natural-language prompt (and optional dataset or audience scope), keep the HTTP connection open, and read a Server-Sent Events (SSE) stream until Spark finishes or reports an error. The stream is staged, not a single JSON blob:

• Provisional thinking text while Spark works
• Sources that describe scope (topics, audiences, datasets, and related fields)
• Insights with cited statistics and audience origins
• A final Markdown answer you can render in a chat UI

You can continue a conversation by sending a follow-up request with the chat_id from the stream.

​

Choosing between the Spark API and the Agentic API

Use the Spark API when you shape the prompt and want one complete JSON answer. Use the Agentic API (Agent Spark) when users type naturally and you want streaming chat with progress events, citations and follow-ups on the same chat_id. Pick one per flow. Use /v1/spark-api/generic when you already know how to phrase the question and can reuse that pattern reliably. Use Agent Spark when the product behaves like a conversation and you cannot expect users to follow Spark’s prompt recipe on every turn. For a first generic call with a shaped prompt, see the Quickstart. For streaming chat, see Stream responses with Agent Spark (beta).

​

Use cases

Agent Spark fits products where prompt quality varies and the UX must carry the user:

• Customer-facing or internal chat assistants with free-text questions
• Copilots and agents that must show sources, cited stats, and a readable Markdown answer
• Long or ambiguous questions where streaming progress (loading events) improves perceived latency
• Multi-turn research with the same chat_id, without rewriting the prompt from scratch each time

The generic v1 endpoint is a poor fit for those flows. Prefer it only when your integration supplies a carefully defined prompt (or generates one from a fixed form or template).

​

Key features

• REST endpoint under the /beta/spark-api/agents/ path
• SSE event types including chat_init, loading, sources, insights, natural_language, and end
• Optional request fields shared with the Spark generic chat endpoint: chat_id, dataset_code, dataset_codes, and docked_audiences (see Working with multiple data sets)
• Structured error responses before the stream starts, and error events if the stream fails mid-flight

​

Outputs

• text/event-stream body made of named SSE events with JSON data payloads
• A chat_id on every event for follow-ups
• A sources event with richer scope metadata than the generic JSON response, including location_groups, timeframe_groups, attribute_codes, questions, and namespaces, plus audience entries with fields such as title, description, is_origin, sample_size, and universe
• insights entries with id, text, and audience origins (id and name per audience)
• A finished natural_language_response in Markdown when the stream succeeds, with sources_available indicating whether citation metadata was included
• Failures that expose code, message, and retryable (JSON before the stream starts, or an error event mid-stream)