Chat API

Envía mensajes a tus minds y recibe respuestas generadas por IA. La Chat API soporta tanto completions sin estado como conversaciones multi-turn con estado, con gestión automática del historial.

Chats con estado (recomendado)

Crea conversaciones persistentes en las que el servidor gestiona automáticamente el historial, la compresión de contexto y los resúmenes rodantes. No hace falta enviar el historial completo de mensajes en cada solicitud.

Crear un Chat

Crea una nueva conversación con estado vinculada a un mind.

Endpoint: POST /api/v1/chats

Headers:

Authorization: Bearer minds_your_api_key
Content-Type: application/json

Request body:

{
  "name": "My Conversation",
  "sparkId": "your-spark-id"
}

Respuesta (201):

{
  "data": {
    "id": "601af953-3837-49c1-a31e-4fdbfa82ac04",
    "name": "My Conversation",
    "description": null,
    "createdAt": "2026-04-04T12:45:24.078Z",
    "sparks": [
      {
        "id": "4774888e-0a03-40d7-979b-39b47c4c049c",
        "name": "Ada Lovelace",
        "discipline": "mathematician and computer scientist"
      }
    ]
  }
}

Enviar un mensaje

Envía un mensaje a un chat existente. El servidor gestiona automáticamente el historial de conversación, la compresión de la ventana de contexto y los resúmenes rodantes.

Endpoint: POST /api/v1/chats/{chatId}/messages

Headers:

Authorization: Bearer minds_your_api_key
Content-Type: application/json

Request body:

{
  "content": "What are the latest advancements in solar panel technology?"
}

La selección de modelo en chat con estado sigue este orden: override por solicitud, luego el proveedor preferido del equipo si está configurado y es elegible, y después el valor predeterminado del producto. En este endpoint, los overrides parciales se rechazan con 400 Bad Request; envía model y provider juntos u omite ambos.

Respuesta:

{
  "content": "Recent advancements in solar panel technology include perovskite cells with 30%+ efficiency...",
  "messageId": "cmnkbsddh00033v01ptk9t4et"
}

Ejemplo multi-turn

Con chats con estado, solo envías el mensaje nuevo cada vez. El servidor lo recuerda todo:

# Step 1: Create a chat
CHAT=$(curl -s -X POST "https://getminds.ai/api/v1/chats" \
  -H "Authorization: Bearer minds_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Research Session", "sparkId": "your-spark-id" }')

CHAT_ID=$(echo $CHAT | jq -r '.data.id')

# Step 2: Send messages (server manages history automatically)
curl -X POST "https://getminds.ai/api/v1/chats/$CHAT_ID/messages" \
  -H "Authorization: Bearer minds_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{ "content": "What are the top marketing trends?" }'

# Step 3: Follow up (the mind remembers the previous exchange)
curl -X POST "https://getminds.ai/api/v1/chats/$CHAT_ID/messages" \
  -H "Authorization: Bearer minds_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{ "content": "Which of those would work best on a small budget?" }'

Cómo funciona por debajo:

• Cada mensaje se persiste en base de datos
• Los últimos 8 mensajes se envían con contexto completo
• Los mensajes más antiguos se comprimen en un resumen rodante generado por LLM
• Las conversaciones pueden durar semanas o meses sin chocar con los límites de contexto

Completions sin estado

Para solicitudes puntuales o cuando quieres gestionar tú mismo el historial de conversación.

Send Message

Envía mensajes a un mind y recibe respuestas.

Endpoint: POST /api/v1/sparks/{sparkId}/completion

Headers:

Authorization: Bearer minds_your_api_key
Content-Type: application/json

Request body

{
  "messages": [
    {
      "role": "user",
      "content": "What are the latest advancements in solar panel technology?"
    }
  ]
}

Parámetros

Respuesta

{
  "messageId": "msg_550e840029b141d4a716446655440000",
  "content": "Recent advancements in solar panel technology include perovskite cells with 30%+ efficiency, bifacial panels that capture light from both sides, and integrated storage systems...",
  "metadata": {
    "ragCitations": [
      {
        "id": "abc123",
        "displaySource": "Spark knowledge",
        "similarity": 0.89
      }
    ]
  }
}

Ejemplo de mensaje único

Haz una única pregunta:

