Seguimos Semantic Versioning para el SDK. El contrato de la API pública es estable dentro de v1; cualquier cambio incompatible se anunciará aquí con al menos 30 días de aviso.

v1 (0.4.0-beta) — 2026-06-14 (Formularios embebibles)

Add-only. Nueva superficie de formularios embebibles para capturar tickets y leads desde tu propia web sin instalar el widget de chat.

API:

• GET https://api.lectico.com/v1/forms/{form_id}/config — devuelve la configuración pública de un formulario (campos, etiquetas, validaciones, branding). La sirve la API pública bajo api.lectico.com y la consume el render del formulario embebido. Autenticación con la cabecera Lectico-Api-Key (clave pública del workspace, equivalente a widget_pk_*).
• POST https://forms.lectico.com/api/forms/{form_id}/submit — recibe el envío del formulario y crea el ticket o lead correspondiente en el workspace. Sirve desde el subdominio dedicado forms.lectico.com. Cabecera Lectico-Api-Key obligatoria.
  • Acepta un identity_token firmado opcional: un token que tu backend genera para identificar de forma verificable al usuario que envía el formulario (evita suplantación). Si lo incluyes, Lectico asocia el envío a esa identidad sin que el visitante pueda falsearla; si lo omites, el envío se trata como anónimo/auto-declarado.

Los envíos que generan un ticket pasan por el mismo pipeline que POST /v1/tickets: emiten ticket.created, notifican al owner por email y respetan los topes de plan.

Guía de uso: ver Formularios embebibles para la instalación paso a paso y Tickets para gestionar las solicitudes que llegan.

Sin cambios en endpoints existentes.

v1 (0.3.0-beta) — 2026-05-30 (Tickets: soporte humano vía API)

Add-only sobre 0.2.1-beta. Cero breaking changes — se añade el recurso tickets completo y 4 eventos de webhook nuevos. Documenta en el changelog endpoints que ya existían en producción.

API — recurso tickets (9 endpoints):

• POST /v1/tickets — crea un ticket. Tres orígenes: widget (widget:tickets, origen widget_button o ai_escalation), y clientes de la API admin (write:tickets, origen api) que canalizan tickets desde otros canales. Encola ticket.created, notifica al owner por email y deduplica con Idempotency-Key (TTL 24 h). Sujeto a topes de plan (Free 20/mes, Starter 200/mes, Pro ilimitado; 402 limit_reached al exceder).
• GET /v1/tickets — lista paginada (read:tickets). status y priority son multi-valor (repetir el parámetro hace OR). Opt-in ?include=total_count añade meta.pagination.total_count.
• GET /v1/tickets/{public_id} — devuelve el ticket con su hilo completo de mensajes y eventos (read:tickets).
• PATCH /v1/tickets/{public_id} — actualización parcial (write:tickets): status, assigned_to (UID de miembro o null), tags (reemplaza la lista completa), metadata (merge superficial).
• POST /v1/tickets/{public_id}/resolve — atajo a PATCH con status:"resolved". Sella resolved_at, emite ticket.resolved, idempotente.
• POST /v1/tickets/{public_id}/reopen — atajo a PATCH con status:"open". Limpia resolved_at, emite ticket.status.changed.
• POST /v1/tickets/{public_id}/messages — añade un mensaje al hilo. author_type se infiere del contexto de auth (admin → member, widget → visitor). Una respuesta de miembro sobre un ticket open lo pasa a pending_user y sella first_response_at.
• DELETE /v1/tickets/{public_id} — derecho de supresión GDPR: anonimiza la PII (nombre, email y cuerpos de mensaje pasan a [deleted]); preserva ticket_events. Idempotente, mismo patrón que DELETE /v1/leads/{lead_id}.

Webhook events nuevos (4):

• ticket.created — se creó un ticket.
• ticket.status.changed — cambió el estado del ticket (incluye reaperturas).
• ticket.resolved — el ticket pasó a resolved.
• ticket.message.created — se añadió un mensaje al hilo.

Referencia completa: Tickets en la referencia REST y la guía del panel Tickets.

SDK @lectico/api: los helpers lectico.tickets.* se publicarán en el siguiente release del SDK.

v1 (0.2.1-beta) — 2026-04-13 (REQ-095: ingesta bulk multi-URL)

Add-only. Un endpoint nuevo.

API:

• POST /v1/agents/{agent_id}/knowledge/batch — nuevo endpoint para ingestar hasta 500 URLs en una sola llamada. Las URLs pasan por el mismo pipeline que el endpoint individual (scrape, generación de categorías con IA, Q&A, vectorización). Procesamiento serial por agente: la primera URL establece la estructura de categorías, las siguientes distribuyen sus Q&A. Útil para documentación multi-página, help centers o migraciones desde otra plataforma.

