Referência da API (OpenAPI 3.1)

O AskAIs Customer Service fornece uma especificação OpenAPI 3.1 completa que descreve cada endpoint público. Ela alimenta nossos SDKs gerados automaticamente e funciona com qualquer ferramenta do ecossistema OpenAPI (Insomnia, Postman, Swagger UI, Hoppscotch, etc.).

Obter a especificação

# 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

• Nuvem: https://cs.askais.com/api/v1
• Auto-hospedado: o endereço para o qual sua APP_URL resolve, com o sufixo /api/v1

Autenticação

Dois esquemas, ambos via Authorization: Bearer <value>:

• JWT de contato — emitido por POST /auth/identify. Restrito a um único contato. Usado pelos SDKs web / móveis.
• Chave de API do espaço de trabalho — sk_live_..., gerada em Configurações → API Keys. Abrange todo o espaço de trabalho. Para servidor a servidor.

Endpoints em resumo

• POST /auth/identify — emitir um JWT de contato
• POST /conversations — iniciar um novo chat
• GET /conversations — listar os seus
• GET /conversations/{id}
• GET /conversations/{id}/messages?before=&limit=
• POST /conversations/{id}/messages
• POST /upload — obter uma URL POST S3 pré-assinada
• POST /upload/{id}/confirm

Erros

Todas as respostas não-2xx usam um envelope estável:

{
  "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.

Companheiro em tempo real

O REST é adequado para chamadas pontuais. Para mensagens ao vivo, conecte-se a wss://<wsUrl>/v1/ws?token=<jwt> e ouça os eventos message:new, ai:stream:delta, ai:stream:end, typing e presence. Consulte Widget web para o esquema completo de eventos.