Gemlead
Docs
Entrar
Obter sua chave de API

Referência da API

Sam AI

O Sam AI escreve as suas respostas nas conversas de campanha. Ele lê instruções e arquivos em três níveis, a conta do X para o seu negócio, a persona para saber como vender a esse tipo de comprador e a conversa para este lead específico. Quando dois níveis se contradizem, vale o mais específico.

Uma conversa funciona em um de três modos. off deixa a conversa com você. draft é o Semiautomático, o Sam AI escreve uma sugestão e você envia. auto deixa o Sam AI enviar as respostas sozinho pela sua conta do X. Uma persona define o modo das conversas dela, e uma conversa pode ter um modo próprio ou seguir o da persona com inherit.

O Sam AI funciona nos planos Business e Enterprise, e só em campanhas ativas. Abaixo do Business ele não escreve nada, nem em draft nem em auto. Cada resposta do Sam AI usa 30 créditos quando é enviada, não importa quantas mensagens ela tenha. Uma sugestão que você não envia é grátis, mas o Sam AI só escreve uma se o seu saldo cobrir uma resposta. As novas sugestões, as respostas que o Sam AI envia e as conversas que ele passa para você também chegam pelos webhooks sam.suggestion.ready, sam.reply.sent e sam.handoff.

Endpoints

O objeto account Sam AI

O Sam AI na conta do X inteira, o botão para ligá-lo ou desligá-lo e o que ele sabe sobre o seu negócio.

Atributos

  • objectstring
    Sempre account_sam.
  • account_idstring
    O ID da conta do X, como no objeto account.
  • enabledboolean
    false quando o Sam AI está desligado em todas as conversas da conta do X, seja qual for o modo delas.
  • instructionsstring
    O que é o seu negócio, lido em todas as conversas, como a sua oferta, os seus preços, a sua garantia e os seus links. Até 3 000 caracteres.
  • filesarray de objects
    Os arquivos que o Sam AI lê em todas as conversas, como objetos Sam AI file.
O objeto account Sam AI
{
  "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"
    }
  ]
}

Obter o Sam AI da conta

GET/v1/account/samScope readMCPget_sam_settings

Retorna se o Sam AI está ligado na conta do X, as informações do negócio e os arquivos dela.

Retorno

O objeto account Sam AI.

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

Atualizar o Sam AI da conta

PATCH/v1/account/samScope writeMCPupdate_sam_settings

Liga ou desliga o Sam AI na conta do X inteira, ou altera as informações do negócio que todas as conversas leem. Só mudam os campos que você envia.

Parâmetros do corpo

  • enabledboolean
    false desliga o Sam AI em todas as conversas da conta do X, true liga de novo.
  • instructionsstring
    O que é o seu negócio, com até 3 000 caracteres. Uma string vazia apaga o texto.

Retorno

O objeto account Sam AI atualizado.

Erros

  • 400parameter_invalid
    Um parâmetro tem um valor que a API não aceita. param diz qual.
  • 400parameter_unknown
    O corpo tem um campo que este endpoint não aceita.
  • 403forbidden
    A chave de um membro da equipe altera uma área que a função dele só pode ver. O botão que liga o Sam AI na conta do X e as conversas ficam na área de chat, as informações do negócio e os arquivos em configurações, e o Sam AI de uma persona em 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."
  }'
Resposta200
{
  "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"
    }
  ]
}

O objeto persona Sam AI

O Sam AI numa persona, para as conversas com os leads dela.

Atributos

  • objectstring
    Sempre persona_sam.
  • persona_idstring
    O ID da persona.
  • modestring
    O modo das conversas da persona que não têm um modo próprio. off deixa as conversas com você, draft é o Semiautomático, em que o Sam AI sugere e você envia, e auto deixa o Sam AI enviar sozinho. Fica em draft até você mudar.
    offdraftauto
  • instructionsstring
    Como escrever e vender para esse tipo de comprador, as Instruções da persona no app. Até 6 000 caracteres.
  • filesarray de objects
    Os arquivos que o Sam AI lê nas conversas da persona, como objetos Sam AI file.
