Visión general de la API

Te damos la bienvenida a la documentación de la API de Minds. Nuestra API te permite crear y gestionar minds con IA de forma programática, subir knowledge e interactuar con ellos.

Comenzar

La API de Minds está organizada según los principios REST. Nuestra API tiene URLs predecibles orientadas a recursos, acepta bodies de solicitud codificados en JSON, devuelve respuestas codificadas en JSON y utiliza códigos de respuesta HTTP, autenticación y verbos estándar.

Base URL

Producción: https://getminds.ai/api/v1 o https://api.getminds.ai/v1

Desarrollo local: http://localhost:3000/api/v1

Ambas URLs base de producción son totalmente equivalentes. Se recomienda el subdominio api.getminds.ai para URLs de integración más limpias.

Autenticación

Todos los endpoints de la API requieren autenticación vía API key. Puedes generar y gestionar tus API keys en Settings → API Keys.

Incluye tu API key en el header Authorization:

Authorization: Bearer minds_your_api_key_here

Especificación OpenAPI

Se publica una especificación OpenAPI 3.1.0 legible por máquina en /_openapi.json. Usa la especificación para generar clientes tipados (TypeScript, Python, etc.) o para pegarla en un LLM y obtener código de integración de una sola vez. Consulta OpenAPI para ver ejemplos.

Content Type

Todas las solicitudes que envían datos deben incluir el header Content-Type:

Content-Type: application/json

Para subidas de archivos, usa:

Content-Type: multipart/form-data

Endpoints disponibles

Minds

Crea y gestiona minds con IA (agentes) con configuraciones personalizadas.

• GET /api/v1/minds - Lista todos los Minds
• GET /api/v1/minds/{mindId} - Obtiene los detalles de un Mind
• POST /api/v1/minds - Crea un nuevo Mind
• PUT /api/v1/minds/{mindId} - Actualiza un Mind
• DELETE /api/v1/minds/{mindId} - Elimina un Mind
• POST /api/v1/minds/{mindId}/regenerate-prompt - Regenera el system prompt a partir del knowledge

Knowledge

Gestiona el knowledge de tus minds.

• GET /api/v1/minds/{mindId}/knowledge - Lista los elementos de knowledge
• POST /api/v1/minds/{mindId}/knowledge - Añade knowledge (links, archivos o búsqueda por palabras clave)
• PUT /api/v1/minds/{mindId}/knowledge/{itemId} - Actualiza un elemento de knowledge
• DELETE /api/v1/minds/{mindId}/knowledge/{itemId} - Elimina un elemento de knowledge
• POST /api/v1/minds/{mindId}/knowledge/enrich - Enriquece mediante búsqueda por palabras clave (alias de conveniencia)
• GET /api/v1/minds/{mindId}/knowledge/patterns - Obtiene los patrones de knowledge por framework

Chat

Interactúa con tus minds mediante chat completions.

• POST /api/v1/minds/{mindId}/completion - Envía mensajes y obtén respuestas

Studies

Crea y gestiona studyes de IA para encuestar audiences de minds.

• GET /api/v1/studies - Lista todos los studyes
• POST /api/v1/studies - Crea un nuevo study
• GET /api/v1/studies/{studyId} - Obtiene los detalles del study con el historial de mensajes
• POST /api/v1/studies/{studyId}/ask - Hace una pregunta a todos los minds del study (SSE stream)
• POST /api/v1/studies/{studyId}/export - Exporta los resultados del study como informe
• GET /api/v1/studies/{studyId}/export-status - Comprueba el estado del job de exportación
• GET /api/v1/studies/{studyId}/export-download - Descarga el PDF exportado

User

Endpoints relacionados con el usuario.

• GET /api/v1/auth/me - Obtiene el usuario autenticado actual
• GET /api/v1/user/shareable-sparks - Lista los minds disponibles para compartir

API Keys

Gestiona tus API keys para autenticación.

• GET /api/v1/api-keys - Lista tus API keys
• POST /api/v1/api-keys - Crea una nueva API key
• DELETE /api/v1/api-keys/{keyId} - Elimina una API key

