API reference
Sam AI
Sam AI writes your replies in campaign conversations. It reads instructions and files on three levels, the X account for your business, the persona for how to sell to that type of buyer, and the conversation for this one lead. When two levels disagree, the most precise wins.
A conversation runs in one of three modes. off leaves it to you. draft is Semi-auto, Sam AI writes a suggestion and you send it. auto lets Sam AI send its replies from your X account on its own. A persona sets the mode of its conversations, and a conversation can set its own or inherit its persona's.
Sam AI works on the Business and Enterprise plans, in live campaigns only. Below Business it writes nothing, in draft as in auto. A reply of Sam AI uses 30 credits when it goes out, however many messages it holds. A suggestion you never send is free, but Sam AI writes one only while the balance covers a reply. New suggestions, the replies Sam AI sends and its handoffs also arrive as the sam.suggestion.ready, sam.reply.sent and sam.handoff webhooks.
- GET/v1/
account/ sam - PATCH/v1/
account/ sam - GET/v1/
personas/ :persona_id/ sam - PATCH/v1/
personas/ :persona_id/ sam - GET/v1/
conversations/ :conversation_id/ sam - PATCH/v1/
conversations/ :conversation_id/ sam - POST/v1/
account/ sam/ files - DELETE/v1/
account/ sam/ files/ :file_id - POST/v1/
personas/ :persona_id/ sam/ files - DELETE/v1/
personas/ :persona_id/ sam/ files/ :file_id - POST/v1/
conversations/ :conversation_id/ sam/ files - DELETE/v1/
conversations/ :conversation_id/ sam/ files/ :file_id
The account Sam AI object
Sam AI on the whole X account, its switch and what it knows about your business.
Attributes
- objectstringAlways
account_sam. - account_idstringThe X account's ID, as in the account object.
- enabledboolean
falsewhen Sam AI is off in every conversation of the X account, whatever their mode. - instructionsstringWhat your business is, read in every conversation, like your offer, your prices, your guarantee and your links. Up to 3 000 characters.
- filesarray of objectsThe files Sam AI reads in every conversation, as Sam AI file objects.
{
"object": "account_sam",
"account_id": "a9PzK2vRtM",
"enabled": true,
"instructions": "Acme lets creators charge for their Discord. 5 percent a sale, no monthly fee, payouts every week. Sign up at https://acme.com/start.",
"files": [
{
"id": "sf_4c1e9a07d2b35f68e190",
"object": "sam_file",
"name": "Pricing and payouts.pdf",
"size": 182344,
"mime_type": "application/pdf",
"url": "https://upcdn.io/W142hYH/raw/uploads/GemleadSamFiles/api/7f3a9c21e5b04d18/Pricing-and-payouts.pdf"
}
]
}Retrieve the account's Sam AI
Returns whether Sam AI is on for the X account, its business info and its files.
Returns
curl https://gemlead.ai/api/v1/account/sam \
-H "Authorization: Bearer $GEMLEAD_API_KEY"{
"object": "account_sam",
"account_id": "a9PzK2vRtM",
"enabled": true,
"instructions": "Acme lets creators charge for their Discord. 5 percent a sale, no monthly fee, payouts every week. Sign up at https://acme.com/start.",
"files": [
{
"id": "sf_4c1e9a07d2b35f68e190",
"object": "sam_file",
"name": "Pricing and payouts.pdf",
"size": 182344,
"mime_type": "application/pdf",
"url": "https://upcdn.io/W142hYH/raw/uploads/GemleadSamFiles/api/7f3a9c21e5b04d18/Pricing-and-payouts.pdf"
}
]
}Update the account's Sam AI
Turns Sam AI on or off for the whole X account, or changes the business info every conversation reads. Only the fields you send change.
Body parameters
- enabledboolean
falseturns Sam AI off in every conversation of the X account,trueturns it back on. - instructionsstringWhat your business is, up to 3 000 characters. An empty string clears it.
Returns
The updated account Sam AI object.
Errors
- A parameter has a value the API does not accept.
paramnames it. - The body has a field this endpoint does not take.
- 403forbiddenA team member's key changes a zone their role can only view. The X account's switch and the conversations are in the chat zone, its business info and files in settings, a persona's Sam AI in personas.
curl -X PATCH https://gemlead.ai/api/v1/account/sam \
-H "Authorization: Bearer $GEMLEAD_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"instructions": "Acme lets creators charge for their Discord. 5 percent a sale, no monthly fee, payouts every week. Sign up at https://acme.com/start."
}'{
"object": "account_sam",
"account_id": "a9PzK2vRtM",
"enabled": true,
"instructions": "Acme lets creators charge for their Discord. 5 percent a sale, no monthly fee, payouts every week. Sign up at https://acme.com/start.",
"files": [
{
"id": "sf_4c1e9a07d2b35f68e190",
"object": "sam_file",
"name": "Pricing and payouts.pdf",
"size": 182344,
"mime_type": "application/pdf",
"url": "https://upcdn.io/W142hYH/raw/uploads/GemleadSamFiles/api/7f3a9c21e5b04d18/Pricing-and-payouts.pdf"
}
]
}The persona Sam AI object
Sam AI on a persona, for the conversations with its leads.
Attributes
- objectstringAlways
persona_sam. - persona_idstringThe persona's ID.
- modestringThe mode of the persona's conversations that have none of their own.
offleaves them to you,draftis Semi-auto where Sam AI suggests and you send,autolets Sam AI send on its own.draftuntil you change it.offdraftauto - instructionsstringHow to write and sell to this type of buyer, the persona's Instructions in the app. Up to 6 000 characters.
- filesarray of objectsThe files Sam AI reads in the persona's conversations, as Sam AI file objects.
{
"object": "persona_sam",
"persona_id": "lvWBPnytpS",
"mode": "draft",
"instructions": "Tipsters want to get paid on time. Lead with the weekly payouts, keep it to two short messages, and offer the link once they ask how.",
"files": []
}Retrieve a persona's Sam AI
Returns Sam AI's mode for the persona's conversations, its instructions and its files.
Path parameters
- persona_idstringRequiredThe persona's ID.
Returns
Errors
- No persona with this ID on the key's account.
curl https://gemlead.ai/api/v1/personas/lvWBPnytpS/sam \
-H "Authorization: Bearer $GEMLEAD_API_KEY"{
"object": "persona_sam",
"persona_id": "lvWBPnytpS",
"mode": "draft",
"instructions": "Tipsters want to get paid on time. Lead with the weekly payouts, keep it to two short messages, and offer the link once they ask how.",
"files": []
}Update a persona's Sam AI
Changes Sam AI's mode in the persona's conversations, those that have no mode of their own, or the persona's instructions. Only the fields you send change. auto sends replies from your X account on their own.
Path parameters
- persona_idstringRequiredThe persona's ID.
Body parameters
- modestringSam AI's mode in the persona's conversations.
offdraftauto - instructionsstringHow to write and sell to this type of buyer, up to 6 000 characters. An empty string clears it.
Returns
The updated persona Sam AI object.
Errors
- No persona with this ID on the key's account.
- A parameter has a value the API does not accept.
paramnames it. - The body has a field this endpoint does not take.
autoon an account below the Business plan.- 403forbiddenA team member's key changes a zone their role can only view. The X account's switch and the conversations are in the chat zone, its business info and files in settings, a persona's Sam AI in personas.
curl -X PATCH \
https://gemlead.ai/api/v1/personas/lvWBPnytpS/sam \
-H "Authorization: Bearer $GEMLEAD_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"mode": "draft"
}'{
"object": "persona_sam",
"persona_id": "lvWBPnytpS",
"mode": "draft",
"instructions": "Tipsters want to get paid on time. Lead with the weekly payouts, keep it to two short messages, and offer the link once they ask how.",
"files": []
}The conversation Sam AI object
Sam AI in one conversation, its mode, the reply it has ready and what it knows about this lead.
Attributes
- objectstringAlways
conversation_sam. - conversation_idstringThe conversation's ID.
- modestringThe conversation's own mode, or
inheritwhen it follows its persona's.offdraftautoinherit - effective_modestringThe mode that runs.
offwhen Sam AI is off on the X account, the conversation is in no live campaign or the account is below the Business plan.offdraftauto - personaobject or nullThe persona Sam AI reads, with its
id,nameandmode. - campaignobject or nullThe campaign the conversation runs in, with its
idandname. Sam AI answers in a live campaign only. - statusstringWhat Sam AI is doing.
writinga reply,suggestedwhen one waits for you,scheduledwhen it goes out on its own atsuggestion.send_at,sending,sent,no_replywhen it chose not to answer,handoffwhen it hands the conversation to you,no_creditswhen the balance is under the 30 credits of a reply,offoridle.idlewritingsuggestedscheduledsendingsentno_replyhandoffno_creditsoff - reasonstring or nullWhy, for
no_replyandhandoff, as Sam AI wrote it. - suggestionobject or nullThe reply Sam AI has ready, while
statusissuggested,scheduledorsending. - instructionsstringWhat Sam AI should know about this one lead. Up to 3 000 characters.
- filesarray of objectsThe files Sam AI reads in this conversation only, as Sam AI file objects.
- updated_atstring or nullWhen Sam AI's state last changed, ISO 8601.
{
"object": "conversation_sam",
"conversation_id": "msgOtJ8dvT",
"mode": "inherit",
"effective_mode": "draft",
"persona": {
"id": "lvWBPnytpS",
"name": "Tipsters",
"mode": "draft"
},
"campaign": {
"id": "c7RkQ2wLxe",
"name": "Tipsters warm intro"
},
"status": "suggested",
"reason": null,
"suggestion": {
"messages": [
"It takes two minutes. You set a price, members pay, and they get their Discord role right away.",
"Want the link to set it up?"
],
"edited": false,
"stage": "answer_question",
"why": "She asked how it works, so the reply explains it in one line and offers the link.",
"replying_to_message_id": "1985321409876543210",
"created_at": "2026-11-06T08:13:20.000Z",
"send_at": null
},
"instructions": "She runs two Discords. Talk about the bigger one first.",
"files": [],
"updated_at": "2026-11-06T08:13:20.000Z"
}Retrieve a conversation's Sam AI
Returns Sam AI's mode in the conversation and the one that runs, the reply it has ready, and the conversation's own instructions and files.
Path parameters
- conversation_idstringRequiredThe conversation's ID.
Returns
The conversation Sam AI object.
Errors
- No conversation with this ID on the key's account.
curl https://gemlead.ai/api/v1/conversations/msgOtJ8dvT/sam \
-H "Authorization: Bearer $GEMLEAD_API_KEY"{
"object": "conversation_sam",
"conversation_id": "msgOtJ8dvT",
"mode": "inherit",
"effective_mode": "draft",
"persona": {
"id": "lvWBPnytpS",
"name": "Tipsters",
"mode": "draft"
},
"campaign": {
"id": "c7RkQ2wLxe",
"name": "Tipsters warm intro"
},
"status": "suggested",
"reason": null,
"suggestion": {
"messages": [
"It takes two minutes. You set a price, members pay, and they get their Discord role right away.",
"Want the link to set it up?"
],
"edited": false,
"stage": "answer_question",
"why": "She asked how it works, so the reply explains it in one line and offers the link.",
"replying_to_message_id": "1985321409876543210",
"created_at": "2026-11-06T08:13:20.000Z",
"send_at": null
},
"instructions": "She runs two Discords. Talk about the bigger one first.",
"files": [],
"updated_at": "2026-11-06T08:13:20.000Z"
}Update a conversation's Sam AI
Sets Sam AI's mode in this one conversation, or gives it back to its persona with inherit, or changes what Sam AI knows about this lead. Only the fields you send change. auto sends replies from your X account on their own.
Path parameters
- conversation_idstringRequiredThe conversation's ID.
Body parameters
- modestringSam AI's mode here.
inheritfollows the persona's.offdraftautoinherit - instructionsstringWhat Sam AI should know about this lead, up to 3 000 characters. An empty string clears it.
Returns
The updated conversation Sam AI object.
Errors
- No conversation with this ID on the key's account.
- A parameter has a value the API does not accept.
paramnames it. - The body has a field this endpoint does not take.
autoon an account below the Business plan.- 403forbiddenA team member's key changes a zone their role can only view. The X account's switch and the conversations are in the chat zone, its business info and files in settings, a persona's Sam AI in personas.
curl -X PATCH \
https://gemlead.ai/api/v1/conversations/msgOtJ8dvT/sam \
-H "Authorization: Bearer $GEMLEAD_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"mode": "auto"
}'{
"object": "conversation_sam",
"conversation_id": "msgOtJ8dvT",
"mode": "auto",
"effective_mode": "auto",
"persona": {
"id": "lvWBPnytpS",
"name": "Tipsters",
"mode": "draft"
},
"campaign": {
"id": "c7RkQ2wLxe",
"name": "Tipsters warm intro"
},
"status": "scheduled",
"reason": null,
"suggestion": {
"messages": [
"It takes two minutes. You set a price, members pay, and they get their Discord role right away.",
"Want the link to set it up?"
],
"edited": false,
"stage": "answer_question",
"why": "She asked how it works, so the reply explains it in one line and offers the link.",
"replying_to_message_id": "1985321409876543210",
"created_at": "2026-11-06T08:13:20.000Z",
"send_at": "2026-11-06T08:14:05.000Z"
},
"instructions": "She runs two Discords. Talk about the bigger one first.",
"files": [],
"updated_at": "2026-11-06T08:13:20.000Z"
}The Sam AI file object
A document Sam AI reads before each reply, a PDF, DOCX, TXT, MD or CSV file. Each level holds 30 files and 100 MB at most.
Attributes
- idstringUnique identifier for the file on its level.
- objectstringAlways
sam_file. - namestringThe file's name, as the app shows it.
- sizeintegerIts size in bytes.
- mime_typestring or nullIts type, like
application/pdf. - urlstringWhere Gemlead keeps it.
{
"id": "sf_4c1e9a07d2b35f68e190",
"object": "sam_file",
"name": "Pricing and payouts.pdf",
"size": 182344,
"mime_type": "application/pdf",
"url": "https://upcdn.io/W142hYH/raw/uploads/GemleadSamFiles/api/7f3a9c21e5b04d18/Pricing-and-payouts.pdf"
}Add a file to the account
Gives Sam AI a document to read in every conversation of the X account. Send its public URL or its bytes in base64. Gemlead reads it once, checks it is a PDF, DOCX, TXT, MD or CSV file and keeps its own copy.
Body parameters
- urlstringThe file at a public HTTPS URL. Gemlead reads it once and keeps its own copy. Give
urlordata. - datastringThe file, base64 encoded, instead of
url. Send a large file asurl. - namestringThe name the app shows, up to 200 characters. Required with
data, else the URL's last part. Gemlead adds the extension when it is missing.
Returns
The new Sam AI file object.
Errors
- A required parameter is missing.
paramnames it. - The file is not a PDF, DOCX, TXT, MD or CSV file, is empty or larger than 25 MB, or its URL cannot be read.
paramnames it. - The body has a field this endpoint does not take.
- The level holds 30 files or 100 MB of files already. Delete one first.
- More than 100 files in the hour on this X account.
- 403forbiddenA team member's key changes a zone their role can only view. The X account's switch and the conversations are in the chat zone, its business info and files in settings, a persona's Sam AI in personas.
curl -X POST https://gemlead.ai/api/v1/account/sam/files \
-H "Authorization: Bearer $GEMLEAD_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"url": "https://acme.com/docs/pricing-and-payouts.pdf",
"name": "Pricing and payouts.pdf"
}'{
"id": "sf_4c1e9a07d2b35f68e190",
"object": "sam_file",
"name": "Pricing and payouts.pdf",
"size": 182344,
"mime_type": "application/pdf",
"url": "https://upcdn.io/W142hYH/raw/uploads/GemleadSamFiles/api/7f3a9c21e5b04d18/Pricing-and-payouts.pdf"
}Delete a file of the account
Takes a file off the level. Sam AI stops reading it from its next reply.
Path parameters
- file_idstringRequiredThe Sam AI file's ID.
Returns
An object with the file's id and deleted set to true.
Errors
- No Sam AI file with this ID on the key's account.
- 403forbiddenA team member's key changes a zone their role can only view. The X account's switch and the conversations are in the chat zone, its business info and files in settings, a persona's Sam AI in personas.
curl -X DELETE \
https://gemlead.ai/api/v1/account/sam/files/sf_4c1e9a07d2b35f68e190 \
-H "Authorization: Bearer $GEMLEAD_API_KEY"{
"id": "sf_4c1e9a07d2b35f68e190",
"object": "sam_file",
"deleted": true
}Add a file to a persona
Gives Sam AI a document to read in the persona's conversations. Send its public URL or its bytes in base64. Gemlead reads it once, checks it is a PDF, DOCX, TXT, MD or CSV file and keeps its own copy.
Path parameters
- persona_idstringRequiredThe persona's ID.
Body parameters
- urlstringThe file at a public HTTPS URL. Gemlead reads it once and keeps its own copy. Give
urlordata. - datastringThe file, base64 encoded, instead of
url. Send a large file asurl. - namestringThe name the app shows, up to 200 characters. Required with
data, else the URL's last part. Gemlead adds the extension when it is missing.
Returns
The new Sam AI file object.
Errors
- No persona with this ID on the key's account.
- A required parameter is missing.
paramnames it. - The file is not a PDF, DOCX, TXT, MD or CSV file, is empty or larger than 25 MB, or its URL cannot be read.
paramnames it. - The body has a field this endpoint does not take.
- The level holds 30 files or 100 MB of files already. Delete one first.
- More than 100 files in the hour on this X account.
- 403forbiddenA team member's key changes a zone their role can only view. The X account's switch and the conversations are in the chat zone, its business info and files in settings, a persona's Sam AI in personas.
curl -X POST \
https://gemlead.ai/api/v1/personas/lvWBPnytpS/sam/files \
-H "Authorization: Bearer $GEMLEAD_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"url": "https://acme.com/docs/pricing-and-payouts.pdf",
"name": "Pricing and payouts.pdf"
}'{
"id": "sf_4c1e9a07d2b35f68e190",
"object": "sam_file",
"name": "Pricing and payouts.pdf",
"size": 182344,
"mime_type": "application/pdf",
"url": "https://upcdn.io/W142hYH/raw/uploads/GemleadSamFiles/api/7f3a9c21e5b04d18/Pricing-and-payouts.pdf"
}Delete a file of a persona
Takes a file off the level. Sam AI stops reading it from its next reply.
Path parameters
- persona_idstringRequiredThe persona's ID.
- file_idstringRequiredThe Sam AI file's ID.
Returns
An object with the file's id and deleted set to true.
Errors
- No Sam AI file with this ID on the key's account.
- 403forbiddenA team member's key changes a zone their role can only view. The X account's switch and the conversations are in the chat zone, its business info and files in settings, a persona's Sam AI in personas.
curl -X DELETE \
https://gemlead.ai/api/v1/personas/lvWBPnytpS/sam/files/sf_4c1e9a07d2b35f68e190 \
-H "Authorization: Bearer $GEMLEAD_API_KEY"{
"id": "sf_4c1e9a07d2b35f68e190",
"object": "sam_file",
"deleted": true
}Add a file to a conversation
Gives Sam AI a document about this one lead. Send its public URL or its bytes in base64. Gemlead reads it once, checks it is a PDF, DOCX, TXT, MD or CSV file and keeps its own copy.
Path parameters
- conversation_idstringRequiredThe conversation's ID.
Body parameters
- urlstringThe file at a public HTTPS URL. Gemlead reads it once and keeps its own copy. Give
urlordata. - datastringThe file, base64 encoded, instead of
url. Send a large file asurl. - namestringThe name the app shows, up to 200 characters. Required with
data, else the URL's last part. Gemlead adds the extension when it is missing.
Returns
The new Sam AI file object.
Errors
- No conversation with this ID on the key's account.
- A required parameter is missing.
paramnames it. - The file is not a PDF, DOCX, TXT, MD or CSV file, is empty or larger than 25 MB, or its URL cannot be read.
paramnames it. - The body has a field this endpoint does not take.
- The level holds 30 files or 100 MB of files already. Delete one first.
- More than 100 files in the hour on this X account.
- 403forbiddenA team member's key changes a zone their role can only view. The X account's switch and the conversations are in the chat zone, its business info and files in settings, a persona's Sam AI in personas.
curl -X POST \
https://gemlead.ai/api/v1/conversations/msgOtJ8dvT/sam/files \
-H "Authorization: Bearer $GEMLEAD_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"url": "https://acme.com/docs/pricing-and-payouts.pdf",
"name": "Pricing and payouts.pdf"
}'{
"id": "sf_4c1e9a07d2b35f68e190",
"object": "sam_file",
"name": "Pricing and payouts.pdf",
"size": 182344,
"mime_type": "application/pdf",
"url": "https://upcdn.io/W142hYH/raw/uploads/GemleadSamFiles/api/7f3a9c21e5b04d18/Pricing-and-payouts.pdf"
}Delete a file of a conversation
Takes a file off the level. Sam AI stops reading it from its next reply.
Path parameters
- conversation_idstringRequiredThe conversation's ID.
- file_idstringRequiredThe Sam AI file's ID.
Returns
An object with the file's id and deleted set to true.
Errors
- No Sam AI file with this ID on the key's account.
- 403forbiddenA team member's key changes a zone their role can only view. The X account's switch and the conversations are in the chat zone, its business info and files in settings, a persona's Sam AI in personas.
curl -X DELETE \
https://gemlead.ai/api/v1/conversations/msgOtJ8dvT/sam/files/sf_4c1e9a07d2b35f68e190 \
-H "Authorization: Bearer $GEMLEAD_API_KEY"{
"id": "sf_4c1e9a07d2b35f68e190",
"object": "sam_file",
"deleted": true
}