Sparks API

Create and manage AI minds (agents) programmatically. Minds are customizable AI assistants with specific expertise, personalities, and knowledge.

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

Get Spark

Retrieve a single mind with full details including system prompt, sharing settings, and knowledge item count.

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

Headers:

Authorization: Bearer minds_your_api_key

Response

{
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "Marketing Expert",
    "description": "Experienced marketing director",
    "type": "expert",
    "discipline": "Marketing",
    "systemPrompt": "## Life Story & Background\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
  }
}

Response Fields

Example Request

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

Error Responses

400 Bad Request - Invalid spark ID format

401 Unauthorized - Invalid or missing API key

403 Forbidden - No access to this mind

404 Not Found - Mind doesn't exist

List Sparks

Retrieve all minds belonging to the authenticated user.

Endpoint: GET /api/v1/sparks

Headers:

Authorization: Bearer minds_your_api_key

Query Parameters

Response

{
  "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
  }
}

Response Fields

Example Request

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

Create Spark

Create a new AI mind with custom configuration using different training modes.

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"
}

Parameters

Mode Values

The mode parameter determines how your mind will be trained:

• keywords (default) - Train your mind using comma-separated keywords. The AI will gather relevant information from various sources based on these keywords to build the mind's knowledge base.
  • Required field: keywords - Array of keywords/topics
  • Best for: General expertise on specific topics or domains
• clone - Clone a person's style and knowledge by providing their name and context. The AI will research and build a comprehensive profile mimicking their expertise and communication style.
  • Required field: personaContext - Name and brief context (e.g., "Ada Lovelace, pioneering computer scientist")
  • Best for: Emulating specific individuals, historical figures, or well-known experts
• link - Train your mind using content from a specific URL. Provide a link to a profile, portfolio, or website, and the AI will analyze and extract relevant information.
  • Required field: contextLink - URL to the content source
  • Best for: Training on specific websites, portfolios, or online profiles
• manual - Create a mind without automatic training. You'll manually configure all settings and add knowledge later through the knowledge API.
  • No additional fields required
  • Best for: Custom configurations where you want full control over the training data

Auto-processing: When you use keywords, clone, or link, the backend mirrors the in-product Add Spark form — it derives entity keywords (AI-assisted for clone/link), enqueues the auto-spark BullMQ worker, and updates spark_pipeline_status. manual mode skips this automation so you can train the mind later via the Knowledge API.

Type Values

• creative - For artists, designers, writers, and creative professionals
• expert - For specialists, consultants, and domain experts
• user - For user personas, customers, and target audience archetypes

Response

{
  "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"
  },
  "processing": {
    "queued": true,
    "entityNames": ["solar", "wind energy", "sustainability", "green tech"],
    "error": null
  }
}

processing.queued is true when the request triggered the automatic content processor (keywords/clone/link with at least one entity). manual mode—or requests that trim down to zero entities—return queued: false. Use /api/spark/pipeline-status/{sparkId} (or subscribe to the SSE progress bus) to watch the pipeline advance through queued, running, and completed statuses just like the product UI.

Example: Create Mind with Keywords Mode

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"]
  }'

Example: Create Mind with Clone Mode

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"]
  }'

Example: Create Mind with Link Mode

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"]
  }'

Example: Create Mind with Manual Mode

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"]
  }'

Profile Images

When you provide a profileImageUrl:

1. The image is downloaded from the external URL
2. Uploaded to secure storage
3. The stored URL is returned in the response

Supported formats: JPG, PNG, GIF, WEBP

How Training Works

The system automatically generates an intelligent system prompt based on your chosen mode, type, and discipline:

• Keywords mode: Creates expertise around your specified keywords
• Clone mode: Builds a profile emulating the specified person's style and knowledge
• Link mode: Extracts knowledge from the provided URL
• Manual mode: Creates a basic assistant that you'll train with custom knowledge

You can further enhance your mind by uploading knowledge after creation.

Plan Limits

Different plans have different mind creation limits:

When you reach your limit, you'll receive a 403 Forbidden error:

{
  "statusCode": 403,
  "statusMessage": "Free plan limit: maximum 1 sparks. Upgrade your subscription to add more."
}

Error Responses

400 Bad Request

Missing or invalid parameters.

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

401 Unauthorized

Invalid or missing API key.

403 Forbidden

Plan limit reached.

500 Internal Server Error

Server-side error (rare).

Update Spark

Update an existing mind's configuration, including name, description, system prompt, and other settings.

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
}

Parameters

System Prompt

The systemPrompt field allows you to customize how your mind behaves and responds. This is useful for:

• Persona customization: Define specific personality traits, communication style, or expertise areas
• Response formatting: Instruct the mind to respond in specific formats (e.g., bullet points, numbered lists)
• Domain constraints: Limit responses to specific topics or perspectives
• Language/tone: Set the language, formality level, or tone of responses

Example system prompts:

# 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.

Response

{
  "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"
  }
}

Example: Update 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."
  }'

Example: Update Multiple Fields

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"]
  }'

Error Responses

400 Bad Request - No valid fields to update or invalid field values

401 Unauthorized - Invalid or missing API key

403 Forbidden - No permission to update this mind (you must be the owner)

