# Ask the Source Developer Guide

Source: https://dev.arcxp.com/ask-the-source/developer-docs/ask-the-source-developer-guide/

Integrate Ask the Source with the JavaScript SDK and React component library.

**API Reference:** [View the complete Ask the Source API specification](https://dev.arcxp.com/api/ask-the-source-api/)

**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:

| Package                                                                                            | What it is                                                                                                                                                 |
| -------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [@arcxp/ask-the-source-sdk](https://www.npmjs.com/package/@arcxp/ask-the-source-sdk)               | TypeScript 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-components](https://www.npmjs.com/package/@arcxp/ask-the-source-components) | React 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.](https://www.npmjs.com/package/@arcxp/ask-the-source-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.](https://www.npmjs.com/package/@arcxp/ask-the-source-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

```bash
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](https://www.npmjs.com/package/@arcxp/ask-the-source-sdk): API reference, query methods, SSE streaming, error handling
- [Components docs](https://www.npmjs.com/package/@arcxp/ask-the-source-components): `<AskProvider>`, `<AskChat/>`, composable views, hooks, theming

## Running the demo app

[apps/demo](https://github.com/arcxp/ask-the-source/tree/main/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

```bash
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):

| Variable             | Description                                        | Example                                          |
| -------------------- | -------------------------------------------------- | ------------------------------------------------ |
| VITE\_ATS\_BASE\_URL | API base URL                                       | https://myorg-config-sandbox.api.arc-cdn.net/ask |
| VITE\_ATS\_WEBSITE   | Site identifier                                    | my-site                                          |
| VITE\_ATS\_API\_KEY  | Site-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.