Sparks API

Crea y gestiona minds de IA (agentes) de forma programática. Los minds son asistentes de IA personalizables con experiencia, personalidades y knowledge específicos.

Base URL: https://getminds.ai/api/v1 o https://api.getminds.ai/v1

Get Spark

Obtén un único mind con todos sus detalles, incluyendo el system prompt, los ajustes de compartir y el número de elementos de knowledge.

Endpoint: GET /api/v1/sparks/{sparkId}

Headers:

Authorization: Bearer minds_your_api_key

Respuesta

{
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "Marketing Expert",
    "description": "Experienced marketing director",
    "type": "expert",
    "discipline": "Marketing",
    "systemPrompt": "## Core Identity & Personality\n\nYou are a seasoned marketing director...",
    "tags": ["marketing", "b2b"],
    "isPublic": false,
    "isLinkSharingEnabled": false,
    "publicShareId": null,
    "profileImageUrl": "https://...",
    "phoneNumber": null,
    "clonedVoiceStatus": null,
    "profitSplitOptIn": false,
    "createdAt": "2025-12-10T12:00:00.000Z",
    "updatedAt": "2025-12-10T12:00:00.000Z",
    "knowledgeItemCount": 12
  }
}

Campos de respuesta

Ejemplo de solicitud

curl -X GET "https://getminds.ai/api/v1/sparks/{sparkId}" \
  -H "Authorization: Bearer minds_your_api_key"

Respuestas de error

400 Bad Request - Formato de spark ID no válido

401 Unauthorized - API key no válida o ausente

403 Forbidden - Sin acceso a este mind

404 Not Found - El mind no existe

List Sparks

Obtén todos los minds que pertenecen al usuario autenticado.

Endpoint: GET /api/v1/sparks

Headers:

Authorization: Bearer minds_your_api_key

Query parameters

Respuesta

{
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "Marketing Expert",
      "description": "Experienced marketing director",
      "type": "expert",
      "discipline": "Marketing",
      "tags": ["marketing", "b2b"],
      "profileImageUrl": "https://...",
      "createdAt": "2025-12-10T12:00:00.000Z",
      "updatedAt": "2025-12-10T12:00:00.000Z"
    }
  ],
  "pagination": {
    "total": 42,
    "limit": 100,
    "offset": 0
  }
}

Campos de respuesta

Ejemplo de solicitud

curl -X GET "https://getminds.ai/api/v1/sparks?limit=10&offset=0" \
  -H "Authorization: Bearer minds_your_api_key"

Create Spark

Crea un nuevo mind con IA con configuración personalizada usando distintos modos de entrenamiento.

Endpoint: POST /api/v1/sparks

Headers:

Authorization: Bearer minds_your_api_key
Content-Type: application/json

Request body

{
  "name": "My AI Expert",
  "description": "An expert in renewable energy",
  "mode": "keywords",
  "type": "expert",
  "discipline": "Renewable Energy",
  "keywords": ["solar", "wind energy", "sustainability", "green tech"],
  "personaContext": "Ada Lovelace, pioneering computer scientist",
  "contextLink": "https://example.com/profile",
  "tags": ["energy", "solar", "sustainability"],
  "profileImageUrl": "https://example.com/avatar.jpg"
}

Parámetros

Valores de mode

El parámetro mode determina cómo se entrenará tu mind:

• keywords (default) - Entrena tu mind usando palabras clave separadas por comas. La IA recopilará información relevante de diversas fuentes basándose en estas palabras clave para construir el knowledge del mind.
  • Campo obligatorio: keywords - Array de palabras clave/temas
  • Ideal para: Experiencia general sobre temas o dominios específicos
• clone - Clona el estilo y conocimiento de una persona proporcionando su nombre y contexto. La IA investigará y construirá un perfil completo que imite su experiencia y estilo de comunicación.
  • Campo obligatorio: personaContext - Nombre y breve contexto (p. ej., "Ada Lovelace, pioneering computer scientist")
  • Ideal para: Emular individuos concretos, figuras históricas o expertos conocidos