O objeto persona Sam AI
{
  "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": []
}

Obter o Sam AI de uma persona

GET/v1/personas/:persona_id/samScope readMCPget_sam_settings

Retorna o modo do Sam AI nas conversas da persona, as instruções e os arquivos dela.

Parâmetros de caminho

  • persona_idstringObrigatório
    O ID da persona.

Retorno

O objeto persona Sam AI.

Erros

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

Atualizar o Sam AI de uma persona

PATCH/v1/personas/:persona_id/samScope writeMCPupdate_sam_settings

Altera o modo do Sam AI nas conversas da persona que não têm modo próprio, ou as instruções da persona. Só mudam os campos que você envia. Com auto, as respostas saem sozinhas pela sua conta do X.

Parâmetros de caminho

  • persona_idstringObrigatório
    O ID da persona.

Parâmetros do corpo

  • modestring
    O modo do Sam AI nas conversas da persona.
    offdraftauto
  • instructionsstring
    Como escrever e vender para esse tipo de comprador, com até 6 000 caracteres. Uma string vazia apaga o texto.

Retorno

O objeto persona Sam AI atualizado.

Erros

  • 404resource_missing
    Nenhuma persona com este ID na conta da chave.
  • 400parameter_invalid
    Um parâmetro tem um valor que a API não aceita. param diz qual.
  • 400parameter_unknown
    O corpo tem um campo que este endpoint não aceita.
  • 403plan_required
    auto numa conta com plano abaixo do Business.
  • 403forbidden
    A chave de um membro da equipe altera uma área que a função dele só pode ver. O botão que liga o Sam AI na conta do X e as conversas ficam na área de chat, as informações do negócio e os arquivos em configurações, e o Sam AI de uma persona em 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"
  }'
Resposta200
{
  "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": []
}

O objeto conversation Sam AI

O Sam AI numa conversa, o modo dele, a resposta que ele tem pronta e o que ele sabe sobre este lead.

Atributos

  • objectstring
    Sempre conversation_sam.
  • conversation_idstring
    O ID da conversa.
  • modestring
    O modo próprio da conversa, ou inherit quando ela segue o da persona.
    offdraftautoinherit
  • effective_modestring
    O modo que está valendo de fato. off quando o Sam AI está desligado na conta do X, a conversa não está em nenhuma campanha ativa ou a conta está num plano abaixo do Business.
    offdraftauto
  • personaobject ou null
    A persona que o Sam AI lê, com id, name e mode.
  • campaignobject ou null
    A campanha em que a conversa acontece, com id e name. O Sam AI só responde numa campanha ativa.
  • statusstring
    O que o Sam AI está fazendo. writing quando ele escreve uma resposta, suggested quando uma resposta espera por você, scheduled quando ela sai sozinha em suggestion.send_at, sending, sent, no_reply quando ele decidiu não responder, handoff quando ele passa a conversa para você, no_credits quando o saldo está abaixo dos 30 créditos de uma resposta, off ou idle.
    idlewritingsuggestedscheduledsendingsentno_replyhandoffno_creditsoff
  • reasonstring ou null
    O motivo, para no_reply e handoff, nas palavras do Sam AI.
  • suggestionobject ou null
    A resposta que o Sam AI tem pronta, enquanto status está em suggested, scheduled ou sending.
  • instructionsstring
    O que o Sam AI precisa saber sobre este lead específico. Até 3 000 caracteres.
  • filesarray de objects
    Os arquivos que o Sam AI lê só nesta conversa, como objetos Sam AI file.
  • updated_atstring ou null
    Quando o estado do Sam AI mudou pela última vez, em ISO 8601.
O objeto conversation Sam AI
{
  "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"
}

Obter o Sam AI de uma conversa

