Prompt Templates - CUIDO Backend

Overview

Prompt templates define the system instructions and structure for AI chat completions. They allow administrators to create reusable, specialized prompts for different use cases like HR analysis, quality improvement, or general assistance.

Authentication

All prompt endpoints require authentication. Admin-only operations are marked.

Authorization: Bearer YOUR_JWT_TOKEN

List Prompt Templates

Get a paginated list of active prompt templates with optional filtering.

Endpoint

GET /api/prompts

Query Parameters

page

number

Page number for pagination. Default: 1

limit

number

Number of templates per page. Default: 10

category

string

Filter by category. Options: analysis, creative, technical, business, educational, general

tags

string

Filter by tags (comma-separated). Example: healthcare,analytics

string

Search in name or description (max 100 characters)

Response

success

boolean

Indicates if the request was successful

data.prompts

array

Array of prompt template objects

Show prompt properties

_id

string

Template unique identifier

name

string

Template name

description

string

Template description

category

string

Template category

tags

array

Array of tag strings

usageCount

number

Number of times this template has been used

isDefault

boolean

Whether this is a default system template

createdBy

object

Populated user information (name, email)

createdAt

string

ISO 8601 timestamp of creation

data.pagination

object

Pagination metadata

Show pagination properties

page

number

Current page number

limit

number

Items per page

total

number

Total number of templates

pages

number

Total number of pages

hasNext

boolean

Whether there’s a next page

hasPrev

boolean

Whether there’s a previous page

Sorting

Templates are sorted by:

isDefault (default templates first)
usageCount (most used first)
createdAt (most recent first)

Examples

curl -X GET "https://api.cuido.com/api/prompts?page=1&limit=10" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Response Example

{
  "success": true,
  "message": "Plantillas obtenidas exitosamente",
  "data": {
    "prompts": [
      {
        "_id": "65a1b2c3d4e5f6a7b8c9d0e1",
        "name": "Análisis de RRHH en Salud",
        "description": "Plantilla especializada para analizar métricas de recursos humanos en hospitales rurales",
        "category": "analysis",
        "tags": ["healthcare", "hr", "analytics"],
        "usageCount": 247,
        "isDefault": true,
        "createdBy": {
          "_id": "65a1b2c3d4e5f6a7b8c9d0e0",
          "name": "System Admin",
          "email": "[email protected]"
        },
        "createdAt": "2024-01-01T00:00:00.000Z"
      },
      {
        "_id": "65a1b2c3d4e5f6a7b8c9d0e2",
        "name": "Mejora de Calidad Asistencial",
        "description": "Genera recomendaciones para mejorar indicadores de calidad hospitalaria",
        "category": "business",
        "tags": ["quality", "improvement", "patient-care"],
        "usageCount": 189,
        "isDefault": true,
        "createdBy": {
          "_id": "65a1b2c3d4e5f6a7b8c9d0e0",
          "name": "System Admin",
          "email": "[email protected]"
        },
        "createdAt": "2024-01-01T00:00:00.000Z"
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 10,
      "total": 15,
      "pages": 2,
      "hasNext": true,
      "hasPrev": false
    }
  }
}

Get Single Template

Retrieve complete details of a specific prompt template.

Endpoint

GET /api/prompts/:id

Path Parameters

string

required

MongoDB ObjectId of the template

Response

data.prompt

object

Complete template object including template and systemInstructions fields

Example

curl -X GET https://api.cuido.com/api/prompts/65a1b2c3d4e5f6a7b8c9d0e1 \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Response Example

{
  "success": true,
  "message": "Plantilla obtenida exitosamente",
  "data": {
    "prompt": {
      "_id": "65a1b2c3d4e5f6a7b8c9d0e1",
      "name": "Análisis de RRHH en Salud",
      "description": "Plantilla especializada para analizar métricas de recursos humanos en hospitales rurales",
      "template": "Analiza las siguientes métricas de recursos humanos:\n- Motivación promedio\n- Satisfacción del personal\n- Riesgo de fuga\n- Horas de capacitación\n\nGenera recomendaciones concretas y priorizadas.",
      "systemInstructions": "Eres un experto en gestión de recursos humanos en el sector salud rural. Tu objetivo es proporcionar análisis basados en datos y recomendaciones prácticas que puedan implementarse en hospitales con recursos limitados.",
      "category": "analysis",
      "tags": ["healthcare", "hr", "analytics"],
      "isDefault": true,
      "isActive": true,
      "usageCount": 247,
      "createdBy": {
        "_id": "65a1b2c3d4e5f6a7b8c9d0e0",
        "name": "System Admin",
        "email": "[email protected]"
      },
      "createdAt": "2024-01-01T00:00:00.000Z",
      "updatedAt": "2024-01-15T10:30:00.000Z"
    }
  }
}

Create Template

Create a new custom prompt template. Admin only.

Endpoint

POST /api/prompts

Request Body

name

string

required

Template name. Must be 3-100 characters and unique.

description

string

required

Template description. Must be 10-500 characters.

template

string

required

The prompt template content. Must be 20-2000 characters.

systemInstructions

string

required

System-level instructions for the AI. Must be 20-1000 characters.

category

string

required

Template category. Options: analysis, creative, technical, business, educational, general

tags

array

Array of tag strings (max 10 tags, each max 30 characters). Tags are automatically lowercased.

Response

data.prompt

object

The created template object with _id and timestamps

Example

curl -X POST https://api.cuido.com/api/prompts \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Análisis de Rotación de Personal",
    "description": "Analiza patrones de rotación de personal y genera estrategias de retención",
    "template": "Analiza los siguientes datos de rotación:\n- Tasa de rotación mensual\n- Departamentos más afectados\n- Razones de salida\n\nProporciona estrategias específicas de retención.",
    "systemInstructions": "Eres un consultor experto en retención de talento en el sector salud. Proporciona análisis basados en datos y recomendaciones accionables.",
    "category": "analysis",
    "tags": ["hr", "retention", "turnover"]
  }'