• link - Entrena tu mind usando el contenido de una URL específica. Proporciona un enlace a un perfil, portfolio o sitio web, y la IA analizará y extraerá información relevante.
  • Campo obligatorio: contextLink - URL a la fuente de contenido
  • Ideal para: Entrenar sobre sitios web específicos, portfolios o perfiles online
• manual - Crea un mind sin entrenamiento automático. Configurarás manualmente todos los ajustes y añadirás knowledge más tarde vía la Knowledge API.
  • Sin campos adicionales obligatorios
  • Ideal para: Configuraciones personalizadas en las que quieres control total sobre los datos de entrenamiento

Auto-processing: Cuando usas keywords, clone o link, el backend replica el formulario Add Spark del producto — deriva palabras clave de entidades (con asistencia de IA para clone/link) y entrena el mind de forma asíncrona. Sigue ese entrenamiento mediante el bloque training de la respuesta de creación y el endpoint dedicado descrito en Ciclo de vida del entrenamiento del mind más abajo. El modo manual omite esta automatización para que puedas entrenar el mind más tarde vía la Knowledge API.

Valores de type

• creative - Para artistas, diseñadores, escritores y profesionales creativos
• expert - Para especialistas, consultores y expertos de dominio
• user - Para personas de usuario, clientes y arquetipos de audiencia objetivo

Respuesta

{
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "My AI Expert",
    "description": "An expert in renewable energy",
    "type": "expert",
    "discipline": "Renewable Energy",
    "tags": ["energy", "solar", "sustainability"],
    "profileImageUrl": "https://...",
    "createdAt": "2025-12-10T12:00:00.000Z",
    "updatedAt": "2025-12-10T12:00:00.000Z"
  },
  "training": {
    "status": "queued",
    "readyToChat": false,
    "message": "Queued for data collection",
    "startedAt": null,
    "completedAt": null,
    "error": null
  }
}

El bloque training informa del ciclo de vida del mind en el momento de la creación. Los modos keywords, clone y link empiezan en queued y se entrenan en segundo plano; los minds manual vuelven en completed con readyToChat ya en true. El id de un mind existe en cuanto esta llamada retorna, pero el mind solo puede responder cuando readyToChat es true. Consulta Ciclo de vida del entrenamiento del mind más abajo para el sondeo.

Ejemplo: Crear mind con modo Keywords

curl -X POST "https://getminds.ai/api/v1/sparks" \
  -H "Authorization: Bearer minds_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Marketing Expert",
    "description": "Experienced marketing director with expertise in B2B SaaS",
    "mode": "keywords",
    "type": "expert",
    "discipline": "Marketing",
    "keywords": ["B2B marketing", "SaaS", "growth marketing", "content strategy", "brand positioning", "ROI"],
    "tags": ["marketing", "b2b", "saas", "growth"]
  }'

Ejemplo: Crear mind con modo Clone

curl -X POST "https://getminds.ai/api/v1/sparks" \
  -H "Authorization: Bearer minds_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Ada Lovelace AI",
    "description": "AI trained to emulate Ada Lovelace",
    "mode": "clone",
    "type": "expert",
    "discipline": "Computer Science Pioneer",
    "personaContext": "Ada Lovelace, pioneering computer scientist and mathematician, first computer programmer",
    "tags": ["computer science", "mathematics", "history"]
  }'

Ejemplo: Crear mind con modo Link

curl -X POST "https://getminds.ai/api/v1/sparks" \
  -H "Authorization: Bearer minds_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Brand Voice Expert",
    "description": "Trained on company brand guidelines",
    "mode": "link",
    "type": "creative",
    "discipline": "Brand Strategy",
    "contextLink": "https://example.com/brand-guidelines",
    "tags": ["branding", "copywriting"]
  }'

Ejemplo: Crear mind con modo Manual

curl -X POST "https://getminds.ai/api/v1/sparks" \
  -H "Authorization: Bearer minds_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Custom Assistant",
    "description": "Custom configured assistant",
    "mode": "manual",
    "type": "creative",
    "discipline": "General Assistant",
    "tags": ["custom"]
  }'

Ciclo de vida del entrenamiento del mind

