MindraDocs

API Reference

5 min read

Complete reference for all Mindra Platform API endpoints.

Base URL

https://api.mindra.co

Authentication

All API requests require authentication using an API key in the Authorization header:

Authorization: Bearer mk_your_api_key

See Authentication Guide for details.

API Version

Current API version: v1

All endpoints are prefixed with /v1:

https://api.mindra.co/v1/orchestrate
https://api.mindra.co/v1/agents
https://api.mindra.co/v1/executions/:id

Endpoints Overview

Orchestration

Agents

Executions

Wallet

API Keys

  • GET /v1/api-keys - List API keys
  • POST /v1/api-keys - Create API key
  • PATCH /v1/api-keys/:id - Update API key
  • DELETE /v1/api-keys/:id - Delete API key

Health & Status

  • GET /health - Health check
  • GET /v1/auth/test - Test authentication

Request Format

Headers

All requests must include:

Authorization: Bearer mk_your_api_key
Content-Type: application/json

Optional headers:

X-Request-ID: unique_request_id        # For request tracing
X-Idempotency-Key: unique_key          # For idempotent operations

Request Body

JSON format for POST/PATCH requests:

{
  "query": "Your instruction",
  "context": {
    "key": "value"
  }
}

Response Format

Success Response

HTTP Status: 200 OK or 202 Accepted

{
  "executionId": "exec_abc123",
  "status": "PENDING",
  "data": {...}
}

Error Response

HTTP Status: 4xx or 5xx

{
  "error": "ERROR_CODE",
  "message": "Human-readable error message",
  "details": "Additional information",
  "requestId": "req_abc123"
}

Error Codes

CodeHTTP StatusDescription
INVALID_REQUEST400Malformed request body
UNAUTHORIZED401Invalid or missing API key
FORBIDDEN403Insufficient permissions
INSUFFICIENT_BALANCE402Wallet balance too low
NOT_FOUND404Resource not found
RATE_LIMIT_EXCEEDED429Too many requests
INTERNAL_ERROR500Server error
SERVICE_UNAVAILABLE503Temporary unavailability

Rate Limits

TierRequests/MinuteRequests/Day
Developer10010,000
Business500100,000
EnterpriseCustomCustom

Response headers include rate limit information:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1699632000

Pagination

List endpoints support pagination:

GET /v1/executions?page=2&limit=50

Parameters:

  • page (default: 1) - Page number
  • limit (default: 20, max: 100) - Items per page

Response includes pagination metadata:

{
  "data": [...],
  "pagination": {
    "page": 2,
    "limit": 50,
    "total": 237,
    "pages": 5,
    "hasNext": true,
    "hasPrev": true
  }
}

Filtering & Sorting

List endpoints support filtering and sorting:

GET /v1/executions?status=COMPLETED&sort=-createdAt

Common filters:

  • status - Filter by status
  • vertical - Filter by agent vertical
  • startDate / endDate - Date range

Sort format:

  • sort=field - Ascending
  • sort=-field - Descending (prefix with -)

Idempotency

POST requests support idempotency using the X-Idempotency-Key header:

curl -X POST https://api.mindra.co/v1/orchestrate \
  -H "Authorization: Bearer $API_KEY" \
  -H "X-Idempotency-Key: unique_key_123" \
  -d '{...}'

If you retry with the same key within 24 hours, you'll receive the same response (cached).

Webhooks

Configure webhooks to receive event notifications:

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

Webhook events:

  • execution.started - Execution began
  • execution.completed - Execution finished successfully
  • execution.failed - Execution failed
  • agent.started - Individual agent started
  • agent.completed - Individual agent completed

Webhook payload:

{
  "event": "execution.completed",
  "executionId": "exec_abc123",
  "timestamp": "2025-11-10T10:30:00Z",
  "signature": "sha256=...",
  "data": {...}
}

Verify 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)

SDKs

Official SDKs available:

Node.js

npm install @mindra/sdk

import { Mindra } from '@mindra/sdk';

const mindra = new Mindra({ apiKey: process.env.MINDRA_API_KEY });

const execution = await mindra.orchestrate({
  query: 'Create an email campaign...',
  context: {...}
});

Python

pip install mindra-sdk

from mindra import Mindra

mindra = Mindra(api_key=os.getenv('MINDRA_API_KEY'))

execution = mindra.orchestrate(
    query='Create an email campaign...',
    context={...}
)

Go

go get github.com/mindra-co/mindra-go

import "github.com/mindra-co/mindra-go"

client := mindra.NewClient(os.Getenv("MINDRA_API_KEY"))

execution, err := client.Orchestrate(ctx, &mindra.OrchestrationRequest{
    Query: "Create an email campaign...",
    Context: map[string]interface{}{...},
})

API Endpoints

Explore detailed documentation for each endpoint:

Testing

Sandbox Environment

Test your integration safely:

https://sandbox-api.mindra.co

Sandbox features:

  • No charges applied
  • Simulated agent responses
  • Same API structure as production
  • Separate API keys (prefix: mk_test_)

Example: Sandbox Request

curl -X POST https://sandbox-api.mindra.co/v1/orchestrate \
  -H "Authorization: Bearer mk_test_your_sandbox_key" \
  -d '{
    "query": "Test query",
    "context": {}
  }'

Support

Start with: Orchestration API →

Found an issue? Report it on GitHub →