curl -X POST "https://getminds.ai/api/v1/sparks/spark-id/completion" \
  -H "Authorization: Bearer minds_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      {
        "role": "user",
        "content": "What are the top 3 marketing trends for 2025?"
      }
    ]
  }'

Conversación multi-turn

Mantén el contexto de la conversación incluyendo los mensajes previos:

curl -X POST "https://getminds.ai/api/v1/sparks/spark-id/completion" \
  -H "Authorization: Bearer minds_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      {
        "role": "user",
        "content": "What are the top marketing trends?"
      },
      {
        "role": "assistant",
        "content": "The top trends are AI personalization, short-form video, and community building..."
      },
      {
        "role": "user",
        "content": "How can I implement AI personalization on a budget?"
      }
    ]
  }'

Tips para conversaciones multi-turn:

• Incluye el historial completo de la conversación en cada solicitud
• El orden importa: los mensajes deben ir en orden cronológico
• Alterna entre los roles user y assistant
• El último mensaje siempre debe ser de user

File attachments

Adjunta archivos, documentos, imágenes y links para aportar contexto a tus minds. Los minds reciben el contenido procesado como parte de la conversación.

Adjuntar archivos

Añade archivos vía el array metadata.attachedFiles en tu mensaje de user:

curl -X POST "https://getminds.ai/api/v1/sparks/spark-id/completion" \
  -H "Authorization: Bearer minds_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      {
        "role": "user",
        "content": "Please review this document and summarize the key points",
        "metadata": {
          "attachedFiles": [
            {
              "url": "https://example.com/quarterly-report.pdf",
              "name": "Q4 2025 Report",
              "type": "application/pdf"
            },
            {
              "path": "uploads/meeting-notes.docx",
              "name": "Strategy Meeting Notes"
            }
          ]
        }
      }
    ]
  }'

Formato del adjunto

Cada objeto de adjunto admite:

Nota: Proporciona url O path, no ambos.

Tipos de archivo soportados

Documentos:

• PDF (.pdf) - Extracción de texto + OCR para páginas escaneadas
• Word (.docx) - Extracción de texto completo
• Texto (.txt, .md) - Contenido de texto directo
• CSV/Excel (.csv, .xlsx) - Extracción de tablas

Imágenes:

• PNG, JPG, WEBP - OCR + análisis visual
• Capacidades de visión para comprensión de imágenes

URLs externas:

• Páginas web obtenidas con Firecrawl (renderizado JS + screenshots)
• Conversión automática a markdown

Procesamiento

Los archivos se procesan automáticamente antes de enviarse al mind:

1. Download - Los archivos se obtienen desde URL o Supabase storage
2. Extract - Se extrae el contenido (texto de PDFs, OCR de imágenes, etc.)
3. Inject - El contenido procesado se añade al contexto de la conversación
4. Response - El mind ve tanto tu mensaje como el contenido del archivo

Límites de procesamiento:

• Timeout: 30 segundos por archivo
• Los archivos se procesan en paralelo
• Los archivos que fallan muestran mensajes de fallback con manejo elegante

Ejemplo con múltiples archivos

{
  "messages": [
    {
      "role": "user",
      "content": "Compare these two proposals and recommend which one to pursue",
      "metadata": {
        "attachedFiles": [
          {
            "url": "https://example.com/proposal-a.pdf",
            "name": "Proposal A - Cloud Migration",
            "type": "application/pdf"
          },
          {
            "url": "https://example.com/proposal-b.pdf",
            "name": "Proposal B - On-Prem Upgrade",
            "type": "application/pdf"
          },
          {
            "path": "uploads/budget-analysis.xlsx",
            "name": "Budget Comparison"
          }
        ]
      }
    }
  ]
}

File attachments en el historial de conversación

Cuando continúes una conversación con archivos adjuntos, incluye el mensaje original con los adjuntos en el historial:

{
  "messages": [
    {
      "role": "user",
      "content": "Analyze this sales data",
      "metadata": {
        "attachedFiles": [
          {
            "url": "https://example.com/sales-q4.csv",
            "name": "Q4 Sales Data"
          }
        ]
      }
    },
    {
      "role": "assistant",
      "content": "Based on the Q4 sales data, I can see that revenue increased by 23% compared to Q3..."
    },
    {
      "role": "user",
      "content": "What were the top 3 performing products?"
    }
  ]
}

