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

# Transition Guide

> Transition from Spark MCP v1 to v2beta

> [!WARNING]
>
> **Beta.** `/v2beta/spark-api/mcp` is a preview endpoint, not the final v2 surface.
> An official frozen `/v2` will be published later from this channel — plan for a further
> URL update then. v1 remains available and is not deprecated.

## What you need to change

1. **URL** — point clients at the single v2beta endpoint (see mapping below).
2. **Tool names** — especially if you used the OpenAI profile (`search` / `fetch`).
3. **New tools** — adopt `global_filters` and `audience_generation` where relevant.

## Endpoint mapping

| Client type | v1 | v2beta |
| :- | :- | :- |
| Standard MCP clients | `/v1/spark-api/mcp` | `/v2beta/spark-api/mcp` |
| OpenAI / ChatGPT connectors | `/v1/spark-api/openai/mcp` | `/v2beta/spark-api/mcp` |

There is no separate OpenAI route on v2beta. OpenAI clients use the same URL and the same standard tool names as everyone else.

```text theme={null}
POST https://api.globalwebindex.com/v2beta/spark-api/mcp
```

## Tool mapping

| v1 standard | v1 OpenAI | v2beta | Notes |
| :- | :- | :- | :- |
| `chat_gwi` | `search` | `generate_insights` | Discovery (see argument changes below) |
| `explore_insight_gwi` | `fetch` | `explore_insight` | Follow-up enrichment; returns structured JSON; replaces OpenAI `fetch` on this channel |
| `list_datasets` | `list_datasets` | `list_datasets` | Dataset discovery |
| `search_audiences` | `search_audiences` | `search_audiences` | Find saved audiences |
| — | — | `global_filters` | Location / timeframe scope |
| — | — | `audience_generation` | Create audiences from prompts |
| — | — | `list_skills` | Discover workflow skill keys and descriptions |
| — | — | `get_skills` | Retrieve full workflow skill instructions |
| — | — | `explore_datasets` | Dataset summaries and coverage |
| — | — | `explore_taxonomy` | Survey questions and attributes for a topic |

## Argument and response changes

v1 discovery tools take a single string **`prompt`**. v2beta **`generate_insights`** takes **`prompts[]`** (one or more short strings per call; see `tools/list` for limits).

| v1 (`chat_gwi` / `search`) | v2beta (`generate_insights`) |
| :- | :- |
| `arguments.prompt` (string) | `arguments.prompts[]` (array of strings) |
| Insight IDs at top level of the discovery payload (varies by client parsing) | `structuredContent.results[]` — one object per prompt, in the same order as `prompts[]` |
| Pass insight UUID to `explore_insight_gwi` / `fetch` from discovery output | Use `results[].insights[].id` for `explore_insight.insight_id` |

Read each prompt's outcome from **`structuredContent.results[]`**. Soft failures for a single prompt appear on that result object (`results[].error` / `results[].message`), not only at the top level of `structuredContent`.

**Custom clients:** build every `tools/call` payload from the **`tools/list`** input schemas for the tools you invoke — do not hardcode argument shapes from v1 or from these guides. See [MCP Server integration guide](https://api.globalwebindex.com/docs/spark-mcp/v2beta/integration-guide/mcp-api.md).

## Suggested migration checklist

1. Keep your v1 integration running.
2. Add or point a test connector / client at `/v2beta/spark-api/mcp` (ChatGPT uses this same URL — there is no `/openai/mcp` on v2beta).
3. If you hardcode tool names in a custom agent, replace `chat_gwi` / `search` with `generate_insights`, and `fetch` / `explore_insight_gwi` with `explore_insight`.
4. Always call `global_filters` before audience or insight tools on a new analysis. See [Overview](https://api.globalwebindex.com/docs/spark-mcp/v2beta/overview.md).
5. Use `search_audiences` or `audience_generation` when the request needs an audience; pass IDs into `generate_insights.enforced_audiences`.
6. Retest Claude, ChatGPT, and any custom agents against the single endpoint.

## What stays the same

* MCP lifecycle: `initialize` → `notifications/initialized` → `tools/list` → `tools/call`
* Authentication model (OAuth 2.0 and access tokens) — see [Authorization](https://api.globalwebindex.com/docs/spark-mcp/v2beta/getting-started/authorization.md)
* v1 remains available; existing dual routes are unchanged

## Related

* [Overview](https://api.globalwebindex.com/docs/spark-mcp/v2beta/overview.md)
* [Integration guide](https://api.globalwebindex.com/docs/spark-mcp/v2beta/integration-guide/overview.md)
* [Changelog](https://api.globalwebindex.com/docs/spark-mcp/v2beta/changelog.md)