> ## Documentation Index
> Fetch the complete documentation index at: https://doc.agentfirst.dev/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 minute.
    </Warning>;
};

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

export const apiEndpoint = 'api.agentfirst.dev';

export const companyName = 'Agent First';

<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 $AGENT_FIRST_TOKEN" \
'https://api.agentfirst.dev/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` (planned) (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                                                                                                                                                                                                       |
| `callback`           | ⬜        | The encoded HTTP or HTTPS callback URL or Amazon SQS queue URL or ARN of up to 2,047 characters to notify when the (prerequisite) asynchronous completion has been retrieved; any SQS queue must grant `sqs:SendMessage` permission to the `arn:aws:iam::180363035301:role/api-instance` AWS principal                                                 |

### 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 $AGENT_FIRST_TOKEN" \
'https://api.agentfirst.dev/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 $AGENT_FIRST_TOKEN" \
'https://api.agentfirst.dev/ai'\
'?prompt=What+happened+to+blackberry%3F'\
'&device=Blackberry+PlayBook'
```

### Response format

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

#### 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, if any, of the conversation                                               |
| `ads`                    | The rendered HTML of just the ads portion, if any, of the conversation                                                   |
| `sse` (ChatGPT only)     | The server-sent events JSON that was used to populate the conversation HTML                                              |
| `fanouts` (ChatGPT only) | 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\" ...",
    "sse": "{\"type\": \"conversation_detail_metadata\" ...",
    "fanouts": [
      "best basketball shoes 2026",
      "top rated basketball shoes 2026 reviews",
      "best performance basketball shoes 2026",
      "best basketball shoes for guards 2026",
      "best basketball shoes for wide feet 2026",
      "best outdoor basketball shoes 2026",
      "most popular basketball shoes 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 (planned).

## Additional examples

### Cachebusting

```shell theme={null}
curl -H "Authorization: Bearer $AGENT_FIRST_TOKEN" \
'https://api.agentfirst.dev/ai'\
'?prompt=Show+the+current+weather.'\
'&expiration=0'
```