Gemlead
Docs
Iniciar sesión
Obtén tu clave API

Referencia de la API

Sam AI

Sam AI escribe tus respuestas en las conversaciones de tus campañas. Lee instrucciones y archivos en tres niveles, la cuenta de X para tu negocio, el buyer persona para saber cómo venderle a ese tipo de comprador, y la conversación para este lead en concreto. Cuando dos niveles no coinciden, gana el más preciso.

Una conversación funciona en uno de estos tres modos. off te la deja a ti. draft es Semiauto, Sam AI escribe una sugerencia y tú la envías. auto deja que Sam AI envíe sus respuestas solo desde tu cuenta de X. Un buyer persona define el modo de sus conversaciones, y una conversación puede tener el suyo propio o seguir el de su buyer persona con inherit.

Sam AI funciona con los planes Business y Enterprise, y solo en campañas en curso. Por debajo de Business no escribe nada, ni en draft ni en auto. Cada respuesta de Sam AI usa 30 créditos al enviarse, tenga los mensajes que tenga. Una sugerencia que no envías es gratis, pero Sam AI solo escribe una si tu saldo cubre una respuesta. Las sugerencias nuevas, las respuestas que envía Sam AI y las conversaciones que te pasa también llegan con los webhooks sam.suggestion.ready, sam.reply.sent y sam.handoff.

Endpoints

El objeto account Sam AI

Sam AI en toda la cuenta de X, si está activado y lo que sabe de tu negocio.

Atributos

  • objectstring
    Siempre account_sam.
  • account_idstring
    El ID de la cuenta de X, como en el objeto account.
  • enabledboolean
    false cuando Sam AI está desactivado en todas las conversaciones de la cuenta de X, sea cual sea su modo.
  • instructionsstring
    La descripción de tu negocio, que Sam AI lee en cada conversación, como tu oferta, tus precios, tu garantía y tus enlaces. Hasta 3 000 caracteres.
  • filesarray de objects
    Los archivos que Sam AI lee en cada conversación, como objetos Sam AI file.
El 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"
    }
  ]
}

Obtener el Sam AI de la cuenta

GET/v1/account/samScope readMCPget_sam_settings

Indica si Sam AI está activado en la cuenta de X, y devuelve la información de tu negocio y sus archivos.

Devuelve

El objeto account Sam AI.

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

Actualizar el Sam AI de la cuenta

PATCH/v1/account/samScope writeMCPupdate_sam_settings

Activa o desactiva Sam AI en toda la cuenta de X, o cambia la información de tu negocio que lee cada conversación. Solo cambian los campos que envías.

Parámetros del cuerpo

  • enabledboolean
    false desactiva Sam AI en todas las conversaciones de la cuenta de X, true lo vuelve a activar.
  • instructionsstring
    La descripción de tu negocio, hasta 3 000 caracteres. Un string vacío la borra.

Devuelve

El objeto account Sam AI actualizado.

Errores

  • 400parameter_invalid
    Un parámetro tiene un valor que la API no acepta. param lo indica.
  • 400parameter_unknown
    El cuerpo tiene un campo que este endpoint no acepta.
  • 403forbidden
    La clave de un miembro del equipo cambia una zona que su rol solo puede ver. La activación en la cuenta de X y las conversaciones están en la zona chat, la información de tu negocio y los archivos de la cuenta en la zona settings, y el Sam AI de un buyer persona en la zona 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."
  }'
Respuesta200
{
  "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"
    }
  ]
}

El objeto persona Sam AI

Sam AI en un buyer persona, para las conversaciones con sus leads.

Atributos

  • objectstring
    Siempre persona_sam.
  • persona_idstring
    El ID del buyer persona.
  • modestring
    El modo de las conversaciones del buyer persona que no tienen uno propio. off te las deja a ti, draft es Semiauto, en el que Sam AI sugiere y tú envías, auto deja que Sam AI envíe solo. draft mientras no lo cambies.
    offdraftauto
  • instructionsstring
    Cómo escribir y vender a este tipo de comprador. Son las Instrucciones del buyer persona en la app. Hasta 6 000 caracteres.
  • filesarray de objects
    Los archivos que Sam AI lee en las conversaciones del buyer persona, como objetos Sam AI file.
