MindraDocs

Quick Start Guide

7 min read

Get started with Mindra Platform in 5 minutes with copy-paste examples.

Prerequisites

# Set your API key
export MINDRA_API_KEY="mk_your_api_key_here"

Get your API key from app.mindra.co/settings/api-keys

1. Check Your Wallet

Before making requests, check your wallet balance:

curl https://api.mindra.co/v1/wallet \
  -H "Authorization: Bearer $MINDRA_API_KEY"

Expected response:

{
  "wallets": [
    {
      "id": "wallet_abc123",
      "type": "FIAT",
      "balance": 100.00,
      "currency": "USD",
      "isActive": true
    }
  ]
}

If your balance is low, top up at app.mindra.co/wallet

2. List Available Agents

See what agents are available:

curl https://api.mindra.co/v1/agents \
  -H "Authorization: Bearer $MINDRA_API_KEY"

Expected response:

{
  "agents": [
    {
      "id": "agent_email_campaign",
      "name": "email-campaign-agent",
      "description": "Automated email marketing campaign creator",
      "vertical": "marketing",
      "capabilities": ["email_generation", "a_b_testing"],
      "pricing": {
        "model": "per_execution",
        "basePrice": 0.50
      }
    },
    {
      "id": "agent_payment",
      "name": "payment-processor-agent",
      "description": "Cross-border payment processor",
      "vertical": "cross-border",
      "capabilities": ["multi_currency_conversion", "compliance_check"],
      "pricing": {
        "model": "per_transaction",
        "basePrice": 0.20
      }
    }
  ]
}

3. Your First Orchestration

Example: Email Campaign

curl -X POST https://api.mindra.co/v1/orchestrate \
  -H "Authorization: Bearer $MINDRA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "Create an email campaign for our new AI product targeting developers",
    "context": {
      "productName": "DevAI Assistant",
      "targetAudience": "software engineers",
      "campaignGoal": "signups",
      "tone": "technical but friendly"
    }
  }'

Expected response (202 Accepted):

{
  "executionId": "exec_abc123def456",
  "status": "PENDING",
  "estimatedCost": 0.50,
  "estimatedDuration": 5000,
  "selectedAgents": [
    {
      "id": "agent_email_campaign",
      "name": "email-campaign-agent",
      "estimatedCost": 0.50
    }
  ],
  "message": "Execution started"
}

Save the executionId - you'll need it to check the status!

4. Check Execution Status

# Replace with your actual execution ID
EXECUTION_ID="exec_abc123def456"

curl https://api.mindra.co/v1/executions/$EXECUTION_ID \
  -H "Authorization: Bearer $MINDRA_API_KEY"

While running:

{
  "id": "exec_abc123def456",
  "status": "RUNNING",
  "query": "Create an email campaign...",
  "progress": {
    "completed": 0,
    "total": 1,
    "currentAgent": "email-campaign-agent"
  },
  "startedAt": "2025-11-10T10:30:00Z"
}

When completed:

{
  "id": "exec_abc123def456",
  "status": "COMPLETED",
  "query": "Create an email campaign...",
  "result": {
    "summary": "Created 3 email variations for A/B testing",
    "details": {
      "emails": [
        {
          "variant": "A",
          "subject": "Introducing DevAI: Your New Coding Companion",
          "preview": "AI-powered assistance for faster development...",
          "cta": "Start Free Trial"
        },
        {
          "variant": "B",
          "subject": "Ship Code 10x Faster with DevAI",
          "preview": "Join 10,000+ developers using AI to code smarter...",
          "cta": "Get Started Free"
        },
        {
          "variant": "C",
          "subject": "Your AI Pair Programmer is Here",
          "preview": "DevAI learns your codebase and helps you build...",
          "cta": "Try DevAI Now"
        }
      ],
      "estimatedReach": 15000,
      "targetSegments": ["full-stack", "frontend", "backend"]
    }
  },
  "metadata": {
    "actualCost": 0.50,
    "actualDuration": 4823,
    "agentsUsed": 1
  },
  "startedAt": "2025-11-10T10:30:00Z",
  "completedAt": "2025-11-10T10:30:04Z"
}

More Examples

Example: Cross-Border Payment

