API de ingesta: sus sistemas alimentan al asistente

Seguridad: lo que debe saber

• Usted es quien envía: QuickAsk nunca se conecta a su red y no posee ninguna credencial suya.
• No es necesario abrir el cortafuegos ni instalar nada: basta con una simple llamada HTTPS saliente.
• Una clave solo es válida para un único asistente. No existe una clave global de cuenta.
• La clave se muestra una sola vez, al crearla. QuickAsk solo conserva una huella, como una contraseña: nadie, tampoco nosotros, puede volver a leerla.
• La clave sirve únicamente para añadir, actualizar, retirar y listar los contenidos que ha enviado. No permite leer ni el texto de la base ni las conversaciones.
• Los contenidos enviados pasan los mismos controles que un archivo añadido a mano: verificación del formato real, lectura en un entorno aislado, bloqueo de los textos que intentan dar instrucciones al asistente.
• El propietario del asistente puede revocar una clave en cualquier momento; ve la fecha del último uso de cada clave y un registro de la actividad reciente (conservado 30 días, sin dirección IP ni contenido).

Empezar en 3 pasos

1. En QuickAsk, el propietario del asistente abre el asistente, pestaña «Conocimientos», sección «Envío automático desde sus programas», y hace clic en «Crear una clave».
2. Le transmite la clave (que empieza por qak_) y el identificador del asistente que aparece al lado. Guarde la clave en su almacén de secretos.
3. Su sistema envía sus contenidos con el encabezado «Authorization: Bearer» seguido de la clave, como en los ejemplos siguientes.

Puntos de acceso

Dirección base: https://www.quick-ask.app/api/v1

El identificador externo es el de su sistema («producto-123», «faq:entrega»…): de 1 a 128 caracteres, letras, cifras y . _ - : ~ @, empezando por una letra o una cifra.

Enviar un contenido

curl -X PUT "https://www.quick-ask.app/api/v1/bots/$BOT_ID/knowledge/faq-delivery" \
  -H "Authorization: Bearer $QUICKASK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Delivery times",
    "format": "markdown",
    "content": "## Delivery\nOrders placed before 2 pm ship the same day.",
    "source_url": "https://intranet.example.com/faq/delivery",
    "updated_at": "2026-10-13T09:30:00Z"
  }'

curl -X PUT "https://www.quick-ask.app/api/v1/bots/$BOT_ID/knowledge/hr-handbook" \
  -H "Authorization: Bearer $QUICKASK_API_KEY" \
  -F "[email protected]" \
  -F "title=Employee handbook" \
  -F "updated_at=2026-09-01"

Respuestas

• created — 201: el contenido no existía, se ha añadido.
• updated — 200: el contenido ha cambiado; solo se vuelven a calcular las partes modificadas.
• unchanged — 200: contenido idéntico al último envío, no se vuelve a calcular nada. Por tanto, puede reenviarlo todo en cada sincronización.

HTTP/1.1 201 Created
{
  "external_id": "faq-delivery",
  "status": "created",          // "updated" or "unchanged" on the next calls
  "title": "Delivery times",
  "document_name": "[API] Delivery times",
  "chunks": 1,
  "indexed_bytes": 58,          // 0 when nothing changed
  "source_url": "https://intranet.example.com/faq/delivery",
  "updated_at": "2026-10-13T09:30:00.000Z"
}

Retirar y listar

curl -X DELETE "https://www.quick-ask.app/api/v1/bots/$BOT_ID/knowledge/faq-delivery" \
  -H "Authorization: Bearer $QUICKASK_API_KEY"

curl "https://www.quick-ask.app/api/v1/bots/$BOT_ID/knowledge?limit=100" \
  -H "Authorization: Bearer $QUICKASK_API_KEY"
# → { "items": [ { "external_id": "faq-delivery", "title": "...", "updated_at": "...",
#                  "indexed_at": "...", "size_bytes": 58, "chunks": 1, ... } ],
#     "next_cursor": null }   // pass ?cursor=<next_cursor> to get the next page

Límites

• Tamaño: 2 MB de texto como máximo por contenido, 4 MB por archivo.
• Archivos aceptados: pdf, docx, xlsx, pptx, csv, txt, md. Las imágenes, el audio, el vídeo y los PDF escaneados (sin texto) no los lee la API.
• Caudal: 60 llamadas por minuto y por clave.
• Volumen de contenidos nuevos o modificados por asistente y por 24 h: 10 MB (Business), 25 MB (Pro), 50 MB (Agency y a medida). Los contenidos sin cambios no cuentan.
• Se aplica el espacio de almacenamiento del plan, como para un archivo añadido a mano.
• La API está disponible a partir del plan Business.
• Los contenidos enviados por la API no se descuentan de las solicitudes del plan.

Errores

Un error devuelve un código HTTP y un JSON cuyo campo error contiene un código y un mensaje. El código es estable: básese en él, no en el mensaje. Cuando tiene sentido reintentar, el encabezado Retry-After indica el plazo en segundos.

HTTP/1.1 429 Too Many Requests
Retry-After: 60
{ "error": { "code": "rate_limited", "message": "Too many requests: at most 60 per minute per key." } }

Ejemplo con n8n (o Make)

1. Cree una credencial «Bearer Auth» que contenga la clave de QuickAsk.
2. Después del nodo que lee sus datos (base, hoja de cálculo, ERP…), añada un nodo «HTTP Request» con el método PUT, con la dirección siguiente y el identificador de cada elemento al final.
3. Envíe un cuerpo JSON con el título, el texto y, si es posible, la dirección y la fecha de actualización del elemento.
4. Deje aproximadamente un segundo entre dos llamadas (opción «Batching») para no superar el límite de caudal. Con Make, el módulo «HTTP — Make a request» se configura del mismo modo.

{
  "method": "PUT",
  "url": "https://www.quick-ask.app/api/v1/bots/<BOT_ID>/knowledge/{{ $json.id }}",
  "authentication": "genericCredentialType",
  "genericAuthType": "httpBearerAuth",
  "sendBody": true,
  "contentType": "json",
  "specifyBody": "json",
  "jsonBody": "={{ { title: $json.name, content: $json.description, format: 'text', source_url: $json.url, updated_at: $json.updatedAt } }}",
  "options": { "batching": { "batch": { "batchSize": 1, "batchInterval": 1100 } } }
}

Buenas prácticas

• Utilice un identificador estable (la clave primaria de su base): es lo que permite una actualización en lugar de un duplicado.
• Envíe la fecha de actualización: ayuda al asistente a preferir la información más reciente.
• Puede reenviar todo su catálogo en cada sincronización: un contenido sin cambios no cuesta nada.
• Para retirar lo que ya no existe en su sistema, compare la lista (GET) con sus datos y elimine los identificadores desaparecidos.
• Guarde la clave en el lado del servidor (nunca en una página web ni en una aplicación móvil) y revóquela en cuanto deje de usarse.