Ejemplo rápido

Aquí tienes un ejemplo rápido de cómo crear un mind y chatear con él:

# 1. Create a mind (keywords mode)
curl -X POST "https://getminds.ai/api/v1/minds" \
  -H "Authorization: Bearer minds_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Marketing Expert",
    "description": "Expert in digital marketing strategies",
    "mode": "keywords",
    "type": "expert",
    "discipline": "Marketing",
    "keywords": ["SEO", "content marketing", "social media", "analytics"]
  }'

# Response: { "data": { "id": "mind-id", ... }, "processing": { "queued": true, ... } }

# 2. Create a mind from social profile (clone mode)
curl -X POST "https://getminds.ai/api/v1/minds" \
  -H "Authorization: Bearer minds_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Influencer Clone",
    "description": "AI trained on influencer social presence",
    "mode": "clone",
    "type": "creative",
    "discipline": "Social Media Marketing",
    "personaContext": "https://twitter.com/username"
  }'

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

Siguientes pasos

• Aprende sobre Autenticación
• Explora los endpoints de Minds
• Lee sobre Gestión de knowledge
• Comprende Chat completions
• Crea Studyes para encuestas multi-mind
• Revisa Latencia y rendimiento
• Conéctate vía Integración MCP
• Revisa Errores y límites

Límites del plan

El acceso a la API y MCP está disponible en los planes de pago compatibles. Gestiona las respuestas estructuradas plan_limited y 429 en lugar de codificar límites fijos en tu integración. El plan Starter aparece como "premium" en los payloads de la API.

Los valores públicos predeterminados siguientes se generan desde el mismo contrato de límites y acceso a funciones que usa el producto. Las excepciones de cuenta o Enterprise mostradas en el producto tienen prioridad.

Ver planes

¿Necesitas ayuda?

Si tienes preguntas o necesitas soporte con la API:

• Consulta nuestra Guía
• Contáctanos a través del formulario de feedback
• Únete a las conversaciones de la comunidad

Flujos de trabajo de n8n

Utilice el nodo de la comunidad Minds para n8n para crear Estudios, previsualizar planes de investigación, recuperar Estudios y resúmenes guardados, o exponer una operación a un Agente de IA. Instale n8n-nodes-minds en n8n autohospedado y conecte una clave API de Minds. El paquete está publicado en npm; la verificación de n8n está bajo revisión, por lo que aún no está disponible en n8n Cloud. Revise e inicie la investigación por separado en Minds.

Facturación de Stripe para agentes

Las nuevas suscripciones y recargas de créditos de respuestas usan los precios existentes de Stripe. Consulta el catálogo autenticado antes de proponer una compra; la elegibilidad, titularidad, pruebas, impuestos y descuentos siguen los mismos servicios de facturación de Minds. Solicita la aprobación del comprador y la aceptación expresa de los términos y del aviso de desistimiento para suscripciones.

Inicia el pago con un Idempotency-Key estable de 1–128 letras, dígitos, guiones bajos o guiones. Tras un tiempo de espera agotado, reutiliza la clave y el cuerpo; cambiar la compra con esa clave se rechaza. La respuesta contiene data.url y data.checkoutSessionId. Devuelve la URL sin modificar. Una URL no demuestra el pago; los cambios de suscripciones existentes se gestionan en los ajustes de Minds.

{
  "kind": "subscription",
  "priceId": "price_from_catalog",
  "planType": "premium",
  "billingCountry": "DE",
  "legalAcceptance": { "termsAccepted": true, "withdrawalConsent": true }
}

MPP y x402 se aplican a facturas propias abiertas send_invoice en USD o EUR, con al menos 50 unidades menores pendientes. El cobro automático continúa en la página de factura de Stripe. La solicitud de pago indica el saldo real con impuestos y descuentos. MPP requiere un perfil de negocio en la cuenta Stripe propietaria. x402 requiere además habilitación cripto y un facilitador configurado; admite facturas USD con Base USDC y exige la extensión de vinculación mppx, por lo que las carteras sin ella no pueden pagar esta ruta.