El 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": []
}

Obtener el Sam AI de un buyer persona

GET/v1/personas/:persona_id/samScope readMCPget_sam_settings

Devuelve el modo de Sam AI en las conversaciones del buyer persona, sus instrucciones y sus archivos.

Parámetros de ruta

  • persona_idstringObligatorio
    El ID del buyer persona.

Devuelve

El objeto persona Sam AI.

Errores

  • 404resource_missing
    No hay ningún buyer persona con este ID en la cuenta de la clave.
GET/v1/personas/:persona_id/sam
curl https://gemlead.ai/api/v1/personas/lvWBPnytpS/sam \
  -H "Authorization: Bearer $GEMLEAD_API_KEY"
Respuesta200
{
  "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": []
}

Actualizar el Sam AI de un buyer persona

PATCH/v1/personas/:persona_id/samScope writeMCPupdate_sam_settings

Cambia el modo de Sam AI en las conversaciones del buyer persona que no tienen modo propio, o las instrucciones del buyer persona. Solo cambian los campos que envías. auto envía las respuestas desde tu cuenta de X sin pasar por ti.

Parámetros de ruta

  • persona_idstringObligatorio
    El ID del buyer persona.

Parámetros del cuerpo

  • modestring
    El modo de Sam AI en las conversaciones del buyer persona.
    offdraftauto
  • instructionsstring
    Cómo escribir y vender a este tipo de comprador, hasta 6 000 caracteres. Un string vacío lo borra.

Devuelve

El objeto persona Sam AI actualizado.

Errores

  • 404resource_missing
    No hay ningún buyer persona con este ID en la cuenta de la clave.
  • 400parameter_invalid
    Un parámetro tiene un valor que la API no acepta. param lo indica.
  • 400parameter_unknown
    El cuerpo tiene un campo que este endpoint no acepta.
  • 403plan_required
    auto en una cuenta con un plan inferior a Business.
  • 403forbidden
    La clave de un miembro del equipo cambia una zona que su rol solo puede ver. La activación en la cuenta de X y las conversaciones están en la zona chat, la información de tu negocio y los archivos de la cuenta en la zona settings, y el Sam AI de un buyer persona en la zona 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"
  }'
Respuesta200
{
  "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": []
}

El objeto conversation Sam AI

Sam AI en una conversación, su modo, la respuesta que tiene lista y lo que sabe de este lead.

Atributos

  • objectstring
    Siempre conversation_sam.
  • conversation_idstring
    El ID de la conversación.
  • modestring
    El modo propio de la conversación, o inherit cuando sigue el de su buyer persona.
    offdraftautoinherit
  • effective_modestring
    El modo que se aplica de verdad. off cuando Sam AI está desactivado en la cuenta de X, la conversación no está en ninguna campaña en curso o la cuenta está por debajo del plan Business.
    offdraftauto
  • personaobject o null
    El buyer persona que lee Sam AI, con su id, name y mode.
  • campaignobject o null
    La campaña en la que está la conversación, con su id y name. Sam AI solo responde en una campaña en curso.
  • statusstring
    Lo que está haciendo Sam AI. writing cuando escribe una respuesta, suggested cuando una te espera, scheduled cuando se enviará sola en suggestion.send_at, sending, sent, no_reply cuando decidió no responder, handoff cuando te pasa la conversación, no_credits cuando el saldo no llega a los 30 créditos de una respuesta, off o idle.
    idlewritingsuggestedscheduledsendingsentno_replyhandoffno_creditsoff
  • reasonstring o null
    El motivo, para no_reply y handoff, tal como lo escribió Sam AI.
  • suggestionobject o null
    La respuesta que Sam AI tiene lista, mientras status es suggested, scheduled o sending.
  • instructionsstring
    Lo que Sam AI debe saber sobre este lead en concreto. Hasta 3 000 caracteres.
  • filesarray de objects
    Los archivos que Sam AI lee solo en esta conversación, como objetos Sam AI file.
  • updated_atstring o null
    Cuándo cambió por última vez el estado de Sam AI, en ISO 8601.
