Skip to main content

​
Service usage

‘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://‍/ai. Conversations can be localized with geotargeting parameters. They’re streamed live by default or optionally queued for subsequent retrieval. 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. Usage data is published regularly.

​
Authentication

You can access the service by including your secret API token in an Authorization header: 
Authorization: Bearer [API token here]
Here’s an example request that uses the common Curl command: 
curl -H "Authorization: Bearer $AGENT_FIRST_TOKEN" \
'https://api.agentfirst.dev/ai'\
'?prompt=best+basketball+shoes+for+2026'\
'&country=us'\
'&city=Portland'

​
Chat parameters

Besides the geotargeting and scheduling parameters linked above, required and optional chat parameters can be added in a standard query string. The keys and values supports are as follows:
KeyRequiredValue
prompt✅The question or instruction of up to 2,047 characters to use as a chat prompt; the prompt requires form or URL encoding (with any space character being replaced by a + character or %20 sequence)
model⬜The AI model to chat with, chatgpt, gemini, perplexity (coming soon), or copilot (coming soon); chatgpt is the default model
device⬜The name as returned by the devices resource 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 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 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); 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://‍/ai/devices: 
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: 
[
  "Blackberry PlayBook",
  "Blackberry PlayBook landscape",
  "BlackBerry Z30",
  "[Remaining device names here]"
]
Then, pass your device name of choice into your chat request: 
curl -H "Authorization: Bearer $AGENT_FIRST_TOKEN" \
'https://api.agentfirst.dev/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 and following chat keys and values:
KeyValue
modelThe AI model that generated the completion
promptThe user prompt that the completion was generated for
htmlThe rendered HTML of the entire conversation
promptHtmlThe rendered HTML of just the prompt portion of the conversation
completionHtmlThe rendered HTML of just the completion portion of the conversation
sourcesHtmlThe rendered HTML of just the sources portion of the conversation
queriesAn array of the fanout queries that the model searched to generate the completion; only some models expose these queries
deviceThe 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
{
  "model": "chatgpt",
  "prompt": "best basketball shoes for 2026",
  "html": "<!DOCTYPE html><html lang=\"en-US\" ...",
  "promptHtml": "<h4 class=\"sr-only select-none\">You said: ...",
  "completionHtml": "<h4 class=\"sr-only select-none\">ChatGPT said: ...",
  "sourcesHtml": "<section aria-label=\"Sources\" ...",
  "fanoutQueries": ["best basketball shoes for 2026"],
  "country": "US",
  "city": "Portland"
}

​
HTML

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

​
Additional examples

​
Cachebusting

curl -H "Authorization: Bearer $AGENT_FIRST_TOKEN" \
'https://api.agentfirst.dev/ai'\
'?prompt=current+weather'\
'&expiration=0'