curl -X POST https://api.mindra.co/v1/orchestrate \
  -H "Authorization: Bearer $MINDRA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "Process payment of $2500 to vendor in Germany",
    "context": {
      "amount": 2500,
      "fromCurrency": "USD",
      "toCurrency": "EUR",
      "recipient": {
        "name": "ACME GmbH",
        "country": "DE",
        "iban": "DE89370400440532013000"
      },
      "urgency": "standard"
    },
    "selectionCriteria": {
      "verticals": ["cross-border"],
      "requiredCapabilities": ["compliance_check", "multi_currency_conversion"]
    }
  }'

Example: Supply Chain Optimization

curl -X POST https://api.mindra.co/v1/orchestrate \
  -H "Authorization: Bearer $MINDRA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "Optimize inventory for warehouse US-WEST-1 for Q4 2025",
    "context": {
      "warehouse": "US-WEST-1",
      "targetQuarter": "Q4-2025",
      "criticalSkus": ["SKU-001", "SKU-042", "SKU-137"],
      "constraints": {
        "maxBudget": 500000,
        "leadTime": 30
      }
    }
  }'

Example: Social Media Campaign

curl -X POST https://api.mindra.co/v1/orchestrate \
  -H "Authorization: Bearer $MINDRA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "Create social media posts announcing our Series B funding",
    "context": {
      "announcement": "We raised $50M Series B led by Sequoia",
      "platforms": ["twitter", "linkedin"],
      "tone": "professional but exciting",
      "tags": ["#funding", "#growth", "#AI"]
    }
  }'

Example: Multi-Agent Workflow

curl -X POST https://api.mindra.co/v1/orchestrate \
  -H "Authorization: Bearer $MINDRA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "Launch complete product announcement: emails + social media + press release",
    "context": {
      "product": "DevAI Assistant v2.0",
      "launchDate": "2025-12-01",
      "targetAudience": "software engineers and CTOs",
      "keyFeatures": [
        "AI-powered code completion",
        "Intelligent refactoring",
        "Security scanning"
      ]
    },
    "mode": "PARALLEL"
  }'

Using Webhooks

Instead of polling for status, receive notifications:

curl -X POST https://api.mindra.co/v1/orchestrate \
  -H "Authorization: Bearer $MINDRA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "Create an email campaign...",
    "context": {...},
    "webhook": {
      "url": "https://your-app.com/webhooks/mindra",
      "events": ["execution.completed", "execution.failed"],
      "secret": "your_webhook_secret_for_validation"
    }
  }'

Your webhook endpoint will receive:

{
  "event": "execution.completed",
  "executionId": "exec_abc123def456",
  "timestamp": "2025-11-10T10:30:04Z",
  "signature": "sha256=...",
  "data": {
    "status": "COMPLETED",
    "result": {...},
    "metadata": {
      "actualCost": 0.50,
      "actualDuration": 4823
    }
  }
}

Verifying Webhook Signatures

import hmac
import hashlib

def verify_webhook(payload, signature, secret):
    expected = hmac.new(
        secret.encode(),
        payload.encode(),
        hashlib.sha256
    ).hexdigest()

    return hmac.compare_digest(
        f"sha256={expected}",
        signature
    )

# In your webhook handler
@app.post("/webhooks/mindra")
def handle_webhook(request):
    signature = request.headers.get("X-Mindra-Signature")
    payload = request.body.decode()

    if not verify_webhook(payload, signature, WEBHOOK_SECRET):
        return {"error": "Invalid signature"}, 401

    data = json.loads(payload)

    if data["event"] == "execution.completed":
        # Handle completion
        print(f"Execution {data['executionId']} completed!")
        print(f"Result: {data['data']['result']}")

    return {"status": "ok"}

Common Patterns

Pattern 1: Poll Until Complete

#!/bin/bash

EXECUTION_ID="exec_abc123def456"

while true; do
  RESPONSE=$(curl -s https://api.mindra.co/v1/executions/$EXECUTION_ID \
    -H "Authorization: Bearer $MINDRA_API_KEY")

  STATUS=$(echo $RESPONSE | jq -r '.status')

  echo "Status: $STATUS"

  if [ "$STATUS" = "COMPLETED" ] || [ "$STATUS" = "FAILED" ]; then
    echo "Final result:"
    echo $RESPONSE | jq
    break
  fi

  sleep 2