El 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"
}

Obtener el Sam AI de una conversación

GET/v1/conversations/:conversation_id/samScope readMCPget_sam_settings

Devuelve el modo de Sam AI en la conversación y el que se aplica de verdad, la respuesta que tiene lista, y las instrucciones y los archivos propios de la conversación.

Parámetros de ruta

  • conversation_idstringObligatorio
    El ID de la conversación.

Devuelve

El objeto conversation Sam AI.

Errores

  • 404resource_missing
    No hay ninguna conversación con este ID en la cuenta de la clave.
GET/v1/conversations/:conversation_id/sam
curl https://gemlead.ai/api/v1/conversations/msgOtJ8dvT/sam \
  -H "Authorization: Bearer $GEMLEAD_API_KEY"
Respuesta200
{
  "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"
}

Actualizar el Sam AI de una conversación

PATCH/v1/conversations/:conversation_id/samScope writeMCPupdate_sam_settings

Define el modo de Sam AI solo en esta conversación, o se lo devuelve a su buyer persona con inherit, o cambia lo que Sam AI sabe de este lead. Solo cambian los campos que envías. auto envía las respuestas desde tu cuenta de X sin pasar por ti.

Parámetros de ruta

  • conversation_idstringObligatorio
    El ID de la conversación.

Parámetros del cuerpo

  • modestring
    El modo de Sam AI aquí. inherit sigue el del buyer persona.
    offdraftautoinherit
  • instructionsstring
    Lo que Sam AI debe saber sobre este lead, hasta 3 000 caracteres. Un string vacío lo borra.

Devuelve

El objeto conversation Sam AI actualizado.

Errores

  • 404resource_missing
    No hay ninguna conversación con este ID en la cuenta de la clave.
  • 400parameter_invalid
    Un parámetro tiene un valor que la API no acepta. param lo indica.
  • 400parameter_unknown
    El cuerpo tiene un campo que este endpoint no acepta.
  • 403plan_required
    auto en una cuenta con un plan inferior a Business.
  • 403forbidden
    La clave de un miembro del equipo cambia una zona que su rol solo puede ver. La activación en la cuenta de X y las conversaciones están en la zona chat, la información de tu negocio y los archivos de la cuenta en la zona settings, y el Sam AI de un buyer persona en la zona 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"
  }'
Respuesta200
{
  "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"
}

El objeto Sam AI file

Un documento que Sam AI lee antes de cada respuesta, un archivo PDF, DOCX, TXT, MD o CSV. Cada nivel admite 30 archivos y 100 MB como máximo.

Atributos

  • idstring
    Identificador único del archivo en su nivel.
  • objectstring
    Siempre sam_file.
  • namestring
    El nombre del archivo, tal como lo muestra la app.
  • sizeinteger
    Su tamaño en bytes.
  • mime_typestring o null
    Su tipo, como application/pdf.
  • urlstring
    Dónde lo guarda Gemlead.
El 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"
}

Añadir un archivo a la cuenta

POST/v1/account/sam/filesScope writeMCPedit_sam_files

Da a Sam AI un documento para leer en todas las conversaciones de la cuenta de X. Envía su URL pública o su contenido en base64. Gemlead lo lee una sola vez, comprueba que es un archivo PDF, DOCX, TXT, MD o CSV y guarda su propia copia.

Parámetros del cuerpo

  • urlstring
    El archivo, en una URL HTTPS pública. Gemlead lo lee una sola vez y guarda su propia copia. Indica url o data.
  • datastring
    El archivo, codificado en base64, en lugar de url. Envía los archivos grandes con url.
  • namestring
    El nombre que muestra la app, hasta 200 caracteres. Obligatorio con data. Si no lo indicas, se usa la última parte de la URL. Gemlead añade la extensión si falta.

Devuelve

El nuevo objeto Sam AI file.