Response Example

{
  "success": true,
  "message": "Plantilla creada exitosamente",
  "data": {
    "prompt": {
      "_id": "65a1b2c3d4e5f6a7b8c9d0e9",
      "name": "Análisis de Rotación de Personal",
      "description": "Analiza patrones de rotación de personal y genera estrategias de retención",
      "template": "Analiza los siguientes datos de rotación:\n- Tasa de rotación mensual\n- Departamentos más afectados\n- Razones de salida\n\nProporciona estrategias específicas de retención.",
      "systemInstructions": "Eres un consultor experto en retención de talento en el sector salud. Proporciona análisis basados en datos y recomendaciones accionables.",
      "category": "analysis",
      "tags": ["hr", "retention", "turnover"],
      "isDefault": false,
      "isActive": true,
      "usageCount": 0,
      "createdBy": "65a1b2c3d4e5f6a7b8c9d0e0",
      "createdAt": "2024-01-15T14:30:00.000Z",
      "updatedAt": "2024-01-15T14:30:00.000Z"
    }
  }
}

Update Template

Update an existing template. Admin only. Only the creator can update their templates.

Endpoint

PUT /api/prompts/:id

Path Parameters

string

required

MongoDB ObjectId of the template to update

Request Body

All fields are optional. Only provided fields will be updated.

name

string

New template name (3-100 characters)

description

string

New description (10-500 characters)

template

string

New template content (20-2000 characters)

systemInstructions

string

New system instructions (20-1000 characters)

category

string

New category

tags

array

New tags array

Example

curl -X PUT https://api.cuido.com/api/prompts/65a1b2c3d4e5f6a7b8c9d0e9 \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "Analiza patrones de rotación de personal, identifica causas raíz y genera estrategias específicas de retención",
    "tags": ["hr", "retention", "turnover", "analytics"]
  }'

Delete Template

Soft-delete a template by marking it as inactive. Admin only. Only the creator can delete their templates.

Endpoint

DELETE /api/prompts/:id

Path Parameters

string

required

MongoDB ObjectId of the template to delete

Response

{
  "success": true,
  "message": "Plantilla eliminada exitosamente"
}

Example

curl -X DELETE https://api.cuido.com/api/prompts/65a1b2c3d4e5f6a7b8c9d0e9 \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Error Responses

400 Bad Request
401 Unauthorized
403 Forbidden
404 Not Found

{
  "success": false,
  "message": "Validation error",
  "errors": [
    {
      "field": "name",
      "message": "El nombre debe tener al menos 3 caracteres"
    }
  ]
}

{
  "success": false,
  "message": "No autorizado. Token inválido o expirado."
}

{
  "success": false,
  "message": "Acceso denegado. Requiere rol de administrador."
}

{
  "success": false,
  "message": "Plantilla no encontrada o sin permisos"
}

Template Categories

Category	Use Case
`analysis`	Data analysis, metrics interpretation, strategic insights
`creative`	Brainstorming, idea generation, creative solutions
`technical`	Technical documentation, troubleshooting, procedures
`business`	Business strategy, process improvement, operations
`educational`	Training content, learning materials, explanations
`general`	General-purpose assistance, miscellaneous queries

Best Practices

Clear System Instructions
- Define the AI’s role and expertise
- Specify tone and style expectations
- Include output format requirements
Effective Template Structure
- Use clear sections and bullet points
- Provide context for the AI
- Include examples if helpful
Descriptive Naming
- Use specific, searchable names
- Include the domain (e.g., “RRHH”, “Calidad”)
- Keep names under 50 characters
Relevant Tags
- Use 3-5 meaningful tags
- Include domain, function, and type tags
- Use lowercase for consistency
Regular Updates
- Review usage metrics
- Update based on user feedback
- Deprecate unused templates

Usage Tracking

Each template tracks usageCount which increments every time it’s used in a chat completion. This helps identify:

Most popular templates
Templates needing improvement
Unused templates to deprecate

Source Code References

Routes: src/routes/promptRoutes.js
Controllers: src/controllers/promptController.js
Service: src/services/promptService.js
Model: src/models/PromptTemplate.js
Validation: src/routes/promptRoutes.js:24

Authentication

Employees

Diagnostic Module

Mentorship Module

Microlearning Module

Recognition Module

Correlation Module

Chat & Prompts

​Overview

​Authentication

​List Prompt Templates

​Endpoint

​Query Parameters

​Response

​Sorting

​Examples

​Response Example

​Get Single Template

​Endpoint

​Path Parameters

​Response

​Example

​Response Example

​Create Template

​Endpoint

​Request Body

​Response

​Example

​Response Example

​Update Template

​Endpoint

​Path Parameters

​Request Body

​Example

​Delete Template

​Endpoint

​Path Parameters

​Response

​Example

​Error Responses

​Template Categories

​Best Practices

​Usage Tracking

​Source Code References

Build docs developers (and LLMs) love

Overview

Authentication

List Prompt Templates

Endpoint

Query Parameters

Response

Sorting

Examples

Response Example

Get Single Template

Endpoint

Path Parameters

Response

Example

Response Example

Create Template

Endpoint

Request Body

Response

Example

Response Example

Update Template

Endpoint

Path Parameters

Request Body

Example

Delete Template

Endpoint

Path Parameters

Response

Example

Error Responses

Template Categories

Best Practices

Usage Tracking

Source Code References