REST API

The Minded REST API provides programmatic access to query your agent's analytics events data and manage your agents. This allows you to build custom dashboards, reports, and integrations.

Overview

• Base URL: https://api.minded.com/api/v1

• Authentication: API key (Bearer token)

• Rate Limit: 3 requests per minute per IP

• Format: JSON

Endpoints

1. POST /api/v1/events/agent - Query agent analytics events

2. GET /api/v1/agents/list - List your organization's agents

Authentication

Getting Your API Key

Contact Minded team to receive an API key.

Using Your API Key

Include your API key in the Authorization header:

Authorization: Bearer your-api-key

API Endpoints

1. List Agents

GET /api/v1/agents

Get a list of all agents in your organization.

Response:

{
  "success": true,
  "data": [
    {
      "agentId": "agent-uuid-1",
      "displayName": "My Support Agent",
      "createdAt": "2025-10-01T10:30:00.000Z"
    },
    {
      "agentId": "agent-uuid-2",
      "displayName": "Sales Assistant",
      "createdAt": "2025-10-15T14:20:00.000Z"
    }
  ],
  "count": 2
}

2. Query Agent Events

POST /api/v1/events/agent

Query analytics events for your agents.

Request Format:

{
  "agentId": "your-agent-id",
  "filters": {
    "environment": "production",
    "sessionId": "session-uuid",
    "eventName": "node_execution",
    "startDate": "2025-10-01T00:00:00Z",
    "endDate": "2025-10-31T23:59:59Z"
  },
  "limit": 100,
  "offset": 0
}

Parameters

Parameter	Type	Required	Description
agentId	string	Yes	Your agent's UUID
filters.environment	string	No	One of: development, staging, production (default: production)
filters.sessionId	string	No	Filter by specific session
filters.eventName	string	No	Filter by event type
filters.startDate	string	No	Start date (ISO 8601 format)
filters.endDate	string	No	End date (ISO 8601 format)
limit	number	No	Records per page (1-1000, default: 100)
offset	number	No	Number of records to skip (default: 0)

Response Format

{
  "success": true,
  "data": [
    {
      "id": 1,
      "agentId": "your-agent-id",
      "sessionId": "session-uuid",
      "environment": "production",
      "eventName": "invocation_start",
      "payload": {
        "triggerBody": {
          "content": "Hello",
          "sessionId": "session-uuid"
        }
      },
      "created_at": "2025-10-14T08:37:44.000Z"
    }
  ],
  "count": 1,
  "limit": 100,
  "offset": 0
}

Event Types

The API returns various event types that track your agent's execution.

Built-in Events

The MindedJS SDK automatically tracks these events:

Event Type	Description	Payload Fields
invocation_start	Agent invocation started	triggerBody, triggerName
invocation_error	Error occurred during invocation	errorMessage, errorStack
node_execution	Flow node executed	nodeName, nodeType, nodeDisplayName, parameters (varies)

Custom Events

You can track custom events using the trackAnalyticsEvent() function in your agent code:

import { trackAnalyticsEvent } from '@minded-ai/mindedjs';

// In your tool, handler, or anywhere in your agent
await trackAnalyticsEvent(
  'custom_event_name',
  {
    // Any custom data you want to track
    userId: 'user-123',
    action: 'button_clicked',
    metadata: { page: 'checkout' },
  },
  state.sessionId,
);

Key Points:

• Custom events can have any eventName you choose

• Payload can be any JSON-serializable object

• Events are sent to the platform when deployed

• When running locally, events are only logged (not sent to backend)

• Analytics tracking never throws errors - failures are logged but don't affect execution

📚 For detailed usage examples and best practices, see the SDK Events - ANALYTICS_EVENT documentation.

Examples

List Your Agents

curl -X GET https://api.minded.com/api/v1/agents/list \
  -H "Authorization: Bearer your-api-key"

Basic Query

Fetch the last 50 events for your agent in production:

curl -X POST https://api.minded.com/api/v1/events/agent \
  -H "Authorization: Bearer your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "agentId": "your-agent-id",
    "filters": {
      "environment": "production"
    },
    "limit": 50
  }'

Query by Date Range

Fetch events from a specific time period:

curl -X POST https://api.minded.com/api/v1/events/agent \
  -H "Authorization: Bearer your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "agentId": "your-agent-id",
    "filters": {
      "environment": "production",
      "startDate": "2025-10-01T00:00:00Z",
      "endDate": "2025-10-31T23:59:59Z"
    },
    "limit": 100
  }'

Query by Session

Get all events for a specific session:

curl -X POST https://api.minded.com/api/v1/events/agent \
  -H "Authorization: Bearer your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "agentId": "your-agent-id",
    "filters": {
      "environment": "production",
      "sessionId": "session-uuid"
    }
  }'

Query by Event Type

Filter by specific event types:

curl -X POST https://api.minded.com/api/v1/events/agent \
  -H "Authorization: Bearer your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "agentId": "your-agent-id",
    "filters": {
      "environment": "production",
      "eventName": "node_execution"
    },
    "limit": 100
  }'

Rate Limiting

The API is limited to 3 requests per minute per IP address.

Error Codes

Code	Description
400	Bad request - missing required fields or invalid filters
401	Unauthorized - invalid or missing API key, or agent doesn't belong to your organization
429	Too many requests - rate limit exceeded
500	Internal server error - contact support