Errores

  • 400parameter_missing
    Falta un parámetro obligatorio. param lo indica.
  • 400parameter_invalid
    El archivo no es un PDF, DOCX, TXT, MD o CSV, está vacío o pesa más de 25 MB, o no se puede leer su URL. param indica el parámetro en cuestión.
  • 400parameter_unknown
    El cuerpo tiene un campo que este endpoint no acepta.
  • 400limit_reached
    El nivel ya tiene 30 archivos o 100 MB de archivos. Elimina uno primero.
  • 429rate_limit_exceeded
    Más de 100 archivos en una hora en esta cuenta de X.
  • 403forbidden
    La clave de un miembro del equipo cambia una zona que su rol solo puede ver. La activación en la cuenta de X y las conversaciones están en la zona chat, la información de tu negocio y los archivos de la cuenta en la zona settings, y el Sam AI de un buyer persona en la zona 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"
  }'
Respuesta200
{
  "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"
}

Eliminar un archivo de la cuenta

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

Quita un archivo del nivel. Sam AI deja de leerlo a partir de su próxima respuesta.

Parámetros de ruta

  • file_idstringObligatorio
    El ID del archivo de Sam AI.

Devuelve

Un objeto con el id del archivo y deleted en true.

Errores

  • 404resource_missing
    No hay ningún archivo de Sam AI con este ID en la cuenta de la clave.
  • 403forbidden
    La clave de un miembro del equipo cambia una zona que su rol solo puede ver. La activación en la cuenta de X y las conversaciones están en la zona chat, la información de tu negocio y los archivos de la cuenta en la zona settings, y el Sam AI de un buyer persona en la zona 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"
Respuesta200
{
  "id": "sf_4c1e9a07d2b35f68e190",
  "object": "sam_file",
  "deleted": true
}

Añadir un archivo a un buyer persona

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

Da a Sam AI un documento para leer en las conversaciones del buyer persona. Envía su URL pública o su contenido en base64. Gemlead lo lee una sola vez, comprueba que es un archivo PDF, DOCX, TXT, MD o CSV y guarda su propia copia.

Parámetros de ruta

  • persona_idstringObligatorio
    El ID del buyer persona.

Parámetros del cuerpo

  • urlstring
    El archivo, en una URL HTTPS pública. Gemlead lo lee una sola vez y guarda su propia copia. Indica url o data.
  • datastring
    El archivo, codificado en base64, en lugar de url. Envía los archivos grandes con url.
  • namestring
    El nombre que muestra la app, hasta 200 caracteres. Obligatorio con data. Si no lo indicas, se usa la última parte de la URL. Gemlead añade la extensión si falta.

Devuelve

El nuevo objeto Sam AI file.

Errores

  • 404resource_missing
    No hay ningún buyer persona con este ID en la cuenta de la clave.
  • 400parameter_missing
    Falta un parámetro obligatorio. param lo indica.
  • 400parameter_invalid
    El archivo no es un PDF, DOCX, TXT, MD o CSV, está vacío o pesa más de 25 MB, o no se puede leer su URL. param indica el parámetro en cuestión.
  • 400parameter_unknown
    El cuerpo tiene un campo que este endpoint no acepta.
  • 400limit_reached
    El nivel ya tiene 30 archivos o 100 MB de archivos. Elimina uno primero.
  • 429rate_limit_exceeded
    Más de 100 archivos en una hora en esta cuenta de X.
  • 403forbidden
    La clave de un miembro del equipo cambia una zona que su rol solo puede ver. La activación en la cuenta de X y las conversaciones están en la zona chat, la información de tu negocio y los archivos de la cuenta en la zona settings, y el Sam AI de un buyer persona en la zona 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"
  }'
Respuesta200
{
  "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"
}

Eliminar un archivo de un buyer persona

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

Quita un archivo del nivel. Sam AI deja de leerlo a partir de su próxima respuesta.

Parámetros de ruta

  • persona_idstringObligatorio
    El ID del buyer persona.
  • file_idstringObligatorio
    El ID del archivo de Sam AI.

Devuelve

Un objeto con el id del archivo y deleted en true.

