> ## Documentation Index
> Fetch the complete documentation index at: https://api.globalwebindex.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# 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.

> [!NOTE]
>
> Agent Spark is in beta. Request and event formats can change.

## **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.

| | **Spark API** (`/v1/spark-api/generic`) | **Agentic API** (Agent Spark) |
| - | - | - |
| **Prompting** | Works best with **tight, structured prompts**: clear audience, a focused question, and often explicit dataset or timeframe scope. Vague or conversational wording often yields weak or irrelevant insights. | Tolerates **open-ended, chat-style prompts**. Spark interprets intent, refines scope, and can clarify across turns with **`chat_id`**. |
| **Interaction** | One JSON response per request | SSE event stream until `end` or `error` |
| **Best for** | Fixed templates, batch jobs, and backends where **you control prompt wording** (see [Structuring a Query](https://api.globalwebindex.com/docs/spark-api/getting-started/structuring-query.md)) | User-facing chat, copilots, and agents where **end users type freely** |
| **Typical output** | JSON with **`message`**, **`insights`**, **`chat_id`**, and **`sources`** | Markdown answer, cited **`insights`**, and expanded **`sources`** metadata across events |
| **Request extras** | Optional **`limit`** (1–20 insights per query) | Same scoping fields as generic; no **`limit`** on Agent Spark |

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](https://api.globalwebindex.com/docs/spark-api/getting-started/insight.md). For streaming chat, see [Stream responses with Agent Spark (beta)](https://api.globalwebindex.com/docs/agentic-api/getting-started/agent-spark-streaming.md).

## **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](https://api.globalwebindex.com/docs/spark-api/getting-started/working-with-multiple-data-sets.md))
* 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)

> [card] [Prerequisites](https://api.globalwebindex.com/docs/agentic-api/getting-started/prerequisites.md)
>
> API key and tools you need before your first request

> [card] [Stream with Agent Spark](https://api.globalwebindex.com/docs/agentic-api/getting-started/agent-spark-streaming.md)
>
> Request format, event order, and error handling