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.

The account Sam AI object

Sam AI on the whole X account, its switch and what it knows about your business.

Attributes

  • objectstring
    Always account_sam.
  • account_idstring
    The X account's ID, as in the account object.
  • enabledboolean
    false when Sam AI is off in every conversation of the X account, whatever their mode.
  • instructionsstring
    What your business is, read in every conversation, like your offer, your prices, your guarantee and your links. Up to 3 000 characters.
  • filesarray of objects
    The files Sam AI reads in every conversation, as Sam AI file objects.
Account Sam AI object
{
  "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

GET/v1/account/samread scopeMCPget_sam_settings

Returns whether Sam AI is on for the X account, its business info and its files.

Returns

The account Sam AI object.

GET/v1/account/sam
curl https://gemlead.ai/api/v1/account/sam \
  -H "Authorization: Bearer $GEMLEAD_API_KEY"
Response200
{
  "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

PATCH/v1/account/samwrite scopeMCPupdate_sam_settings

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
    false turns Sam AI off in every conversation of the X account, true turns it back on.
  • instructionsstring
    What 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. param names it.
  • The body has a field this endpoint does not take.
  • A 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.
PATCH/v1/account/sam
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."
  }'
Response200
{
  "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

  • objectstring
    Always persona_sam.
  • persona_idstring
    The persona's ID.
  • modestring
    The mode of the persona's conversations that have none of their own. off leaves them to you, draft is Semi-auto where Sam AI suggests and you send, auto lets Sam AI send on its own. draft until you change it.
    offdraftauto
  • instructionsstring
    How to write and sell to this type of buyer, the persona's Instructions in the app. Up to 6 000 characters.
  • filesarray of objects
    The files Sam AI reads in the persona's conversations, as Sam AI file objects.
Persona Sam AI object
{
  "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

GET/v1/personas/:persona_id/samread scopeMCPget_sam_settings

Returns Sam AI's mode for the persona's conversations, its instructions and its files.

Path parameters

  • persona_idstringRequired
    The persona's ID.

Returns

The persona Sam AI object.

Errors

GET/v1/personas/:persona_id/sam
curl https://gemlead.ai/api/v1/personas/lvWBPnytpS/sam \
  -H "Authorization: Bearer $GEMLEAD_API_KEY"
Response200
{
  "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

PATCH/v1/personas/:persona_id/samwrite scopeMCPupdate_sam_settings

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_idstringRequired
    The persona's ID.

Body parameters

  • modestring
    Sam AI's mode in the persona's conversations.
    offdraftauto
  • instructionsstring
    How 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. param names it.
  • The body has a field this endpoint does not take.
  • auto on an account below the Business plan.
  • A 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.
PATCH/v1/personas/:persona_id/sam
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"
  }'
Response200
{
  "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

  • objectstring
    Always conversation_sam.
  • conversation_idstring
    The conversation's ID.
  • modestring
    The conversation's own mode, or inherit when it follows its persona's.
    offdraftautoinherit
  • effective_modestring
    The mode that runs. off when 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 null
    The persona Sam AI reads, with its id, name and mode.
  • campaignobject or null
    The campaign the conversation runs in, with its id and name. Sam AI answers in a live campaign only.
  • statusstring
    What Sam AI is doing. writing a reply, suggested when one waits for you, scheduled when it goes out on its own at suggestion.send_at, sending, sent, no_reply when it chose not to answer, handoff when it hands the conversation to you, no_credits when the balance is under the 30 credits of a reply, off or idle.
    idlewritingsuggestedscheduledsendingsentno_replyhandoffno_creditsoff
  • reasonstring or null
    Why, for no_reply and handoff, as Sam AI wrote it.
  • suggestionobject or null
    The reply Sam AI has ready, while status is suggested, scheduled or sending.
  • instructionsstring
    What Sam AI should know about this one lead. Up to 3 000 characters.
  • filesarray of objects
    The files Sam AI reads in this conversation only, as Sam AI file objects.
  • updated_atstring or null
    When Sam AI's state last changed, ISO 8601.
Conversation Sam AI object
{
  "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

GET/v1/conversations/:conversation_id/samread scopeMCPget_sam_settings

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_idstringRequired
    The conversation's ID.

Returns

The conversation Sam AI object.

Errors

GET/v1/conversations/:conversation_id/sam
curl https://gemlead.ai/api/v1/conversations/msgOtJ8dvT/sam \
  -H "Authorization: Bearer $GEMLEAD_API_KEY"
Response200
{
  "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

PATCH/v1/conversations/:conversation_id/samwrite scopeMCPupdate_sam_settings

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_idstringRequired
    The conversation's ID.

Body parameters

  • modestring
    Sam AI's mode here. inherit follows the persona's.
    offdraftautoinherit
  • instructionsstring
    What 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. param names it.
  • The body has a field this endpoint does not take.
  • auto on an account below the Business plan.
  • A 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.
PATCH/v1/conversations/:conversation_id/sam
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"
  }'
Response200
{
  "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

  • idstring
    Unique identifier for the file on its level.
  • objectstring
    Always sam_file.
  • namestring
    The file's name, as the app shows it.
  • sizeinteger
    Its size in bytes.
  • mime_typestring or null
    Its type, like application/pdf.
  • urlstring
    Where Gemlead keeps it.
Sam AI file object
{
  "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

POST/v1/account/sam/fileswrite scopeMCPedit_sam_files

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

  • urlstring
    The file at a public HTTPS URL. Gemlead reads it once and keeps its own copy. Give url or data.
  • datastring
    The file, base64 encoded, instead of url. Send a large file as url.
  • namestring
    The 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. param names 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. param names 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.
  • A 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.
POST/v1/account/sam/files
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"
  }'
Response200
{
  "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

DELETE/v1/account/sam/files/:file_idwrite scopeMCPedit_sam_files

Takes a file off the level. Sam AI stops reading it from its next reply.

Path parameters

  • file_idstringRequired
    The 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.
  • A 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.
DELETE/v1/account/sam/files/:file_id
curl -X DELETE \
  https://gemlead.ai/api/v1/account/sam/files/sf_4c1e9a07d2b35f68e190 \
  -H "Authorization: Bearer $GEMLEAD_API_KEY"
Response200
{
  "id": "sf_4c1e9a07d2b35f68e190",
  "object": "sam_file",
  "deleted": true
}

Add a file to a persona

POST/v1/personas/:persona_id/sam/fileswrite scopeMCPedit_sam_files

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_idstringRequired
    The persona's ID.

Body parameters

  • urlstring
    The file at a public HTTPS URL. Gemlead reads it once and keeps its own copy. Give url or data.
  • datastring
    The file, base64 encoded, instead of url. Send a large file as url.
  • namestring
    The 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. param names 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. param names 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.
  • A 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.
POST/v1/personas/:persona_id/sam/files
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"
  }'
Response200
{
  "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

DELETE/v1/personas/:persona_id/sam/files/:file_idwrite scopeMCPedit_sam_files

Takes a file off the level. Sam AI stops reading it from its next reply.

Path parameters

  • persona_idstringRequired
    The persona's ID.
  • file_idstringRequired
    The 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.
  • A 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.
DELETE/v1/personas/:persona_id/sam/files/:file_id
curl -X DELETE \
  https://gemlead.ai/api/v1/personas/lvWBPnytpS/sam/files/sf_4c1e9a07d2b35f68e190 \
  -H "Authorization: Bearer $GEMLEAD_API_KEY"
Response200
{
  "id": "sf_4c1e9a07d2b35f68e190",
  "object": "sam_file",
  "deleted": true
}

Add a file to a conversation

POST/v1/conversations/:conversation_id/sam/fileswrite scopeMCPedit_sam_files

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_idstringRequired
    The conversation's ID.

Body parameters

  • urlstring
    The file at a public HTTPS URL. Gemlead reads it once and keeps its own copy. Give url or data.
  • datastring
    The file, base64 encoded, instead of url. Send a large file as url.
  • namestring
    The 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. param names 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. param names 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.
  • A 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.
POST/v1/conversations/:conversation_id/sam/files
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"
  }'
Response200
{
  "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

DELETE/v1/conversations/:conversation_id/sam/files/:file_idwrite scopeMCPedit_sam_files

Takes a file off the level. Sam AI stops reading it from its next reply.

Path parameters

  • conversation_idstringRequired
    The conversation's ID.
  • file_idstringRequired
    The 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.
  • A 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.
DELETE/v1/conversations/:conversation_id/sam/files/:file_id
curl -X DELETE \
  https://gemlead.ai/api/v1/conversations/msgOtJ8dvT/sam/files/sf_4c1e9a07d2b35f68e190 \
  -H "Authorization: Bearer $GEMLEAD_API_KEY"
Response200
{
  "id": "sf_4c1e9a07d2b35f68e190",
  "object": "sam_file",
  "deleted": true
}