Errores

  • 404resource_missing
    No hay ningún archivo de Sam AI con este ID en la cuenta de la clave.
  • 403forbidden
    La clave de un miembro del equipo cambia una zona que su rol solo puede ver. La activación en la cuenta de X y las conversaciones están en la zona chat, la información de tu negocio y los archivos de la cuenta en la zona settings, y el Sam AI de un buyer persona en la zona 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"
Respuesta200
{
  "id": "sf_4c1e9a07d2b35f68e190",
  "object": "sam_file",
  "deleted": true
}

Añadir un archivo a una conversación

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

Da a Sam AI un documento sobre este lead en concreto. Envía su URL pública o su contenido en base64. Gemlead lo lee una sola vez, comprueba que es un archivo PDF, DOCX, TXT, MD o CSV y guarda su propia copia.

Parámetros de ruta

  • conversation_idstringObligatorio
    El ID de la conversación.

Parámetros del cuerpo

  • urlstring
    El archivo, en una URL HTTPS pública. Gemlead lo lee una sola vez y guarda su propia copia. Indica url o data.
  • datastring
    El archivo, codificado en base64, en lugar de url. Envía los archivos grandes con url.
  • namestring
    El nombre que muestra la app, hasta 200 caracteres. Obligatorio con data. Si no lo indicas, se usa la última parte de la URL. Gemlead añade la extensión si falta.

Devuelve

El nuevo objeto Sam AI file.

Errores

  • 404resource_missing
    No hay ninguna conversación con este ID en la cuenta de la clave.
  • 400parameter_missing
    Falta un parámetro obligatorio. param lo indica.
  • 400parameter_invalid
    El archivo no es un PDF, DOCX, TXT, MD o CSV, está vacío o pesa más de 25 MB, o no se puede leer su URL. param indica el parámetro en cuestión.
  • 400parameter_unknown
    El cuerpo tiene un campo que este endpoint no acepta.
  • 400limit_reached
    El nivel ya tiene 30 archivos o 100 MB de archivos. Elimina uno primero.
  • 429rate_limit_exceeded
    Más de 100 archivos en una hora en esta cuenta de X.
  • 403forbidden
    La clave de un miembro del equipo cambia una zona que su rol solo puede ver. La activación en la cuenta de X y las conversaciones están en la zona chat, la información de tu negocio y los archivos de la cuenta en la zona settings, y el Sam AI de un buyer persona en la zona 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"
  }'
Respuesta200
{
  "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"
}

Eliminar un archivo de una conversación

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

Quita un archivo del nivel. Sam AI deja de leerlo a partir de su próxima respuesta.

Parámetros de ruta

  • conversation_idstringObligatorio
    El ID de la conversación.
  • file_idstringObligatorio
    El ID del archivo de Sam AI.

Devuelve

Un objeto con el id del archivo y deleted en true.

Errores

  • 404resource_missing
    No hay ningún archivo de Sam AI con este ID en la cuenta de la clave.
  • 403forbidden
    La clave de un miembro del equipo cambia una zona que su rol solo puede ver. La activación en la cuenta de X y las conversaciones están en la zona chat, la información de tu negocio y los archivos de la cuenta en la zona settings, y el Sam AI de un buyer persona en la zona 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"
Respuesta200
{
  "id": "sf_4c1e9a07d2b35f68e190",
  "object": "sam_file",
  "deleted": true
}
Recibe las novedades de Gemlead
directamente en tu bandeja de entrada.
Suscribirme
Al suscribirte aceptas nuestra Política de privacidad y das tu consentimiento para recibir novedades de nuestra empresa.
Gemlead
Producto
Empezar
Iniciar sesión
Para quién
Agentes de IA
Funciones
Precios
Afiliados
FAQ
Funciones
Compradores 24/7Primero los calientes+60% de respuestasDM a medidaUna bandeja para todoTu closer con IAEscala sin límitesAPI, MCP, webhooksPregunta a Gemlead
Recursos
InicioAPIBlog
Legal
Términos
Privacidad
© 2026 Gemlead, Inc. Todos los derechos reservados.
Español