Orchestration API | Mindra Docs

Execute multi-agent workflows with the orchestration endpoint.

POST /v1/orchestrate

Start a new orchestration execution with automatic agent selection and workflow coordination.

Request

POST https://api.mindra.co/v1/orchestrate

Headers:

Authorization: Bearer mk_your_api_key
Content-Type: application/json
X-Idempotency-Key: unique_key (optional)

Body:

{
  "query": "string (required, 1-10000 chars)",
  "context": "object (optional)",
  "selectionCriteria": "object (optional)",
  "aggregationStrategy": "string (optional)",
  "mode": "string (optional)",
  "webhook": "object (optional)"
}

Parameters

`query` (required)

Natural language instruction describing what you want to accomplish.

Type: string Length: 1-10,000 characters Example:

{
  "query": "Create an email campaign for our product launch targeting developers"
}

`context` (optional)

Additional structured data to provide context for the execution.

Type: object Max depth: 10 levels Example:

{
  "context": {
    "productName": "DevAI Assistant",
    "targetAudience": "software engineers",
    "budget": 5000,
    "deadline": "2025-12-01"
  }
}

`selectionCriteria` (optional)

Control which agents are selected for the execution.

Type: object Fields:

verticals: string[] - Filter by agent verticals
requiredCapabilities: string[] - Required agent capabilities
maxAgents: number - Maximum agents to use (1-10, default: 5)
minConfidence: number - Minimum selection confidence (0-1, default: 0.7)

Example:

{
  "selectionCriteria": {
    "verticals": ["marketing", "analytics"],
    "requiredCapabilities": ["email_generation", "a_b_testing"],
    "maxAgents": 3,
    "minConfidence": 0.8
  }
}

`aggregationStrategy` (optional)

How to combine results from multiple agents.

Type: string Options:

merge (default) - Combine all agent outputs
best - Return output from highest-confidence agent
vote - Majority vote for conflicting outputs
custom - Use custom aggregation logic

Example:

{
  "aggregationStrategy": "merge"
}

`mode` (optional)

Execution mode for multiple agents.

Type: string Options:

SEQUENTIAL - Execute agents one after another
PARALLEL (default) - Execute agents concurrently
DAG - Execute based on dependency graph

Example:

{
  "mode": "PARALLEL"
}

`webhook` (optional)

Configure webhook notifications for execution events.

Type: object Fields:

url: string - Your webhook endpoint URL
events: string[] - Events to receive
secret: string - Secret for signature verification

Example:

{
  "webhook": {
    "url": "https://your-app.com/webhooks/mindra",
    "events": ["execution.completed", "execution.failed"],
    "secret": "your_webhook_secret"
  }
}

Response

Success (202 Accepted):

{
  "executionId": "exec_1a2b3c4d5e6f7g8h",
  "status": "PENDING",
  "estimatedCost": 0.75,
  "estimatedDuration": 8000,
  "selectedAgents": [
    {
      "id": "agent_email_campaign",
      "name": "email-campaign-agent",
      "vertical": "marketing",
      "estimatedCost": 0.50,
      "confidence": 0.92
    },
    {
      "id": "agent_social_media",
      "name": "social-media-agent",
      "vertical": "marketing",
      "estimatedCost": 0.25,
      "confidence": 0.85
    }
  ],
  "mode": "PARALLEL",
  "message": "Execution started",
  "statusUrl": "https://api.mindra.co/v1/executions/exec_1a2b3c4d5e6f7g8h"
}

Response Fields:

executionId - Unique execution identifier
status - Current status (PENDING, RUNNING, COMPLETED, FAILED)
estimatedCost - Estimated cost in USD
estimatedDuration - Estimated duration in milliseconds
selectedAgents - Agents selected for this execution
mode - Execution mode being used
message - Human-readable status message
statusUrl - URL to check execution status

Examples

Example 1: Marketing Campaign

curl -X POST https://api.mindra.co/v1/orchestrate \
  -H "Authorization: Bearer mk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "Create a comprehensive marketing campaign for our product launch",
    "context": {
      "product": {
        "name": "DevAI Assistant",
        "category": "developer tools",
        "price": "$29/month"
      },
      "target": {
        "audience": "software engineers",
        "geography": ["US", "EU", "APAC"],
        "companySize": ["startup", "mid-market"]
      },
      "goals": {
        "primary": "signups",
        "secondary": "brand awareness",
        "kpis": {
          "signupGoal": 1000,
          "conversionRate": 0.05
        }
      }
    },
    "selectionCriteria": {
      "verticals": ["marketing"],
      "maxAgents": 3
    },
    "mode": "PARALLEL"
  }'

