Skip to content
Arc XP

Ask the Source Developer Guide

Last updatedView as Markdown

API Reference: View the complete Ask the Source API specification

Ask the Source is an Arc XP product that lets readers ask natural-language questions about your newsroom’s content. It queries your Arc XP news corpus and returns AI-generated answers with cited articles, streamed in real time.

Two npm packages integrate Ask the Source into your application:

PackageWhat it is
@arcxp/ask-the-source-sdkTypeScript SDK: direct API access (queries, SSE streaming, feedback, settings). Use this if you are building a custom UI or working outside of React.
@arcxp/ask-the-source-componentsReact component library built on the SDK, with a drop-in <AskChat/> plus composable views and hooks. Use this if you want a working UI with minimal setup.

Which package do I need?

  • Building a React app and want a ready-made UI? Install @arcxp/ask-the-source-components. It bundles the SDK and gives you a full chat experience in a few lines of JSX. Get started with components.
  • Building a custom UI, using a non-React framework, or need raw API access? Install @arcxp/ask-the-source-sdk. It handles auth, request/response typing, and SSE streaming. Get started with the SDK.

Installing the packages

The packages are published to the public npm registry under the @arcxp scope. No token or .npmrc setup is needed:

Terminal window
npm install @arcxp/ask-the-source-components   # React UI (includes the SDK)
# or
npm install @arcxp/ask-the-source-sdk          # SDK only

Both packages require Node.js 22 and above. The components package also requires React 18 or 19, provided by your app as peer dependencies.

Documentation

  • SDK docs: API reference, query methods, SSE streaming, error handling
  • Components docs: <AskProvider>, <AskChat/>, composable views, hooks, theming

Running the demo app

apps/demo is a minimal demo app showing how the packages are wired together: a single page rendering <AskProvider> + <AskChat/>. It is dev-only and runs off the Vite dev server.

Prerequisites: Node.js 22 and above.

Terminal window
npm install       # installs the demo and the published @arcxp packages
npm run dev       # starts the demo on http://localhost:3000

Point the demo at your Ask the Source deployment with these environment variables (e.g. via apps/demo/.env.local or real environment variables):

VariableDescriptionExample
VITE_ATS_BASE_URLAPI base URLhttps://myorg-config-sandbox.api.arc-cdn.net/ask
VITE_ATS_WEBSITESite identifiermy-site
VITE_ATS_API_KEYSite-scoped API key (sent as the X-Api-Key header)(your site’s API key)

License

Both packages are published under the ISC License. The license text ships in the LICENSE file of each package. Use requires an active Arc XP subscription.