done

Pattern 2: Async with Webhook (Node.js)

const MINDRA_API_KEY = process.env.MINDRA_API_KEY;

async function orchestrateAsync(query, context) {
  const response = await fetch('https://api.mindra.co/v1/orchestrate', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${MINDRA_API_KEY}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      query,
      context,
      webhook: {
        url: 'https://myapp.com/webhooks/mindra',
        events: ['execution.completed', 'execution.failed'],
      },
    }),
  });

  const data = await response.json();
  console.log(`Execution started: ${data.executionId}`);

  return data.executionId;
}

// Your webhook handler (Express.js)
app.post('/webhooks/mindra', (req, res) => {
  const { event, executionId, data } = req.body;

  if (event === 'execution.completed') {
    console.log(`Execution ${executionId} completed!`);
    console.log('Result:', data.result);

    // Process the result...
  }

  res.json({ status: 'ok' });
});

Pattern 3: Batch Processing (Python)

import asyncio
import aiohttp

MINDRA_API_KEY = os.getenv('MINDRA_API_KEY')

async def orchestrate_batch(queries):
    async with aiohttp.ClientSession() as session:
        tasks = []

        for query_data in queries:
            task = session.post(
                'https://api.mindra.co/v1/orchestrate',
                headers={
                    'Authorization': f'Bearer {MINDRA_API_KEY}',
                    'Content-Type': 'application/json',
                },
                json=query_data
            )
            tasks.append(task)

        responses = await asyncio.gather(*tasks)

        execution_ids = []
        for resp in responses:
            data = await resp.json()
            execution_ids.append(data['executionId'])

        return execution_ids

# Usage
queries = [
    {
        'query': 'Create email campaign for Product A',
        'context': {'product': 'Product A'}
    },
    {
        'query': 'Create email campaign for Product B',
        'context': {'product': 'Product B'}
    },
    {
        'query': 'Create email campaign for Product C',
        'context': {'product': 'Product C'}
    },
]

execution_ids = asyncio.run(orchestrate_batch(queries))
print(f"Started {len(execution_ids)} executions")

Error Handling

Check for Errors

import requests

response = requests.post(
    'https://api.mindra.co/v1/orchestrate',
    headers={'Authorization': f'Bearer {MINDRA_API_KEY}'},
    json={'query': '...', 'context': {...}}
)

if response.status_code == 202:
    data = response.json()
    execution_id = data['executionId']
    print(f"Success! Execution ID: {execution_id}")

elif response.status_code == 400:
    error = response.json()
    print(f"Bad Request: {error['message']}")

elif response.status_code == 402:
    error = response.json()
    print(f"Insufficient Balance: {error['message']}")
    print(f"Top up at: {error['topUpUrl']}")

elif response.status_code == 429:
    error = response.json()
    retry_after = error['retryAfter']
    print(f"Rate limited. Retry after {retry_after} seconds")

else:
    print(f"Error {response.status_code}: {response.text}")

Testing

Health Check

curl https://api.mindra.co/health

Expected response:

{
  "status": "healthy",
  "version": "1.0.0",
  "timestamp": 1699632000
}

Test Authentication

curl https://api.mindra.co/v1/auth/test \
  -H "Authorization: Bearer $MINDRA_API_KEY"

Expected response:

{
  "authenticated": true,
  "keyId": "key_abc123",
  "permissions": ["orchestrate", "agents:read"],
  "accountTier": "DEVELOPER"
}

Next Steps

Now that you've made your first requests:

  1. API Reference - Explore all endpoints
  2. Build Your Own Agent - Deploy custom agents
  3. Enterprise Features - Agent deployment options and custom SLAs
  4. Wallet Management - FIAT and crypto payments

Troubleshooting

Problem: 401 Unauthorized

Cause: Invalid or missing API key

Solution: Check your API key is correct and included in the header

Problem: 402 Payment Required

Cause: Insufficient wallet balance

Solution: Top up at app.mindra.co/wallet

Problem: 429 Rate Limit

Cause: Too many requests

Solution: Implement exponential backoff or upgrade your tier

Problem: 500 Server Error

Cause: Internal server error

Solution: Check status.mindra.co or contact support

Support

Next: API Reference →

Found an issue? Report it on GitHub →