GET/v1/conversations/:conversation_id/samScope readMCPget_sam_settings

Retorna o modo do Sam AI na conversa e o modo que está valendo de fato, a resposta que ele tem pronta e as instruções e os arquivos próprios da conversa.

Parâmetros de caminho

  • conversation_idstringObrigatório
    O ID da conversa.

Retorno

O objeto conversation Sam AI.

Erros

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

Atualizar o Sam AI de uma conversa

PATCH/v1/conversations/:conversation_id/samScope writeMCPupdate_sam_settings

Define o modo do Sam AI só nesta conversa, devolve a conversa ao modo da persona com inherit ou altera o que o Sam AI sabe sobre este lead. Só mudam os campos que você envia. Com auto, as respostas saem sozinhas pela sua conta do X.

Parâmetros de caminho

  • conversation_idstringObrigatório
    O ID da conversa.

Parâmetros do corpo

  • modestring
    O modo do Sam AI nesta conversa. inherit segue o da persona.
    offdraftautoinherit
  • instructionsstring
    O que o Sam AI precisa saber sobre este lead, com até 3 000 caracteres. Uma string vazia apaga o texto.

Retorno

O objeto conversation Sam AI atualizado.

Erros

  • 404resource_missing
    Nenhuma conversa com este ID na conta da chave.
  • 400parameter_invalid
    Um parâmetro tem um valor que a API não aceita. param diz qual.
  • 400parameter_unknown
    O corpo tem um campo que este endpoint não aceita.
  • 403plan_required
    auto numa conta com plano abaixo do Business.
  • 403forbidden
    A chave de um membro da equipe altera uma área que a função dele só pode ver. O botão que liga o Sam AI na conta do X e as conversas ficam na área de chat, as informações do negócio e os arquivos em configurações, e o Sam AI de uma persona em 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"
  }'
Resposta200
{
  "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"
}

O objeto Sam AI file

Um documento que o Sam AI lê antes de cada resposta, um arquivo PDF, DOCX, TXT, MD ou CSV. Cada nível comporta no máximo 30 arquivos e 100 MB.

Atributos

  • idstring
    Identificador único do arquivo no nível dele.
  • objectstring
    Sempre sam_file.
  • namestring
    O nome do arquivo, como o app mostra.
  • sizeinteger
    O tamanho dele em bytes.
  • mime_typestring ou null
    O tipo dele, como application/pdf.
  • urlstring
    Onde o Gemlead guarda o arquivo.
O objeto Sam AI file
{
  "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"
}

Adicionar um arquivo à conta

POST/v1/account/sam/filesScope writeMCPedit_sam_files

Entrega ao Sam AI um documento para ler em todas as conversas da conta do X. Envie a URL pública dele ou os bytes em base64. O Gemlead lê o arquivo uma vez, confere se é um PDF, DOCX, TXT, MD ou CSV e guarda uma cópia própria.

Parâmetros do corpo

  • urlstring
    O arquivo numa URL HTTPS pública. O Gemlead lê o arquivo uma vez e guarda uma cópia própria. Informe url ou data.
  • datastring
    O arquivo, codificado em base64, no lugar de url. Envie um arquivo grande como url.
  • namestring
    O nome que o app mostra, com até 200 caracteres. Obrigatório com data, senão é a última parte da URL. O Gemlead adiciona a extensão quando ela falta.

Retorno

O novo objeto Sam AI file.

Erros

  • 400parameter_missing
    Falta um parâmetro obrigatório. param diz qual.
  • 400parameter_invalid
    O arquivo não é PDF, DOCX, TXT, MD nem CSV, está vazio ou tem mais de 25 MB, ou não dá para ler a URL dele. param diz qual.
  • 400parameter_unknown
    O corpo tem um campo que este endpoint não aceita.
  • 400limit_reached
    O nível já tem 30 arquivos ou 100 MB de arquivos. Exclua um antes.
  • 429rate_limit_exceeded
    Mais de 100 arquivos na mesma hora nesta conta do X.
  • 403forbidden
    A chave de um membro da equipe altera uma área que a função dele só pode ver. O botão que liga o Sam AI na conta do X e as conversas ficam na área de chat, as informações do negócio e os arquivos em configurações, e o Sam AI de uma persona em 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"
  }'