404 Not Found - Mind doesn't exist

Get Spark Patterns (Raw)

Retrieve the raw Pattern[] rows for a mind. This is the unprocessed feed used by the SphereGraph visualization in the product UI — it returns one row per detected pattern (method/competency pair plus the supporting spark quote and source linkage), without any framework grouping or aggregation.

If you want the structured, framework-grouped view, use the Get Spark Knowledge Patterns endpoint below instead.

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

Headers:

Authorization: Bearer minds_your_api_key

Response

{
  "data": [
    {
      "id": 12345,
      "sparkId": "550e8400-e29b-41d4-a716-446655440000",
      "userId": "...",
      "messageId": null,
      "portfolioItemId": "abc-123",
      "aspect": "Strategic Thinking",
      "subAspect": "Market Analysis",
      "spark": "Market segmentation requires understanding customer pain points...",
      "isPredefined": true,
      "isPredefinedAspect": true,
      "isPredefinedSubAspect": true,
      "createdAt": "2025-12-10T15:30:00.000Z"
    }
  ]
}

Results are ordered by createdAt descending. The legacy field names aspect/subAspect correspond to the method/competency columns in the underlying schema and are preserved for backward compatibility.

Access Rules

• Public minds (isPublic: true) and link-shared minds (publicShareId set) are readable without authentication.
• Private minds require an API key whose owner is the mind owner, a team member, or a direct member.

Example Request

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

Error Responses

400 Bad Request - Invalid spark ID format

401 Unauthorized - Mind is private and no valid API key was supplied

403 Forbidden - No access to this private mind

404 Not Found - Mind doesn't exist

Get Spark Knowledge Patterns

Retrieve thinking patterns and knowledge organized by framework for a specific mind.

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

Headers:

Authorization: Bearer minds_your_api_key

Response Structure

The endpoint returns patterns grouped by frameworks (e.g., AOX Internal, OCEAN, DISC, etc.), with methods and competencies showing occurrences and evidence.

{
  "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"
                  }
                ]
              }
            ]
          }
        ]
      }
    ]
  }
}

Understanding the Response

• frameworks: Array of frameworks containing the spark's patterns
  • totalOccurrences: Total number of patterns in this framework
  • methods: Thinking methods or approaches detected
    • occurrences: Number of times this method appears
    • competencies: Specific skills or sub-areas within the method
      • occurrences: Number of patterns for this competency
      • evidence: Array of citations/quotes demonstrating this pattern
        • spark: The actual quote or insight from the content
        • portfolioItemId: Reference to the source material
        • createdAt: When this pattern was identified

Example Request

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

Use Cases

• Understanding mind expertise: See what methods and competencies your mind has learned
• Quality assurance: Verify patterns are being extracted correctly from training data
• Knowledge gaps: Identify areas where more training data is needed
• Framework comparison: Compare how a mind performs across different frameworks

Error Responses

401 Unauthorized - Invalid or missing API key

403 Forbidden - No access to this mind

404 Not Found - Mind doesn't exist

Regenerate System Prompt

Regenerate all system prompt components for a spark using its existing knowledge base. This uses the same AI-powered generation as the UI's "Generate All" button.

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

Headers:

Authorization: Bearer minds_your_api_key

How It Works

The endpoint analyzes the mind's knowledge base (portfolio items, patterns, embeddings) and generates a unified set of biographical prompt components for all spark types (user, expert, creative):

• Life Story & Background — biographical grounding, current age, location, ethnicity, formative experiences
• Communication & Language — distinctive voice, phrases, dialect, emotional triggers
• Knowledge & Experience — what they know and how they came to know it
• Values & Contradictions — beliefs, ideals, and the tensions between them
• Daily Reality & Context — economic, temporal, social, and physical context

The type field is preserved on the spark for backward compatibility but no longer changes which components are generated. A mind is a mind — the unified biographical approach produces stronger, more grounded personas regardless of type.

Response

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

Example Request

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

Use Cases

• After adding knowledge: Regenerate the prompt to incorporate newly added knowledge items
• Persona refinement: Regenerate to update the persona based on current knowledge patterns
• Reset customizations: Clear manual edits and regenerate fresh prompts from the knowledge base

Error Responses

401 Unauthorized - Invalid or missing API key

403 Forbidden - No permission to modify this mind (you must be the owner)

404 Not Found - Mind doesn't exist

500 Internal Server Error - Failed to generate prompt (e.g., insufficient knowledge)

Delete Spark

Permanently delete a mind and all associated data including knowledge, portfolio items, and files.

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

Headers:

Authorization: Bearer minds_your_api_key

Response

Returns 204 No Content with an empty body on success.

Example Request

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

What Gets Deleted

When you delete a mind, the following are permanently removed:

• The mind itself and all configuration
• All knowledge and training data
• All portfolio items and associated files
• All chat history and messages
• Profile images and uploaded files

Warning: This action cannot be undone.

Error Responses

400 Bad Request - Invalid spark ID format

401 Unauthorized - Invalid or missing API key

403 Forbidden - No permission to delete this mind (you must be the owner)

404 Not Found - Mind doesn't exist

Next Steps

• Upload knowledge to your mind
• Chat with your mind
• Learn about errors and limits