Nota: Los archivos solo se procesan una vez al adjuntarse por primera vez. Los mensajes posteriores en la misma conversación referencian el contenido ya procesado.

Links web

Para páginas web y contenido externo, usa el campo url:

{
  "messages": [
    {
      "role": "user",
      "content": "Summarize the key findings from this research paper",
      "metadata": {
        "attachedFiles": [
          {
            "url": "https://arxiv.org/pdf/2103.12345.pdf",
            "name": "AI Research Paper",
            "type": "application/pdf"
          }
        ]
      }
    }
  ]
}

Para páginas web en concreto:

• Los sitios con mucho JavaScript se renderizan con Firecrawl
• Se capturan screenshots para contexto visual
• El contenido se convierte a markdown limpio

Manejo de errores

Si el procesamiento del archivo falla:

• El mind recibe un mensaje de fallback indicando que el archivo se adjuntó pero el procesamiento falló
• La conversación continúa con normalidad
• Los errores de timeout muestran [Processing timeout - file may be too large]
• Otros errores muestran [Processing failed - file uploaded but analysis unavailable]

Esto asegura que los minds sepan que hubo intentos de adjuntos aunque el procesamiento falle.

Mensaje inicial (saludo)

Si envías un array de messages vacío o no envías messages, el mind se presentará:

curl -X POST "https://getminds.ai/api/v1/sparks/spark-id/completion" \
  -H "Authorization: Bearer minds_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": []
  }'

Respuesta:

{
  "content": "Hi! I'm Sarah, a marketing director with 15 years of experience in B2B SaaS. I specialize in growth marketing and data-driven strategies. What can I help you with today?"
}

Model override

Puedes sobrescribir opcionalmente el modelo de IA usado para una solicitud de completion sin estado pasando el parámetro model. Es útil para benchmarking, optimización de costes o testeo de comportamientos de distintos modelos. Los endpoints de chat con estado y paneles validan los overrides con más rigor: envía model y provider juntos.

curl -X POST "https://getminds.ai/api/v1/sparks/spark-id/completion" \
  -H "Authorization: Bearer minds_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      {
        "role": "user",
        "content": "What are your thoughts on sustainable packaging?"
      }
    ],
    "model": "gpt-4o-mini"
  }'

Cuando no se especifica model, se usa el default del servidor.

Providers

Puedes pasar cualquier string de modelo soportado por el provider. El provider se detecta automáticamente a partir de los prefijos habituales de nombres de modelo (claude- → Anthropic, gemini- → Google, gpt-/o1/o3/o4 → OpenAI).

Para modelos con nombres ambiguos, especifica el provider explícitamente:

{
  "messages": [...],
  "model": "my-custom-fine-tune",
  "provider": "openai"
}

Si no se puede determinar el provider, la API devuelve un error 400 Bad Request pidiéndote que lo especifiques.

Structured output

Solicita respuestas JSON garantizadas que coincidan con un schema específico usando el parámetro response_format. Sigue el patrón de structured output estilo OpenAI y es útil para extraer datos estructurados de las conversaciones.

JSON Schema Mode

Fuerza al modelo a producir un JSON válido que coincida con tu schema:

curl -X POST "https://getminds.ai/api/v1/sparks/spark-id/completion" \
  -H "Authorization: Bearer minds_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      {
        "role": "user",
        "content": "Analyze the sentiment of this text: I love this product, it exceeded all my expectations!"
      }
    ],
    "response_format": {
      "type": "json_schema",
      "json_schema": {
        "name": "sentiment_analysis",
        "description": "Sentiment analysis result",
        "schema": {
          "type": "object",
          "properties": {
            "sentiment": {
              "type": "string",
              "enum": ["positive", "negative", "neutral"]
            },
            "confidence": {
              "type": "number",
              "minimum": 0,
              "maximum": 1
            },
            "keywords": {
              "type": "array",
              "items": { "type": "string" }
            }
          },
          "required": ["sentiment", "confidence", "keywords"]
        }
      }
    }
  }'

Respuesta:

{
  "content": "{\"sentiment\": \"positive\", \"confidence\": 0.95, \"keywords\": [\"love\", \"exceeded\", \"expectations\"]}",
  "parsed": {
    "sentiment": "positive",
    "confidence": 0.95,
    "keywords": ["love", "exceeded", "expectations"]
  }
}

JSON Object Mode

Fuerza output JSON sin validación de schema:

curl -X POST "https://getminds.ai/api/v1/sparks/spark-id/completion" \
  -H "Authorization: Bearer minds_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      {
        "role": "user",
        "content": "List 3 marketing ideas as JSON"
      }
    ],
    "response_format": {
      "type": "json_object"
    }
  }'

Tipos de Response Format

Campos de JSON Schema

Funcionalidades de Schema soportadas

Se soportan las siguientes funcionalidades de JSON Schema:

• Tipos: string, number, integer, boolean, array, object, null
• Restricciones: enum, minimum, maximum, minLength, maxLength, minItems, maxItems
• Estructura: properties, required, items, additionalProperties
• Metadatos: description (usado para guiar al modelo)

Notas

• Los tools (RAG, web search, etc.) funcionan con structured output — el mind puede seguir buscando en su knowledge base antes de generar la respuesta estructurada
• El campo parsed contiene el objeto JSON parseado por conveniencia; content contiene el string JSON en bruto
• Todos los providers principales (OpenAI, Anthropic, Google) soportan structured output
• Para schemas complejos, considera añadir campos description para guiar el output del modelo

Tool calling

Permite a los minds llamar a tus funciones personalizadas durante las conversaciones. Sigue el patrón de function calling compatible con OpenAI y te permite extender las capacidades de los minds con tools y APIs externas.

Cómo funciona

1. Define tools: Pasa definiciones de tools con nombres, descripciones y parámetros en JSON Schema
2. El mind decide: El mind determina cuándo llamar a tus tools en función de la conversación (o lo fuerzas con tool_choice)
3. La API devuelve tool calls: La respuesta incluye tool_calls con el nombre de la tool y los argumentos generados
4. Ejecuta los tools: Ejecutas los tools en tu aplicación y obtienes los resultados
5. Envía los resultados de vuelta: Incluye los resultados del tool en el siguiente mensaje con role: "tool"
6. El mind responde: El mind incorpora los resultados del tool en su respuesta final

Ejemplo básico

Solicitud con tools:

curl -X POST "https://getminds.ai/api/v1/sparks/spark-id/completion" \
  -H "Authorization: Bearer minds_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      {
        "role": "user",
        "content": "What is the weather in Berlin?"
      }
    ],
    "tools": [
      {
        "name": "get_weather",
        "description": "Get current weather for a city",
        "parameters": {
          "type": "object",
          "properties": {
            "city": {
              "type": "string",
              "description": "City name"
            },
            "units": {
              "type": "string",
              "enum": ["celsius", "fahrenheit"],
              "description": "Temperature units"
            }
          },
          "required": ["city"]
        }
      }
    ]
  }'

Respuesta:

{
  "content": "",
  "tool_calls": [
    {
      "id": "call_abc123",
      "name": "get_weather",
      "arguments": {
        "city": "Berlin",
        "units": "celsius"
      }
    }
  ]
}

Ejecuta el tool y envía los resultados de vuelta:

curl -X POST "https://getminds.ai/api/v1/sparks/spark-id/completion" \
  -H "Authorization: Bearer minds_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      {
        "role": "user",
        "content": "What is the weather in Berlin?"
      },
      {
        "role": "assistant",
        "content": "",
        "tool_calls": [
          {
            "id": "call_abc123",
            "name": "get_weather",
            "arguments": {
              "city": "Berlin",
              "units": "celsius"
            }
          }
        ]
      },
      {
        "role": "tool",
        "tool_call_id": "call_abc123",
        "content": "{\"temperature\": 18, \"condition\": \"partly cloudy\", \"humidity\": 65}"
      }
    ],
    "tools": [
      {
        "name": "get_weather",
        "description": "Get current weather for a city",
        "parameters": {
          "type": "object",
          "properties": {
            "city": { "type": "string" },
            "units": { "type": "string", "enum": ["celsius", "fahrenheit"] }
          },
          "required": ["city"]
        }
      }
    ]
  }'

Respuesta final:

