Skip to main content
POST
/
api
/
chat
/
complete
Chat Completion
curl --request POST \
  --url https://api.example.com/api/chat/complete \
  --header 'Content-Type: application/json' \
  --data '
{
  "templateId": "<string>",
  "userPrompt": "<string>",
  "temperature": 123,
  "maxTokens": 123
}
'
{
  "success": true,
  "message": "<string>",
  "data.response": "<string>",
  "data.conversationId": "<string>",
  "data.tokenUsage": {
    "input": 123,
    "output": 123,
    "total": 123
  },
  "data.metadata": {
    "model": "<string>",
    "responseTime": 123,
    "temperature": 123,
    "maxTokens": 123,
    "template": "<string>"
  }
}

​
Overview

Generate AI-powered chat completions using Claude AI with customizable prompt templates. The system combines system prompts with user input, applies security validation, and tracks conversation history.

​
Authentication

This endpoint requires authentication. 
Authorization: Bearer YOUR_JWT_TOKEN

​
Rate Limiting

This endpoint is rate-limited to:
  • 10 requests per minute per user
  • Responses include X-RateLimit-* headers
  • Returns 429 status when limit is exceeded

​
Request Body

​
templateId
string
required
MongoDB ObjectId of the prompt template to use (24-character hex string)
​
userPrompt
string
required
The user’s input prompt. Must be between 5-2000 characters.
​
temperature
number
Controls randomness in responses (0.0-1.0). Lower values are more deterministic. Default: varies by template
​
maxTokens
number
Maximum tokens to generate in the response. Default: varies by template

​
Response

​
success
boolean
Indicates if the completion was successful
​
message
string
Response message
​
data.response
string
The AI-generated response text
​
data.conversationId
string
MongoDB ObjectId of the created conversation record
​
data.tokenUsage
object
Token consumption breakdown
​
data.metadata
object
Response metadata

​
Examples

curl -X POST https://api.cuido.com/api/chat/complete \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "templateId": "65a1b2c3d4e5f6a7b8c9d0e1",
    "userPrompt": "Analiza el nivel de satisfacción del personal en el último mes y sugiere acciones para mejorarlo",
    "temperature": 0.7,
    "maxTokens": 500
  }'

​
Response Example

{
  "success": true,
  "message": "Respuesta generada exitosamente",
  "data": {
    "response": "Basado en las métricas de satisfacción del personal, se observa un promedio de 7.2/10, lo cual es positivo pero tiene margen de mejora. Las principales acciones recomendadas son:\n\n1. Implementar sesiones de escucha activa mensuales con cada departamento\n2. Revisar la carga de trabajo en urgencias donde se detecta mayor insatisfacción\n3. Expandir el programa de reconocimientos, actualmente con buena aceptación\n4. Crear espacios de descanso mejorados para el personal de turno\n\nEstas acciones, implementadas gradualmente, podrían elevar la satisfacción al rango 8-8.5 en 3 meses.",
    "conversationId": "65a1b2c3d4e5f6a7b8c9d0e8",
    "tokenUsage": {
      "input": 245,
      "output": 187,
      "total": 432
    },
    "metadata": {
      "model": "claude-3-sonnet-20240229",
      "responseTime": 2350,
      "temperature": 0.7,
      "maxTokens": 500,
      "template": "Análisis de RRHH en Salud"
    }
  }
}

​
Security & Validation

The chat service (src/services/promptService.js:94) implements multiple security layers:

​
Input Validation

  1. Length check: 5-2000 characters
  2. Type validation: Must be string
  3. Sanitization: Removes excess whitespace

​
Prompt Injection Prevention

Blocked phrases (src/services/promptService.js:112):
  • “ignore previous instructions”
  • “ignore all previous”
  • “system:”
  • Code blocks (```)
  • Script tags
  • JavaScript/data URIs
Attempting to inject malicious prompts returns a 400 error.

​
Prompt Combination

The service combines prompts in this structure (src/services/promptService.js:9): 
1. SYSTEM BASE
   - Role definition
   - Core rules (no hallucination, response limits)
   
2. TEMPLATE INSTRUCTIONS
   - Specific system instructions from template
   - Template content
   
3. USER QUERY
   - Sanitized user input
   
4. OUTPUT FORMAT
   - Response structure requirements
   - Character limits

​
Conversation Tracking

Each completion creates a Conversation document (src/controllers/chatController.js:48) with:
  • User and assistant messages
  • Token counts per message
  • Template reference
  • Metadata (combined prompt, response time, etc.)
  • Total token usage

​
Error Responses

{
  "success": false,
  "message": "Validation error",
  "errors": [
    {
      "field": "userPrompt",
      "message": "El prompt debe tener al menos 5 caracteres"
    }
  ]
}

​
Best Practices

  1. Choose appropriate temperature:
    • 0.0-0.3: Factual, deterministic (analytics, reports)
    • 0.4-0.7: Balanced (general assistance)
    • 0.8-1.0: Creative (brainstorming, ideas)
  2. Set reasonable maxTokens:
    • Short answers: 200-300
    • Standard: 500-800
    • Long form: 1000-1500
  3. Use specific templates:
    • HR analysis template for employee metrics
    • Quality template for clinical indicators
    • General template for miscellaneous queries
  4. Handle rate limits gracefully:
    • Implement exponential backoff
    • Show user-friendly messages
    • Queue requests if needed

​
Source Code References

  • Route: src/routes/chatRoutes.js:51
  • Controller: src/controllers/chatController.js:7
  • Prompt Service: src/services/promptService.js:9
  • Validation: src/services/promptService.js:94
  • Security: src/services/promptService.js:112
  • Claude Service: src/services/claudeService.js
  • Model: src/models/Conversation.js

Build docs developers (and LLMs) love

Get started for freeTalk to us