Mastra Development API

Interact with the Mastra dev server API to debug agents, view conversations, inspect tools and workflows, and access observability data.

Quick Start

Agent Debugging

Run these scripts/... commands from the skills/mastra-api/ directory. From repo root, prefix them with skills/mastra-api/.

# Get latest conversation
scripts/get_latest_thread.sh <agent-id> [port]

# Debug errors
scripts/debug_agent_error.sh <agent-id> [port]

# View thread messages
curl --globoff -sS \
  "http://localhost:4111/api/memory/threads/THREAD_ID/messages?page=0&perPage=50&agentId=my-agent&orderBy[field]=createdAt&orderBy[direction]=DESC" \
  | jq '.'

Tools and Workflows

Run these scripts/... commands from the skills/mastra-api/ directory. From repo root, prefix them with skills/mastra-api/.

# List all tools
scripts/list_tools.sh [port]

# List all workflows
scripts/list_workflows.sh [port]

# Get workflow details
scripts/get_workflow_details.sh <workflow-name> [port]

# Get workflow runs
scripts/get_workflow_runs.sh <workflow-name> [port]

Resource Listing

# List all agents
curl -sS http://localhost:4111/api/agents | jq 'keys'

# List all tools
curl -sS http://localhost:4111/api/tools | jq 'keys'

# List all workflows
curl -sS http://localhost:4111/api/workflows | jq 'keys'

Common Tasks

Debug Agent Failures

1. Get latest thread: scripts/get_latest_thread.sh my-agent
2. Check for errors: scripts/debug_agent_error.sh my-agent
3. Inspect message content for error details

Inspect Available Resources

# See what tools an agent can use
curl -sS http://localhost:4111/api/agents | \
  jq '.["my-agent"].tools | keys'

# See what workflows an agent can invoke
curl -sS http://localhost:4111/api/agents | \
  jq '.["my-agent"].workflows | keys'

# List all registered tools
scripts/list_tools.sh

# List all registered workflows
scripts/list_workflows.sh

Debug Workflows

# Get workflow structure and steps
scripts/get_workflow_details.sh my-workflow

# Check workflow execution history
scripts/get_workflow_runs.sh my-workflow

# Find failed workflow runs
scripts/get_workflow_runs.sh my-workflow | \
  jq '.runs[] | select(.status == "failed")'

Check Tool/Workflow Schemas

# Get tool input parameters
curl -sS http://localhost:4111/api/tools | \
  jq '.YOUR_TOOL_KEY.inputSchema | fromjson.json.properties | keys'

# Get workflow input requirements
curl -sS http://localhost:4111/api/workflows/my-workflow | \
  jq '.inputSchema | fromjson.json.properties | keys'

Access Observability Data

# Get traces
curl -sS http://localhost:4111/api/observability/traces | jq '.'

# Get logs
curl -sS http://localhost:4111/api/logs | jq '.'

Important Notes

Use --globoff with curl

Query parameters with brackets must use --globoff:

curl --globoff -sS "...&orderBy[field]=updatedAt&orderBy[direction]=DESC"

Without --globoff, curl treats [...] as character ranges.

API Base URLs

Standard: http://localhost:4111/api

Swagger Documentation

Complete interactive API docs: http://localhost:4111/swagger-ui

Debugging Workflow

When UI doesn't show errors clearly:

1. Get latest thread - scripts/get_latest_thread.sh <agent-id>
2. Extract thread ID from response
3. Get messages - Use thread ID to fetch conversation
4. Look for errors - Search for "error" or "failed" fields
5. Review content - Inspect message content for details

This is the fastest way to debug agent issues.

Reference

See references/api_endpoints.md for:

• Complete endpoint reference
• Query parameter details
• Pagination and ordering
• Project-specific configurations
• Error handling patterns

See references/tools_and_workflows.md for:

• Tools API documentation
• Workflows API documentation
• Schema parsing examples
• Integration with agents
• Common debugging patterns

Scripts

Agent Debugging

• scripts/get_latest_thread.sh <agent-id> [port] [detailed] - Get latest conversation thread
• scripts/debug_agent_error.sh <agent-id> [port] - Quick error debugging

Tools & Workflows

• scripts/list_tools.sh [port] - List all registered tools with descriptions
• scripts/list_workflows.sh [port] - List all registered workflows with steps
• scripts/get_workflow_details.sh <workflow-name> [port] - Get detailed workflow information
• scripts/get_workflow_runs.sh <workflow-name> [port] [page] [perPage] - Get workflow execution history