Example 2: Cross-Border Payment

curl -X POST https://api.mindra.co/v1/orchestrate \
  -H "Authorization: Bearer mk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "Process international payment with currency conversion and compliance check",
    "context": {
      "transaction": {
        "amount": 50000,
        "fromCurrency": "USD",
        "toCurrency": "EUR"
      },
      "sender": {
        "name": "ACME Corp",
        "country": "US",
        "accountType": "business"
      },
      "recipient": {
        "name": "Supplier GmbH",
        "country": "DE",
        "iban": "DE89370400440532013000"
      },
      "compliance": {
        "kycRequired": true,
        "amlCheck": true,
        "sanctionsScreening": true
      }
    },
    "selectionCriteria": {
      "verticals": ["cross-border"],
      "requiredCapabilities": [
        "multi_currency_conversion",
        "compliance_check",
        "payment_routing"
      ]
    },
    "mode": "SEQUENTIAL"
  }'

Example 3: Supply Chain Optimization

curl -X POST https://api.mindra.co/v1/orchestrate \
  -H "Authorization: Bearer mk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "Optimize inventory levels and coordinate shipments for Q4",
    "context": {
      "warehouse": {
        "location": "US-WEST-1",
        "capacity": 100000,
        "currentUtilization": 0.73
      },
      "inventory": {
        "criticalSkus": ["SKU-001", "SKU-042", "SKU-137"],
        "targetStockLevel": "2-week supply",
        "reorderPoint": "1-week supply"
      },
      "shipments": {
        "activeShipments": 47,
        "pendingOrders": 123,
        "carriers": ["FedEx", "UPS", "DHL"]
      },
      "forecast": {
        "quarter": "Q4-2025",
        "expectedGrowth": 0.35,
        "peakDates": ["2025-11-25", "2025-12-20"]
      }
    },
    "selectionCriteria": {
      "verticals": ["supply-chain"],
      "requiredCapabilities": [
        "demand_forecasting",
        "inventory_optimization",
        "shipment_tracking"
      ],
      "maxAgents": 2
    },
    "mode": "DAG"
  }'

Example 4: With Webhook

curl -X POST https://api.mindra.co/v1/orchestrate \
  -H "Authorization: Bearer mk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "Generate quarterly financial report",
    "context": {
      "quarter": "Q3-2025",
      "includeProjections": true
    },
    "webhook": {
      "url": "https://your-app.com/webhooks/mindra",
      "events": [
        "execution.started",
        "execution.completed",
        "execution.failed"
      ],
      "secret": "whsec_your_webhook_secret"
    }
  }'

Error Responses

400 Bad Request - Invalid Query

{
  "error": "INVALID_REQUEST",
  "message": "Query is required and must be between 1 and 10000 characters",
  "field": "query",
  "requestId": "req_abc123"
}

402 Payment Required - Insufficient Balance

{
  "error": "INSUFFICIENT_BALANCE",
  "message": "Insufficient wallet balance. Required: $0.75, Available: $0.50",
  "requiredBalance": 0.75,
  "currentBalance": 0.50,
  "topUpUrl": "https://app.mindra.co/wallet/topup",
  "requestId": "req_abc123"
}

404 Not Found - No Suitable Agents

{
  "error": "NO_AGENTS_AVAILABLE",
  "message": "No agents found matching your selection criteria",
  "criteria": {
    "verticals": ["custom-vertical"],
    "requiredCapabilities": ["rare_capability"]
  },
  "suggestion": "Try relaxing your selection criteria or contact info@mindra.co to add custom agents",
  "requestId": "req_abc123"
}

429 Too Many Requests

{
  "error": "RATE_LIMIT_EXCEEDED",
  "message": "Rate limit exceeded. Try again in 42 seconds.",
  "retryAfter": 42,
  "limit": 100,
  "remaining": 0,
  "resetAt": "2025-11-10T15:31:00Z",
  "requestId": "req_abc123"
}

Execution Modes

SEQUENTIAL Mode

Agents execute one after another. Each agent receives the previous agent's output.

Use when:

