Referencia de la API (OpenAPI 3.1)

AskAIs Customer Service incluye una especificación OpenAPI 3.1 completa que describe cada endpoint público. Es la base de nuestros SDK generados automáticamente y funciona con cualquier herramienta del ecosistema OpenAPI (Insomnia, Postman, Swagger UI, Hoppscotch, etc.).

Obtener la especificación

# Live (cached 5 min, CORS open)
curl https://cs.askais.com/api/v1/openapi.json

# Save to disk
curl https://cs.askais.com/api/v1/openapi.json -o singlink-openapi.json

URL base

• Nube: https://cs.askais.com/api/v1
• Autoalojado: la dirección a la que resuelve tu APP_URL, con el sufijo /api/v1

Autenticación

Dos esquemas, ambos mediante Authorization: Bearer <value>:

• JWT de contacto — emitido por POST /auth/identify. Limitado a un solo contacto. Usado por los SDK web / móviles.
• Clave de API del espacio de trabajo — sk_live_..., generada en Ajustes → API Keys. Abarca todo el espacio de trabajo. Para servidor a servidor.

Endpoints de un vistazo

• POST /auth/identify — emitir un JWT de contacto
• POST /conversations — iniciar un nuevo chat
• GET /conversations — listar los tuyos
• GET /conversations/{id}
• GET /conversations/{id}/messages?before=&limit=
• POST /conversations/{id}/messages
• POST /upload — obtener una URL POST S3 prefirmada
• POST /upload/{id}/confirm

Errores

Todas las respuestas que no son 2xx usan un sobre estable:

{
  "error": {
    "code": "validation_error",
    "message": "content or attachments required",
    "field": "content"
  }
}

Códigos: validation_error, unauthorized, forbidden, not_found, conflict, unprocessable, rate_limit_exceeded, internal_error.

Complemento en tiempo real

REST está bien para llamadas puntuales. Para mensajes en vivo, conéctate a wss://<wsUrl>/v1/ws?token=<jwt> y escucha los eventos message:new, ai:stream:delta, ai:stream:end, typing y presence. Consulta Widget web para el esquema completo de eventos.