Resposta200
{
  "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"
}

Excluir um arquivo da conta

DELETE/v1/account/sam/files/:file_idScope writeMCPedit_sam_files

Tira um arquivo do nível. O Sam AI deixa de ler o arquivo a partir da próxima resposta.

Parâmetros de caminho

  • file_idstringObrigatório
    O ID do arquivo do Sam AI.

Retorno

Um objeto com o id do arquivo e deleted igual a true.

Erros

  • 404resource_missing
    Nenhum arquivo do Sam AI com este ID na conta da chave.
  • 403forbidden
    A chave de um membro da equipe altera uma área que a função dele só pode ver. O botão que liga o Sam AI na conta do X e as conversas ficam na área de chat, as informações do negócio e os arquivos em configurações, e o Sam AI de uma persona em 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"
Resposta200
{
  "id": "sf_4c1e9a07d2b35f68e190",
  "object": "sam_file",
  "deleted": true
}

Adicionar um arquivo a uma persona

POST/v1/personas/:persona_id/sam/filesScope writeMCPedit_sam_files

Entrega ao Sam AI um documento para ler nas conversas da persona. Envie a URL pública dele ou os bytes em base64. O Gemlead lê o arquivo uma vez, confere se é um PDF, DOCX, TXT, MD ou CSV e guarda uma cópia própria.

Parâmetros de caminho

  • persona_idstringObrigatório
    O ID da persona.

Parâmetros do corpo

  • urlstring
    O arquivo numa URL HTTPS pública. O Gemlead lê o arquivo uma vez e guarda uma cópia própria. Informe url ou data.
  • datastring
    O arquivo, codificado em base64, no lugar de url. Envie um arquivo grande como url.
  • namestring
    O nome que o app mostra, com até 200 caracteres. Obrigatório com data, senão é a última parte da URL. O Gemlead adiciona a extensão quando ela falta.

Retorno

O novo objeto Sam AI file.

Erros

  • 404resource_missing
    Nenhuma persona com este ID na conta da chave.
  • 400parameter_missing
    Falta um parâmetro obrigatório. param diz qual.
  • 400parameter_invalid
    O arquivo não é PDF, DOCX, TXT, MD nem CSV, está vazio ou tem mais de 25 MB, ou não dá para ler a URL dele. param diz qual.
  • 400parameter_unknown
    O corpo tem um campo que este endpoint não aceita.
  • 400limit_reached
    O nível já tem 30 arquivos ou 100 MB de arquivos. Exclua um antes.
  • 429rate_limit_exceeded
    Mais de 100 arquivos na mesma hora nesta conta do X.
  • 403forbidden
    A chave de um membro da equipe altera uma área que a função dele só pode ver. O botão que liga o Sam AI na conta do X e as conversas ficam na área de chat, as informações do negócio e os arquivos em configurações, e o Sam AI de uma persona em 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"
  }'
Resposta200
{
  "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"
}

Excluir um arquivo de uma persona

DELETE/v1/personas/:persona_id/sam/files/:file_idScope writeMCPedit_sam_files

Tira um arquivo do nível. O Sam AI deixa de ler o arquivo a partir da próxima resposta.

Parâmetros de caminho

  • persona_idstringObrigatório
    O ID da persona.
  • file_idstringObrigatório
    O ID do arquivo do Sam AI.

Retorno

Um objeto com o id do arquivo e deleted igual a true.

Erros

  • 404resource_missing
    Nenhum arquivo do Sam AI com este ID na conta da chave.
  • 403forbidden
    A chave de um membro da equipe altera uma área que a função dele só pode ver. O botão que liga o Sam AI na conta do X e as conversas ficam na área de chat, as informações do negócio e os arquivos em configurações, e o Sam AI de uma persona em 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"
