Skip to main content
POST
/
ai
/
batches
Batch completions
curl --request POST \
  --url https://api.agentfirst.dev/ai/batches \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "prompts": [
    "Where can I buy a vintage guitar?",
    "Help me find guitar repair shops nearby.",
    "Do any local stores sell vinyl records?",
    "[Additional prompts here]"
  ],
  "model": "gemini",
  "device": null,
  "country": null,
  "subdivision": null,
  "city": null,
  "language (planned)": null,
  "display (planned)": null,
  "format": "rendered",
  "expiration": 0,
  "callback (planned)": "https://webhook.site/02e249f8-1faf-4fab-bcf5-78ce683e85a8"
}
'
{
  "id": "a0482596-c2ad-445a-a435-727002156a20",
  "count": 37
}

Authorizations

​
Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json
​
prompts
string[]
required

The questions or instructions to use as chat prompts.

Required array length: 1 - 1000 elements
Maximum string length: 2047
Example:
[
  "Where can I buy a vintage guitar?",
  "Help me find guitar repair shops nearby.",
  "Do any local stores sell vinyl records?",
  "[Additional prompts here]"
]
​
model
enum<string>
default:chatgpt

The AI model to chat with.

Available options:
chatgpt,
gemini,
perplexity,
copilot
Example:

"gemini"

​
device
string

The name as returned by the devices resource [blocked] 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.

Example:

null

​
country
string

The two-letter ISO code of the country to chat from (these codes are case insensitive); a random country is used by default.

Example:

null

​
subdivision
string

The alphanumeric second part (proceeding the separator) of a first-level subdivision code in the (prerequisite) country to chat from (these codes are case insensitive); a random subdivision is used by default.

Example:

null

​
city
string

The commonly spelled name of the city in the (prerequisite) country to chat from (these names are temporarily case sensitive and required to include form- or URL-encoded spaces and punctuation marks); a random city is used by default.

Example:

null

​
language (planned)
string

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.

Example:

null

​
display (planned)
string

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.

Example:

null

​
format
enum<string>
default:json

The format to output to.

Available options:
json,
rendered,
raw (planned)
Example:

"rendered"

​
expiration
integer
default:1

The age in days of when to consider a cached completion expired, where 0 disables caching.

Required range: 0 <= x <= 1
Example:

0

​
callback (planned)
string

The HTTP or HTTPS callback URL or Amazon SQS queue URL or ARN to notify when the batch completions have been retrieved; any SQS queue must grant sqs:SendMessage permission to the arn:aws:iam::180363035301:role/api-instance AWS principal.

Example:

"https://webhook.site/02e249f8-1faf-4fab-bcf5-78ce683e85a8"

Response

A job identifier and confirmation count.

​
id
string<uuid>
required

The identifier to retrieve the batch conversations with.

Example:

"a0482596-c2ad-445a-a435-727002156a20"

​
count
integer
required

The number of prompts in the batch as confirmed by the API.

Required range: 1 <= x <= 1000
Example:

37