Sin cambios en endpoints existentes. El ingest individual POST /v1/agents/{id}/knowledge type:"url" sigue igual y usa el mismo pipeline; la diferencia es que /batch ahorra 1 request por URL y garantiza orden serial.

SDK: @lectico/api@0.2.1-beta — pendiente release. El helper lectico.agents.knowledge.createBatch(agentId, { urls }) se publicará tras el siguiente release del SDK.

v1 (0.2.0-beta) — 2026-04-13 (REQ-092: paridad con admin)

Add-only sobre 0.1.0-beta. Cero breaking changes en endpoints existentes — solo se añaden 26 endpoints nuevos y campos adicionales al shape de KnowledgeSource.

API — 26 endpoints añadidos (total 53):

• Imagen (REQ-092.1): POST /v1/agents/{id}/knowledge type:"file_id" ahora procesa imágenes (PNG, JPG, WEBP) con OCR por IA.
• CSV Q&A (REQ-092.2): POST /v1/agents/{id}/knowledge acepta type:"csv_qa" con content (CSV plano, max 1 MB) para importar Q&A pre-formuladas sin pasar por el pipeline de IA.
• Status enriquecido (REQ-092.3): el shape de knowledge source incluye ahora phase, progress, attempts, next_attempt_at para client UX (progress bars, spinners).
• Files confirm: POST /v1/files/{id}/confirm flippea status a uploaded tras el PUT de bytes.
• Q&A management (REQ-092.4, 9 endpoints): /v1/agents/{id}/qa (CRUD + /regenerate async) y /v1/agents/{id}/categories (CRUD).
• Training agents (REQ-092.5, 12 endpoints): /v1/agents/{id}/modules, /lessons y /sources con jerarquía explícita. Solo agentes type:"training".
• Glossary (REQ-092.6, 5 endpoints): /v1/agents/{id}/glossary con PUT lista completa, POST /terms, DELETE /terms/{term}, PATCH flags.

Webhook events nuevos:

• qa.regenerated — POST /qa/regenerate terminó.
• course.lesson.source.indexed — lesson source listo (training).
• course.lesson.source.failed — lesson source falló.

SDK @lectico/api v0.2.0-beta:

• 3 recursos nuevos: lectico.qa, lectico.training, lectico.glossary.
• lectico.knowledge.get(agentId, sourceId) y lectico.knowledge.waitUntilDone(...) para polling.
• lectico.training.waitUntilDone(...).
• lectico.files.confirm(id).
• KnowledgeCreateInput ahora discrimina por type: text | url | file_id | csv_qa.

npm install @lectico/api@beta

Limitaciones documentadas:

• Imagen >= 4 MB usa un flujo interno alternativo (transparente para el cliente).
• Audio en lecciones puede tardar hasta 10 min según duración.
• Training agents: is_primary se asigna al primer source de la lección automáticamente; no hay endpoint para cambiarlo.

v1 (0.1.0-beta) — 2026-04-13

Lanzamiento inicial de la API pública y del SDK de Node.

API

• 26 endpoints bajo /v1/* cubriendo agentes, mensajes, conocimiento, conversaciones, leads, webhooks, files y usage.
• Autenticación con claves sk_live_* y sk_test_* vía Authorization: Bearer.
• Cabecera legacy x-api-key soportada por compatibilidad.
• Formato de error uniforme (RFC 7807-inspired) con request_id en cada respuesta.
• Paginación por cursor (starting_after, has_more, next_cursor).
• Idempotencia en todos los POST vía Idempotency-Key (TTL 24 h).
• Rate limits explícitos vía cabeceras X-RateLimit-*.
• Streaming SSE en POST /v1/agents/{id}/messages.
• Webhooks firmados con HMAC-SHA256 (formato t=...,v1=...) y protección contra replay (tolerancia 5 min).

SDK @lectico/api v0.1.0

• Recursos: agents, knowledge, conversations, leads, webhooks, files, usage.
• agents.messages.create con streaming (default) o JSON (stream: false).
• iterAll para auto-paginación.
• constructEvent para verificar firmas de webhook.
• Clases de error tipadas: AuthenticationError, NotFoundError, ConflictError, InvalidRequestError, RateLimitError, PaymentRequiredError, PermissionDeniedError, InternalServerError.
• Reintentos automáticos en 429 y 5xx con backoff exponencial.
• Cero dependencias runtime. ESM only. Node 18+.
• npm · GitHub