Resposta200
{
  "id": "sf_4c1e9a07d2b35f68e190",
  "object": "sam_file",
  "deleted": true
}

Adicionar um arquivo a uma conversa

POST/v1/conversations/:conversation_id/sam/filesScope writeMCPedit_sam_files

Entrega ao Sam AI um documento sobre este lead específico. Envie a URL pública dele ou os bytes em base64. O Gemlead lê o arquivo uma vez, confere se é um PDF, DOCX, TXT, MD ou CSV e guarda uma cópia própria.

Parâmetros de caminho

  • conversation_idstringObrigatório
    O ID da conversa.

Parâmetros do corpo

  • urlstring
    O arquivo numa URL HTTPS pública. O Gemlead lê o arquivo uma vez e guarda uma cópia própria. Informe url ou data.
  • datastring
    O arquivo, codificado em base64, no lugar de url. Envie um arquivo grande como url.
  • namestring
    O nome que o app mostra, com até 200 caracteres. Obrigatório com data, senão é a última parte da URL. O Gemlead adiciona a extensão quando ela falta.

Retorno

O novo objeto Sam AI file.

Erros

  • 404resource_missing
    Nenhuma conversa com este ID na conta da chave.
  • 400parameter_missing
    Falta um parâmetro obrigatório. param diz qual.
  • 400parameter_invalid
    O arquivo não é PDF, DOCX, TXT, MD nem CSV, está vazio ou tem mais de 25 MB, ou não dá para ler a URL dele. param diz qual.
  • 400parameter_unknown
    O corpo tem um campo que este endpoint não aceita.
  • 400limit_reached
    O nível já tem 30 arquivos ou 100 MB de arquivos. Exclua um antes.
  • 429rate_limit_exceeded
    Mais de 100 arquivos na mesma hora nesta conta do X.
  • 403forbidden
    A chave de um membro da equipe altera uma área que a função dele só pode ver. O botão que liga o Sam AI na conta do X e as conversas ficam na área de chat, as informações do negócio e os arquivos em configurações, e o Sam AI de uma persona em 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"
  }'
Resposta200
{
  "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"
}

Excluir um arquivo de uma conversa

DELETE/v1/conversations/:conversation_id/sam/files/:file_idScope writeMCPedit_sam_files

Tira um arquivo do nível. O Sam AI deixa de ler o arquivo a partir da próxima resposta.

Parâmetros de caminho

  • conversation_idstringObrigatório
    O ID da conversa.
  • file_idstringObrigatório
    O ID do arquivo do Sam AI.

Retorno

Um objeto com o id do arquivo e deleted igual a true.

Erros

  • 404resource_missing
    Nenhum arquivo do Sam AI com este ID na conta da chave.
  • 403forbidden
    A chave de um membro da equipe altera uma área que a função dele só pode ver. O botão que liga o Sam AI na conta do X e as conversas ficam na área de chat, as informações do negócio e os arquivos em configurações, e o Sam AI de uma persona em 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"
Resposta200
{
  "id": "sf_4c1e9a07d2b35f68e190",
  "object": "sam_file",
  "deleted": true
}
Receba as novidades do Gemlead
direto no seu e-mail.
Assinar
Ao assinar, você aceita a nossa Política de Privacidade e concorda em receber novidades da nossa empresa.
Gemlead
Produto
Começar
Entrar
Para quem
Agentes de IA
Recursos
Preços
Afiliados
FAQ
Recursos
Compradores, 24/7Os quentes primeiro+60% de respostasDMs sob medidaTudo numa caixa sóSeu closer de IAEscale sem limitesAPI, MCP, webhooksPergunte ao Gemlead
Conteúdo
InícioAPIBlog
Jurídico
Termos
Privacidade
© 2026 Gemlead, Inc. Todos os direitos reservados.
Português