Référence API (OpenAPI 3.1)

AskAIs Customer Service fournit une spécification OpenAPI 3.1complète décrivant chaque point de terminaison public. Elle alimente nos SDK générés automatiquement et fonctionne avec n'importe quel outil de l'écosystème OpenAPI (Insomnia, Postman, Swagger UI, Hoppscotch, etc.).

Obtenir la spécification

# 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 de base

• Cloud : https://cs.askais.com/api/v1
• Auto-hébergé : l'adresse vers laquelle pointe votre APP_URL, suffixée par /api/v1

Authentification

Deux schémas, tous deux via Authorization: Bearer <value> :

• JWT de contact — émis par POST /auth/identify. Limité à un seul contact. Utilisé par les SDK web / mobiles.
• Clé API d'espace de travail — sk_live_..., générée dans Paramètres → API Keys. Couvre l'ensemble de l'espace de travail. Pour le serveur à serveur.

Points de terminaison en un coup d'œil

• POST /auth/identify — émettre un JWT de contact
• POST /conversations — démarrer une nouvelle conversation
• GET /conversations — lister les vôtres
• GET /conversations/{id}
• GET /conversations/{id}/messages?before=&limit=
• POST /conversations/{id}/messages
• POST /upload — obtenir une URL POST S3 présignée
• POST /upload/{id}/confirm

Erreurs

Toutes les réponses non-2xx utilisent une enveloppe stable :

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

Codes : validation_error, unauthorized, forbidden, not_found, conflict, unprocessable, rate_limit_exceeded, internal_error.

Compagnon temps réel

REST convient aux appels ponctuels. Pour les messages en direct, connectez-vous à wss://<wsUrl>/v1/ws?token=<jwt> et écoutez les événements message:new, ai:stream:delta, ai:stream:end, typing et presence. Voir Widget web pour le schéma complet des événements.