Conserva Authorization: Bearer para identificarte en Minds y envía credenciales MPP en Payment-Authorization o x402 en PAYMENT-SIGNATURE. Los clientes MPP nativos pueden usar Authorization: Payment con el bearer de Minds en Minds-Authorization solo en esta ruta. Nunca incluyas credenciales de pago en argumentos MCP visibles al modelo. Reintenta un pago incierto con la credencial original; otra credencial no debe generar un segundo cargo. Stripe y el webhook firmado determinan la entrega.

Los métodos de pago se descubren en /openapi.json; la respuesta 402 cotiza los importes dinámicos. /.well-known/acp.json anuncia el adaptador alojado en /api/acp, versión 2026-04-17. Crea una sesión con un precio Stripe en line_items, su currency y capabilities: {}; coloca billingCountry, quantity de equipo y legalAcceptance de suscripción en metadata. Consulta, actualiza, completa o cancela con /checkout_sessions/{id} y las acciones /complete o /cancel. Los POST requieren una clave de idempotencia. Actualizar y completar aceptan cuerpos vacíos: devuelve continue_url si hace falta intervención del comprador y confirma la finalización solo tras Stripe.

El descubrimiento UCP está en /.well-known/ucp, versión 2026-08-25, con checkout REST en /api/ucp y las mismas sesiones de Stripe que MCP y la API de facturación. Publica un perfil de plataforma compatible y utiliza un cliente OAuth de Minds con documento de metadatos en el mismo origen HTTPS. Las claves API personales no pueden declarar un perfil de plataforma arbitrario. Envía UCP-Agent: profile="https://your-platform.example/.well-known/ucp" en cada solicitud e Idempotency-Key en las escrituras. Los controladores de pago están vacíos porque el comprador paga en Stripe Checkout.

Suscripciones webhook de disponibilidad

Usa la misma clave API o conexión OAuth autenticada que para el recurso. GET /api/v1/events devuelve los eventos permitidos y sus esquemas exactos. POST /api/v1/events/subscribe crea o renueva una suscripción determinista; POST /api/v1/events/unsubscribe la detiene con el evento, los argumentos y la URL originales, sin cancelar la investigación. Las Audiencias requieren operationId; los Estudios, studyId y runId. Los métodos MCP son events/list, events/subscribe y events/unsubscribe, descubiertos con server/discover y protocolo 2026-07-28.

{
  "name": "study.run.finished",
  "arguments": {
    "studyId": "163bcb31-6ca7-4fef-91bd-9b963a9dd39f",
    "runId": "663bcb31-6ca7-4fef-91bd-9b963a9dd39f"
  },
  "delivery": {
    "mode": "webhook",
    "url": "https://receiver.example/mcp-events",
    "secret": "whsec_<base64-encoded-signing-key>"
  },
  "cursor": null
}

El callback HTTPS debe devolver el desafío de verificación firmado. Se usan los encabezados Standard Webhooks webhook-id, webhook-timestamp, webhook-signature y X-MCP-Subscription-Id. La clave whsec_ debe decodificar a 24–64 bytes. Se rechazan direcciones privadas, redirecciones y credenciales en URL. Un fallo devuelve MCP -32015 con un motivo y no activa la suscripción. HTTP 2xx confirma recepción; los fallos transitorios se reintentan de forma limitada con espera exponencial e ID estable; 410 y 413 detienen la entrega. Elimina ID duplicados antes de actuar.

La respuesta contiene id, refreshBefore, cursor:null y truncated:false. ttlMs puede pedir menos tiempo; omitido o null concede el valor finito predeterminado, hasta 86400000 ms. El mismo principal, callback, evento y argumentos renuevan el mismo ID. La rotación firma brevemente con ambas claves. Caducidad o revocación detiene la entrega. Las cargas no incluyen credenciales Bearer ni respuestas de investigación.