{
  "content": "The current weather in Berlin is 18°C and partly cloudy, with 65% humidity."
}

Schema de definición de Tool

Cada tool debe seguir esta estructura:

{
  "name": "tool_name",
  "description": "Clear description of when and how to use this tool",
  "parameters": {
    "type": "object",
    "properties": {
      "param1": {
        "type": "string",
        "description": "What this parameter does"
      }
    },
    "required": ["param1"]
  },
  "strict": true
}

Campos obligatorios:

Campos opcionales:

Tool choice modes

Controla cuándo y cómo el mind llama a los tools usando el parámetro tool_choice:

Ejemplos:

// Let the mind decide
{
  "messages": [...],
  "tools": [...],
  "tool_choice": "auto"
}

// Force a specific tool
{
  "messages": [...],
  "tools": [...],
  "tool_choice": {
    "name": "search_database"
  }
}

// Require at least one tool call
{
  "messages": [...],
  "tools": [...],
  "tool_choice": "required"
}

Parallel tool calls

Por defecto, los minds pueden llamar a varios tools en un mismo turno para ganar eficiencia:

{
  "content": "",
  "tool_calls": [
    {
      "id": "call_1",
      "name": "get_customer",
      "arguments": { "id": "CUST-001" }
    },
    {
      "id": "call_2",
      "name": "get_customer",
      "arguments": { "id": "CUST-002" }
    }
  ]
}

Para deshabilitar las llamadas en paralelo y forzar ejecución secuencial:

{
  "messages": [...],
  "tools": [...],
  "parallel_tool_calls": false
}

Formato del mensaje de Tool

Al enviar los resultados del tool de vuelta, usa el rol tool:

{
  "role": "tool",
  "tool_call_id": "call_abc123",
  "content": "{\"result\": \"success\", \"data\": {...}}"
}

Tools internos vs tools de usuario

Minds tiene tools internos del lado del servidor que se ejecutan automáticamente:

Diferencias clave:

• Tools internos: Se ejecutan del lado del servidor; los resultados se incluyen en content y metadata. Nunca se devuelven en tool_calls.
• Tools de usuario: Se devuelven en tool_calls para que tú los ejecutes. Los resultados deben enviarse de vuelta como mensajes tool.

No puedes sobrescribir ni deshabilitar los tools internos. Los tools de usuario son aditivos — extienden las capacidades del mind.

Ejemplo multi-tool completo

Un mind asistente legal con varios tools personalizados:

curl -X POST "https://getminds.ai/api/v1/sparks/spark-id/completion" \
  -H "Authorization: Bearer minds_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      {
        "role": "user",
        "content": "Create a new case for Schmidt vs. Mueller and search for similar precedents"
      }
    ],
    "tools": [
      {
        "name": "create_case",
        "description": "Create a new legal case in the system",
        "parameters": {
          "type": "object",
          "properties": {
            "title": {
              "type": "string",
              "description": "Case title (parties involved)"
            },
            "practice_area": {
              "type": "string",
              "enum": ["corporate", "litigation", "employment", "ip"],
              "description": "Legal practice area"
            },
            "client_id": {
              "type": "string",
              "description": "Client identifier"
            }
          },
          "required": ["title", "practice_area"]
        }
      },
      {
        "name": "search_precedents",
        "description": "Search legal database for similar cases",
        "parameters": {
          "type": "object",
          "properties": {
            "keywords": {
              "type": "array",
              "items": { "type": "string" },
              "description": "Search keywords"
            },
            "practice_area": {
              "type": "string",
              "description": "Filter by practice area"
            },
            "max_results": {
              "type": "integer",
              "minimum": 1,
              "maximum": 50,
              "description": "Maximum number of results"
            }
          },
          "required": ["keywords"]
        }
      }
    ],
    "parallel_tool_calls": true
  }'

Respuesta con tool calls en paralelo:

{
  "content": "",
  "tool_calls": [
    {
      "id": "call_1",
      "name": "create_case",
      "arguments": {
        "title": "Schmidt vs. Mueller",
        "practice_area": "litigation"
      }
    },
    {
      "id": "call_2",
      "name": "search_precedents",
      "arguments": {
        "keywords": ["Schmidt", "Mueller"],
        "practice_area": "litigation",
        "max_results": 10
      }
    }
  ]
}