Crear un mind es asíncrono. POST /v1/sparks devuelve de inmediato un id, pero en los modos keywords, clone y link el mind aún se está entrenando en segundo plano. Que exista el id de un mind no significa que el mind esté listo — el mind solo puede responder cuando readyToChat es true. La única excepción es el modo manual: esos minds omiten la recopilación de datos y quedan completed en el momento en que se crean.

Sondea el endpoint de entrenamiento dedicado hasta que el mind esté listo:

curl "https://getminds.ai/api/v1/sparks/{sparkId}/training" \
  -H "Authorization: Bearer minds_your_api_key"

{
  "status": "running",
  "readyToChat": false,
  "message": "Collecting knowledge...",
  "startedAt": "2025-12-10T12:00:01.000Z",
  "completedAt": null,
  "error": null
}

Valores de estado

GET /v1/sparks/{id} también devuelve readyToChat (y trainingStatus) junto con el resto del mind, de modo que una sola lectura te dice tanto quién es el mind como si ya puede responder.

Cuando el entrenamiento falla

Cuando status es failed, la respuesta incluye un objeto error con un code y una marca retryable:

Reentrenamiento

Si un mind termina en failed (o simplemente quieres reconstruir un mind completed), reentrénalo:

curl -X POST "https://getminds.ai/api/v1/sparks/{sparkId}/retrain" \
  -H "Authorization: Bearer minds_your_api_key"

Esto vuelve a poner el mind en cola y devuelve un bloque training nuevo con status en queued. El reentrenamiento solo funciona con minds que han terminado: un mind que aún está queued o running devuelve 409 Conflict porque ya hay una ejecución de entrenamiento en curso. Tras reentrenar, sondea de nuevo GET /v1/sparks/{id}/training hasta que readyToChat sea true.

Imágenes de perfil

Cuando proporcionas un profileImageUrl:

1. La imagen se descarga desde la URL externa
2. Se sube a almacenamiento seguro
3. La URL almacenada se devuelve en la respuesta

Formatos soportados: JPG, PNG, GIF, WEBP

Cómo funciona el entrenamiento

El sistema genera automáticamente un system prompt inteligente basado en el modo, tipo y disciplina que elijas:

• Modo Keywords: Crea experiencia alrededor de las palabras clave especificadas
• Modo Clone: Construye un perfil que emula el estilo y conocimiento de la persona indicada
• Modo Link: Extrae knowledge de la URL proporcionada
• Modo Manual: Crea un asistente básico que entrenarás con knowledge personalizado

Puedes mejorar aún más tu mind subiendo knowledge después de crearlo.

Límites del plan

Distintos planes tienen distintos límites de creación de minds:

Cuando alcances tu límite, recibirás un error 403 Forbidden:

{
  "statusCode": 403,
  "statusMessage": "Individual plan limit reached",
  "message": "Individual plan limit reached",
  "url": "/api/v1/sparks",
  "error": true,
  "data": {
    "code": "PLAN_LIMIT",
    "limitType": "sparks",
    "currentPlan": "premium",
    "limit": 100,
    "current": 100
  }
}

Respuestas de error

400 Bad Request

Parámetros ausentes o no válidos.

{
  "statusCode": 400,
  "statusMessage": "Name is required"
}

401 Unauthorized

API key no válida o ausente.

403 Forbidden

Límite del plan alcanzado.

500 Internal Server Error

Error del servidor (poco frecuente).

Update Spark

Actualiza la configuración de un mind existente, incluyendo nombre, descripción, system prompt y otros ajustes.

Endpoint: PUT /api/v1/sparks/{sparkId}

Headers:

Authorization: Bearer minds_your_api_key
Content-Type: application/json

Request body

{
  "name": "Updated Name",
  "description": "Updated description",
  "type": "expert",
  "discipline": "Updated Discipline",
  "systemPrompt": "Custom system prompt instructions...",
  "tags": ["tag1", "tag2"],
  "isPublic": false
}

Parámetros

System prompt

El campo systemPrompt te permite personalizar cómo se comporta y responde tu mind. Es útil para:

• Personalización de persona: Define rasgos de personalidad, estilo de comunicación o áreas de experiencia específicas
• Formato de respuesta: Instruye al mind para que responda en formatos concretos (p. ej., listas con viñetas, listas numeradas)
• Restricciones de dominio: Limita las respuestas a temas o perspectivas específicas
• Idioma/tono: Establece el idioma, nivel de formalidad o tono de las respuestas

Ejemplos de system prompt:

# Survey Response Expert
Du bist ein erfahrener Handwerker. Bei Umfragen antworte immer aus deiner
persönlichen Erfahrung, nicht mit allgemeinen Branchendurchschnittswerten.
Wähle bei Multiple-Choice-Fragen immer genau eine Option.

# Technical Expert
You are a senior software architect. Always provide concrete,
actionable advice. Include code examples when relevant.
Avoid vague statements.

Respuesta

{
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "Updated Name",
    "description": "Updated description",
    "type": "expert",
    "discipline": "Updated Discipline",
    "systemPrompt": "Custom system prompt...",
    "tags": ["tag1", "tag2"],
    "isPublic": false,
    "profileImageUrl": "https://...",
    "createdAt": "2025-12-10T12:00:00.000Z",
    "updatedAt": "2025-12-29T15:30:00.000Z"
  }
}

Ejemplo: Actualizar el system prompt

curl -X PUT "https://getminds.ai/api/v1/sparks/{sparkId}" \
  -H "Authorization: Bearer minds_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "systemPrompt": "Du bist ein erfahrener Handwerker im Sanitärbereich. Antworte immer aus deiner persönlichen Praxiserfahrung."
  }'

Ejemplo: Actualizar varios campos

curl -X PUT "https://getminds.ai/api/v1/sparks/{sparkId}" \
  -H "Authorization: Bearer minds_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Senior Plumber Expert",
    "description": "Expert plumber with 20 years of experience",
    "discipline": "Plumbing & Sanitary Installation",
    "tags": ["plumbing", "sanitary", "renovation"]
  }'

Respuestas de error

400 Bad Request - No hay campos válidos para actualizar o valores de campo no válidos

401 Unauthorized - API key no válida o ausente

403 Forbidden - Sin permiso para actualizar este mind (debes ser el propietario)

404 Not Found - El mind no existe

Get Spark Knowledge Patterns

Obtén los patrones de pensamiento y el knowledge organizados por framework para un mind concreto.

Endpoint: GET /api/v1/sparks/{sparkId}/knowledge/patterns

Headers:

Authorization: Bearer minds_your_api_key

Estructura de la respuesta

El endpoint devuelve patrones agrupados por frameworks (p. ej., AOX Internal, OCEAN, DISC, etc.), con métodos y competencias que muestran ocurrencias y evidencia.

{
  "success": true,
  "data": {
    "sparkId": "550e8400-e29b-41d4-a716-446655440000",
    "sparkName": "Marketing Expert",
    "totalPatterns": 47,
    "frameworks": [
      {
        "id": "aox-internal",
        "name": "AOX Internal Framework",
        "totalOccurrences": 32,
        "methods": [
          {
            "id": "strategic-thinking",
            "name": "Strategic Thinking",
            "description": "Ability to think strategically and plan long-term",
            "occurrences": 15,
            "competencies": [
              {
                "id": "market-analysis",
                "name": "Market Analysis",
                "description": "Understanding market dynamics and trends",
                "occurrences": 8,
                "evidence": [
                  {
                    "spark": "Market segmentation requires understanding customer pain points and aligning product features with specific needs...",
                    "portfolioItemId": "abc-123",
                    "createdAt": "2025-12-10T15:30:00.000Z"
                  },
                  {
                    "spark": "Competitive analysis shows that timing and positioning are critical for market entry...",
                    "portfolioItemId": "def-456",
                    "createdAt": "2025-12-10T14:20:00.000Z"
                  }
                ]
              }
            ]
          }
        ]
      }
    ]
  }
}

Cómo interpretar la respuesta

• frameworks: Array de frameworks que contienen los patrones del spark
  • totalOccurrences: Número total de patrones en este framework
  • methods: Métodos o enfoques de pensamiento detectados
    • occurrences: Número de veces que aparece este método
    • competencies: Habilidades específicas o subáreas dentro del método
      • occurrences: Número de patrones para esta competencia
      • evidence: Array de citas/quotes que demuestran este patrón
        • spark: La cita o insight real del contenido
        • portfolioItemId: Referencia al material origen
        • createdAt: Cuándo se identificó este patrón

