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

# AI chat

> Generate popular LLM completions.

export const Autoscaling = () => {
  return <Warning>
      This endpoint autoscales; if you receive a <code>503</code> response, maintain traffic and
      expect errors to resolve within a couple minutes.
    </Warning>;
};

export const Reference = ({endpoint}) => {
  return <Info>
      See also the <Link href={`reference/${endpoint}`}>API reference</Link> for more detail.
    </Info>;
};

export const apiEndpoint = 'render.joinmassive.com';

export const companyName = 'Massive';

<Reference endpoint="ai" />

## Service usage

**{companyName}'s** AI service provides all completion content and grounding sources from frontier
AI labs as structured or raw data for use in generative or language engine optimization. The service
has a RESTful interface that accepts `GET` requests at **https\://‍{apiEndpoint}/ai**.

Conversations can be localized with <Link href="geotargeting">geotargeting parameters</Link>.
They're streamed live by default or optionally queued for <Link href="scheduling">subsequent
retrieval</Link>. Live conversations take an average of several seconds but may require multiple
retries, in which case up to **3 minutes** is allocated per API call. <Link href="usage">Usage
data</Link> is published regularly.

### Authentication

You can access the service by including your secret API token in an `Authorization` header:

```http theme={null}
Authorization: Bearer [API token here]
```

Here's an example request that uses the [common Curl command](https://curl.se/):

```shell theme={null}
curl -H "Authorization: Bearer $MASSIVE_TOKEN" \
'https://render.joinmassive.com/ai'\
'?prompt=best+basketball+shoes+for+2026'\
'&country=us'\
'&city=Portland'
```

<Autoscaling />

### Chat parameters

Besides the [geotargeting and scheduling params linked above](#service-usage), required and optional
chat params can be added in a
[standard query string](https://developer.mozilla.org/en-US/docs/Learn/Common_questions/What_is_a_URL#parameters).
The keys and values **{companyName}** supports are as follows:

| Key                  | Required | Value                                                                                                                                                                                                                                                                                                                                                  |
| :------------------- | :------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `prompt`             | ✅        | The question or instruction of up to 2,047 characters to use as a chat prompt; the prompt requires [form or URL encoding](https://developer.mozilla.org/en-US/docs/Glossary/Percent-encoding) (with any space character being replaced by a `+` character or `%20` sequence)                                                                           |
| `model`              | ⬜        | The AI model to chat with, `chatgpt`, `gemini`, `perplexity`, or `copilot`; `chatgpt` is the default model                                                                                                                                                                                                                                             |
| `device`             | ⬜        | The name as returned by the [devices resource](#device-emulation) of the device to emulate chatting on (these names are case insensitive but must include form- or URL-encoded spaces and punctuation marks); device emulation is unused by default                                                                                                    |
| `language` (planned) | ⬜        | The commonly spelled name or [two-letter ISO code](https://www.loc.gov/standards/iso639-2/php/code_list.php) of the language to chat in (these names and codes are case insensitive but required to include form- or URL-encoded spaces and punctuation marks); the language is unset by default                                                       |
| `display` (planned)  | ⬜        | The commonly spelled name or [two-letter ISO code](https://www.loc.gov/standards/iso639-2/php/code_list.php) of the chat interface's display language (these names and codes are case insensitive but required to include form- or URL-encoded spaces and punctuation marks); the display language is unset by default or set to the language if given |
| `format`             | ⬜        | The format to output to, `json`, `rendered`, or `raw` (see the [section below](#response-format)); `json` is the default format                                                                                                                                                                                                                        |
| `expiration`         | ⬜        | The age in days of when to consider a cached completion expired, where `0` disables caching; `1` is the default number of days before expiration                                                                                                                                                                                                       |

### Device emulation

The `device` param lets you fetch a device-specific completion, rather than the default desktop
completion. For a list of supported smartphone and tablet devices, make a request with your API
token and no params to **https\://‍{apiEndpoint}/ai/devices**:

```shell theme={null}
curl -H "Authorization: Bearer $MASSIVE_TOKEN" \
'https://render.joinmassive.com/ai/devices'
```

The API will return JSON that contains an alphabetized array of device names:

```json theme={null}
[
  "Blackberry PlayBook",
  "Blackberry PlayBook landscape",
  "BlackBerry Z30",
  "[Remaining device names here]"
]
```

Then, pass your device name of choice into your chat request:

```shell theme={null}
curl -H "Authorization: Bearer $MASSIVE_TOKEN" \
'https://render.joinmassive.com/ai'\
'?prompt=what+happened+to+blackberry'\
'&device=blackberry+playbook'
```

### Response format

Completions are returned as structured JSON, rendered HTML, or raw (unrendered) HTML.

#### JSON

If you set the output to JSON, your completion will be parsed into an object with the
[geotargeting keys and values above](#service-usage) and following chat keys and values:

| Key                  | Value                                                                                                                    |
| :------------------- | :----------------------------------------------------------------------------------------------------------------------- |
| `model`              | The AI model that generated the completion                                                                               |
| `query`              | The user prompt that the completion was generated for                                                                    |
| `html`               | The rendered HTML of the entire conversation                                                                             |
| `prompt`             | The rendered HTML of just the prompt portion of the conversation                                                         |
| `completion`         | The rendered HTML of just the completion portion of the conversation                                                     |
| `sources`            | The rendered HTML of just the sources portion of the conversation                                                        |
| `ads`                | The rendered HTML of just the ads portion of the conversation                                                            |
| `fanouts`            | An array of the fanout queries that the model searched to generate the completion; only some models expose these queries |
| `device`             | The emulated device name that the conversation was had on                                                                |
| `language` (planned) | The common name or ISO code of the language that the conversation is in                                                  |
| `display` (planned)  | The common name or ISO code of the display language that conversation interface is in                                    |

<Accordion icon="code" title="View JSON example">
  ```json theme={null}
  {
    "model": "chatgpt",
    "query": "best basketball shoes for 2026",
    "html": "<!DOCTYPE html><html lang=\"en-US\" ...",
    "prompt": "<h4 class=\"sr-only select-none\">You said: ...",
    "completion": "<h4 class=\"sr-only select-none\">ChatGPT said: ...",
    "sources": "<section aria-label=\"Sources\" ...",
    "ads": "<div class=\"border-token-border-default mt-2 border-t py-4 text-sm\" ...",
    "fanouts": ["best basketball shoes for 2026"],
    "country": "US",
    "city": "Portland"
  }
  ```
</Accordion>

#### HTML

HTML is available after processing by rendering and JavaScript engines or in the raw form sent by
the chatbot.

## Additional examples

### Cachebusting

```shell theme={null}
curl -H "Authorization: Bearer $MASSIVE_TOKEN" \
'https://render.joinmassive.com/ai'\
'?prompt=current+weather'\
'&expiration=0'
```