Buenas prácticas

1. Escribe descripciones claras: El campo description es crítico. Sé específico sobre cuándo y por qué usar cada tool.

   ❌ "description": "Search database"
   ✅ "description": "Search the legal precedents database for similar cases based on keywords and practice area"
   

2. Usa descripciones en los parámetros: Ayuda al mind a entender qué hace cada parámetro.

   "case_id": {
     "type": "string",
     "description": "Unique case identifier in format CASE-YYYY-NNNN"
   }
   

3. Apóyate en enums para valores restringidos:

   "status": {
     "type": "string",
     "enum": ["pending", "active", "closed", "archived"]
   }
   

4. Establece restricciones de validación:

   "priority": {
     "type": "integer",
     "minimum": 1,
     "maximum": 5,
     "description": "Priority level (1=lowest, 5=highest)"
   }
   

5. Activa el modo strict: Mantén strict: true (default) para asegurar que el mind genere argumentos válidos.
6. Devuelve resultados de tool estructurados: Usa JSON para los resultados de tool para facilitar su parseo:

   {
     "role": "tool",
     "tool_call_id": "call_123",
     "content": "{\"success\": true, \"case_id\": \"CASE-2026-001\", \"created_at\": \"2026-03-30T23:00:00Z\"}"
   }
   

7. Gestiona los errores con elegancia: Devuelve los detalles del error en el resultado del tool:

   {
     "role": "tool",
     "tool_call_id": "call_123",
     "content": "{\"success\": false, \"error\": \"Case already exists\", \"error_code\": \"DUPLICATE_CASE\"}"
   }
   

Limitaciones

• Máximo 128 tools por solicitud
• Los nombres de tool deben ser únicos y no pueden entrar en conflicto con los nombres de tools internos
• La ejecución del tool ocurre del lado del cliente — eres responsable de ejecutarlos y securizarlos
• Los resultados del tool deben enviarse de vuelta en el historial de conversación para que el mind responda

Soporte de JSON Schema

El campo parameters soporta las funcionalidades estándar de JSON Schema:

Tipos:

• string, number, integer, boolean, array, object, null

Validación:

• enum — Restringe a valores específicos
• minimum, maximum — Cotas numéricas
• minLength, maxLength — Longitud de string
• minItems, maxItems — Tamaño de array
• pattern — Validación por regex
• format — Formatos de string (p. ej., "date-time", "email", "uri")

Estructura:

• properties — Propiedades del objeto
• required — Campos obligatorios
• items — Schema del item del array
• additionalProperties — Permite/deshabilita propiedades extra

Ejemplo con validación avanzada:

{
  "name": "schedule_meeting",
  "description": "Schedule a meeting with a client",
  "parameters": {
    "type": "object",
    "properties": {
      "title": {
        "type": "string",
        "minLength": 1,
        "maxLength": 200
      },
      "date": {
        "type": "string",
        "format": "date-time",
        "description": "Meeting date and time in ISO 8601 format"
      },
      "attendees": {
        "type": "array",
        "items": {
          "type": "string",
          "format": "email"
        },
        "minItems": 1,
        "maxItems": 20
      },
      "duration_minutes": {
        "type": "integer",
        "minimum": 15,
        "maximum": 480,
        "description": "Meeting duration (15-480 minutes)"
      }
    },
    "required": ["title", "date", "attendees"]
  }
}

Cómo funciona

1. Carga de contexto

Cuando envías un mensaje, el mind:

• Carga su system prompt y configuración
• Busca automáticamente en su knowledge base información relevante
• Considera el historial de conversación

2. Procesamiento

El mind:

• Analiza tu mensaje en contexto
• Fundamenta las respuestas en el knowledge recuperado con citas
• Accede a tools adicionales (web search, generación de imágenes, etc.) si es necesario
• Formula una respuesta alineada con su personalidad

3. Generación de respuesta

El mind:

• Genera una respuesta que refleja su experiencia
• Incluye citas cuando usa el knowledge base o fuentes web
• Devuelve el mensaje con metadatos opcionales (citas, imágenes, etc.)

Metadatos

Las respuestas pueden incluir metadatos adicionales:

Imágenes

Cuando un mind genera o muestra imágenes:

{
  "content": "Here are some logo concepts...",
  "metadata": {
    "images": [
      {
        "id": "img_123",
        "url": "https://...",
        "filename": "Logo Concept 1",
        "description": "Modern minimalist logo with blue gradient",
        "source": "generated"
      }
    ]
  }
}

Citas de knowledge

Cuando un mind recupera información de su knowledge base o de una búsqueda web:

{
  "content": "Based on recent research, solar panel efficiency has improved significantly...",
  "metadata": {
    "ragCitations": [
      {
        "id": "9bf44ab0-9d83-42ec-b941-c0ab7610e949",
        "displaySource": "Spark knowledge",
        "similarity": 0.85
      },
      {
        "id": "external-web-123",
        "displaySource": "https://example.com/solar-research",
        "similarity": 0.92
      }
    ]
  }
}

Campos de la cita:

• id - Identificador único de la fuente
• displaySource - Nombre legible de la fuente o URL
• similarity - Puntuación de relevancia (0-1) que indica cómo de bien coincide la fuente con la consulta

Los minds buscan automáticamente en su knowledge base antes de responder e incluyen citas cuando fundamentan sus respuestas en fuentes específicas.

Control de acceso

Puedes chatear con minds que:

• Tú posees - Minds que has creado
• Tienes acceso - Minds compartidos contigo por miembros del equipo
• Eres miembro - Minds en team workspaces a los que perteneces
• Minds públicos - Minds accesibles públicamente

Intentar acceder a minds no autorizados devuelve:

{
  "statusCode": 403,
  "statusMessage": "Access denied"
}

Formatos de respuesta

Respuesta de texto

La mayoría de las respuestas son texto plano:

{
  "content": "Based on current trends, I recommend focusing on..."
}

Respuesta estructurada

Algunos minds pueden devolver contenido estructurado:

{
  "content": "Here's my analysis:\n\n1. Trend: AI Personalization\n   - Impact: High\n   - Timeline: 6-12 months\n\n2. Trend: Short-form Video\n   - Impact: Very High\n   - Timeline: Immediate"
}

Respuesta vacía con metadatos

A veces solo se devuelven metadatos (p. ej., para generación de imágenes):

{
  "content": "",
  "metadata": {
    "images": [...]
  }
}

Buenas prácticas

Sé específico

❌ "Tell me about marketing"
✅ "What are the most cost-effective digital marketing channels for a B2B SaaS startup with a $5K monthly budget?"

Aporta contexto

✅ "We're launching a sustainable fashion brand targeting Gen Z. What social media strategy would you recommend?"

Usa follow-ups

Aprovecha la memoria de la conversación:

User: "What are the top trends?"
Assistant: "The top trends are..."
User: "Which of these would work best for a small budget?"
Assistant: "For a small budget, I'd focus on..."

Referencia el knowledge

Si has subido knowledge, referénciate a él:

✅ "Based on our brand guidelines, what tone should we use for this campaign?"

Respuestas de error

400 Bad Request

Spark ID ausente o no válido:

{
  "statusCode": 400,
  "statusMessage": "Spark ID is required"
}

Provider no soportado:

{
  "statusCode": 400,
  "statusMessage": "Unsupported provider: 'invalid'. Supported providers: openai, anthropic, google."
}

Nombre de modelo ambiguo sin provider:

{
  "statusCode": 400,
  "statusMessage": "Cannot auto-detect provider for model 'my-model'. Please specify a 'provider' parameter (openai, anthropic, or google)."
}

401 Unauthorized

API key no válida.

403 Forbidden

Acceso denegado al spark:

{
  "statusCode": 403,
  "statusMessage": "Access denied"
}

404 Not Found

El spark no existe:

{
  "statusCode": 404,
  "statusMessage": "Spark not found"
}

Notas de uso

• La API v1 aplica un límite configurable por cuenta autenticada (300 solicitudes por minuto de forma predeterminada)
• Lee RateLimit-Limit y RateLimit-Remaining, y respeta Retry-After tras un 429
• Limita las completions paralelas porque la generación consume recursos

Siguientes pasos

• Comprende latencia y rendimiento
• Aprende sobre errores y rate limits
• Crea tu primer mind
• Sube knowledge para mejorar las respuestas
• Lee la visión general de la API