Ejemplo de solicitud

curl -X GET "https://getminds.ai/api/v1/sparks/{sparkId}/knowledge/patterns" \
  -H "Authorization: Bearer minds_your_api_key"

Casos de uso

• Entender la experiencia del mind: Ve qué métodos y competencias ha aprendido tu mind
• Control de calidad: Verifica que los patrones se estén extrayendo correctamente de los datos de entrenamiento
• Detección de carencias de knowledge: Identifica áreas donde se necesitan más datos de entrenamiento
• Comparación entre frameworks: Compara cómo rinde un mind en distintos frameworks

Respuestas de error

401 Unauthorized - API key no válida o ausente

403 Forbidden - Sin acceso a este mind

404 Not Found - El mind no existe

Regenerate System Prompt

Regenera todos los componentes del system prompt de un spark usando su knowledge existente. Usa la misma generación impulsada por IA que el botón "Generate All" de la UI.

Endpoint: POST /api/v1/sparks/{sparkId}/regenerate-prompt

Headers:

Authorization: Bearer minds_your_api_key

Cómo funciona

El endpoint analiza el knowledge del mind (portfolio items, patrones, embeddings) y genera todos los componentes del prompt:

Para sparks de tipo user:

• Core Identity & Demographics
• Needs & Motivations
• Pain Points & Challenges
• Tone & Communication Style
• Goals & Desires
• Behavioral Patterns

Para sparks de tipo expert:

• Core Identity & Personality
• Professional Expertise & Credentials
• Tone & Communication Style
• Professional Approach & Methods
• Domain Knowledge

Para sparks de tipo creative:

• Core Identity & Personality
• Creative Philosophy & Values
• Tone & Communication Style
• Creative Approach & Methods
• Domain Expertise

Respuesta

{
  "success": true,
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "My Spark",
    "systemPrompt": "## Core Identity & Demographics\n\n...",
    "promptLength": 2847
  }
}

Ejemplo de solicitud

curl -X POST "https://getminds.ai/api/v1/sparks/{sparkId}/regenerate-prompt" \
  -H "Authorization: Bearer minds_your_api_key"

Casos de uso

• Tras añadir knowledge: Regenera el prompt para incorporar nuevos elementos de knowledge
• Refinamiento de persona: Regenera para actualizar la persona con los patrones de knowledge actuales
• Reset de personalizaciones: Borra las ediciones manuales y regenera prompts frescos desde el knowledge

Respuestas de error

401 Unauthorized - API key no válida o ausente

403 Forbidden - Sin permiso para modificar este mind (debes ser el propietario)

404 Not Found - El mind no existe

500 Internal Server Error - Fallo al generar el prompt (p. ej., knowledge insuficiente)

Delete Spark

Elimina permanentemente un mind y todos sus datos asociados, incluyendo knowledge, portfolio items y archivos.

Endpoint: DELETE /api/v1/sparks/{sparkId}

Headers:

Authorization: Bearer minds_your_api_key

Respuesta

Devuelve 204 No Content con un body vacío en caso de éxito.

Ejemplo de solicitud

curl -X DELETE "https://getminds.ai/api/v1/sparks/{sparkId}" \
  -H "Authorization: Bearer minds_your_api_key"

Qué se elimina

Al eliminar un mind, se borra permanentemente lo siguiente:

• El propio mind y toda su configuración
• Todo el knowledge y los datos de entrenamiento
• Todos los portfolio items y archivos asociados
• Todo el historial de chat y mensajes
• Imágenes de perfil y archivos subidos

Advertencia: Esta acción no se puede deshacer.

Respuestas de error

400 Bad Request - Formato de spark ID no válido

401 Unauthorized - API key no válida o ausente

403 Forbidden - Sin permiso para eliminar este mind (debes ser el propietario)

404 Not Found - El mind no existe

Siguientes pasos

• Sube knowledge a tu mind
• Chatea con tu mind
• Aprende sobre errores y límites