Agents have dependencies
Output of one agent is input to another
Order matters

Example flow:

Agent A → Agent B → Agent C → Final Result

PARALLEL Mode (Default)

All agents execute simultaneously. Results are aggregated at the end.

Use when:

Agents are independent
Want fastest execution
Aggregating diverse outputs

Example flow:

        → Agent A →
Query → → Agent B → → Aggregate → Final Result
        → Agent C →

DAG Mode

Agents execute based on dependency graph. Some parallel, some sequential.

Use when:

Complex workflows
Mix of dependent and independent agents
Optimizing for both speed and dependencies

Example flow:

        → Agent A → Agent D →
Query →                       → Aggregate → Final Result
        → Agent B → Agent C →

Idempotency

Use X-Idempotency-Key header to safely retry requests:

curl -X POST https://api.mindra.co/v1/orchestrate \
  -H "Authorization: Bearer mk_your_api_key" \
  -H "X-Idempotency-Key: campaign_launch_2025_11_10" \
  -d '{
    "query": "Create email campaign...",
    "context": {...}
  }'

If you retry with the same key within 24 hours, you'll get the cached response without creating a duplicate execution.

Best Practices

1. Provide Rich Context

// ✅ Good - Rich context
{
  "query": "Create marketing campaign",
  "context": {
    "product": "DevAI Assistant",
    "targetAudience": "software engineers",
    "budget": 5000,
    "deadline": "2025-12-01",
    "channels": ["email", "social"],
    "tone": "technical but friendly"
  }
}

// ❌ Bad - Minimal context
{
  "query": "Create marketing campaign"
}

2. Use Selection Criteria

// ✅ Good - Specific criteria
{
  "query": "Process payment",
  "selectionCriteria": {
    "verticals": ["cross-border"],
    "requiredCapabilities": ["compliance_check"],
    "minConfidence": 0.8
  }
}

// ❌ Bad - No criteria (may select suboptimal agents)
{
  "query": "Process payment"
}

3. Choose Appropriate Mode

// ✅ Good - SEQUENTIAL for dependent tasks
{
  "query": "Generate report, analyze results, send email",
  "mode": "SEQUENTIAL"
}

// ❌ Bad - PARALLEL for dependent tasks (wrong results)
{
  "query": "Generate report, analyze results, send email",
  "mode": "PARALLEL"
}

4. Use Webhooks for Long Operations

// ✅ Good - Webhook for async
{
  "query": "Process 10,000 transactions",
  "webhook": {
    "url": "https://your-app.com/webhooks/mindra",
    "events": ["execution.completed"]
  }
}

// ❌ Bad - Polling (inefficient)
// Making repeated GET requests to check status

Rate Limits

Tier	Concurrent Executions	Queue Size
Developer	5	20
Business	25	100
Enterprise	Custom	Custom

If you exceed concurrent execution limit, new requests are queued.

Pricing

Orchestration costs are calculated as:

Total Cost = Sum of (Agent Base Price + Agent Variable Costs) + Platform Fee

Platform fee:

Developer: 10% of agent costs (min $0.01)
Business: 5% of agent costs
Enterprise: Custom pricing

Example:

Agent A: $0.50
Agent B: $0.30
Platform fee (10%): $0.08
Total: $0.88

Support

API Reference: docs.mindra.co/api-reference
Support: info@mindra.co
Status: status.mindra.co

Next: Agents API →

POST /v1/orchestrate

Request

Parameters

query (required)

context (optional)

selectionCriteria (optional)

aggregationStrategy (optional)

mode (optional)

webhook (optional)

Response

Examples

Example 1: Marketing Campaign

Example 2: Cross-Border Payment

Example 3: Supply Chain Optimization

Example 4: With Webhook

Error Responses

400 Bad Request - Invalid Query

402 Payment Required - Insufficient Balance

404 Not Found - No Suitable Agents

429 Too Many Requests

Execution Modes

SEQUENTIAL Mode

PARALLEL Mode (Default)

DAG Mode

Idempotency

Best Practices

1. Provide Rich Context

2. Use Selection Criteria

3. Choose Appropriate Mode

4. Use Webhooks for Long Operations

Rate Limits

Pricing

Support

`query` (required)

`context` (optional)

`selectionCriteria` (optional)

`aggregationStrategy` (optional)

`mode` (optional)

`webhook` (optional)