Mastra API

Setup

The CLI can interact with any reachable Mastra server:

• Local dev server: http://localhost:4111 from npm run dev
• Mastra platform deployment: Use the deployment URL
• Remote/self-hosted server: Use the server URL
• Hosted Mastra Platform Observability: https://observability.mastra.ai (auto-targeted by trace, log, score, and metric commands)

For local servers, mastra api defaults to http://localhost:4111:

For Mastra platform or remote servers, pass --url. For the sake of brevity in examples, $MASTRA_URL is used as a placeholder for the actual server URL which you need to set yourself:

For Factory operations, activate the mastra-factory skill first. Use the user’s actual Factory instance URL (not the platform API/dashboard URL). Explicit --url works from an empty directory. Recognized hosted Factory domains use saved mastra auth login credentials; check mastra auth whoami and offer login if needed. Custom/self-hosted deployments may use different authentication. Factory discovery uses bundled leaf contracts and root-level /web/* routes, not the runtime schema probe below.

For an unauthenticated local runtime server, verify the server once with a cheap check before resource calls:

If $MASTRA_URL is not reachable, ask for the correct deployment URL and set --url accordingly. For authenticated targets, use a supported read-only CLI call instead of treating an unauthenticated schema-probe failure as unreachability. Let the CLI use saved login on recognized platform hosts; for custom servers, have the user configure the deployment’s approved authentication mechanism outside chat. Never request secret values in chat or inspect saved credential files.

For authenticated servers, pass repeatable headers:

Target resolution

Runtime commands (agent, workflow, tool, mcp, thread, memory, dataset, experiment) resolve the target in this order:

1. --url <url> for an explicit remote or self-hosted server.
2. http://localhost:4111 for a local mastra dev server.
3. .mastra-project.json for a Mastra platform project.

Observability commands (trace, log, score, metric) target https://observability.mastra.ai by default instead of a project deployment URL. The CLI resolves credentials in this order:

1. Explicit Authorization and X-Mastra-Project-Id headers passed with --header.
2. MASTRA_PLATFORM_ACCESS_TOKEN and MASTRA_PROJECT_ID from the environment.
3. Project metadata from .mastra-project.json for the project ID.
4. The Mastra CLI login token as an auth fallback.

For observability calls, no --url or --header is required if MASTRA_PLATFORM_ACCESS_TOKEN and MASTRA_PROJECT_ID are set, or if .mastra-project.json is present:

Pass --url and --header only when overriding the hosted observability target or credentials.

Decision flow

1. Clear read-only request (list X, latest X, get X, summarize recent X): infer the resource and use the fast path first.
2. Mutating request (create, update, delete, run, resume, execute), unclear resource/action, failed fast path, or exact syntax requested: use narrow CLI discovery.
3. JSON input uncertain: use command-specific --schema.
4. Route behavior confusing: inspect /api/system/api-schema.

Start with these command groups when present; verify with mastra api --help if the group fails.

Fast path for read-only requests

Use conventional list/get commands first. Keep pages small and pipe through jq immediately.

Latest item:

Recent items:

When the shape is known, project only the fields needed for the task:

Get details:

When the shape is known, project only the fields needed for the task:

If a resource does not support the conventional shape, fall back to narrow --help for that resource/action.

Output control

• Do not use unfiltered --pretty during exploration.
• Always project list/get output with jq before reading details.
• Use perPage:1 for latest and perPage:10 or less for recent lists.
• If output is truncated or noisy, rerun with a narrower jq projection. Do not increase terminal output just to see more raw JSON.
• Fetch full JSON only when the user asks for raw output or compact projections are insufficient.

Fallback discovery

Use the narrowest discovery command that can answer the question. Example for traces:

Use trace query instead of trace list when selection requires recursive predicates, metadata filters, or conditions over related spans, scores, or feedback. First use trace query --help to confirm that the installed CLI exposes the command. The inline JSON query is required, and its cursor-bearing response stays nested under data. Read trace-query.md for availability checks, the division between CLI schema discovery and canonical documentation, query construction, and pagination.

Use top-level help only when the resource is unknown:

Read --schema output as the contract:

• command: usage string
• examples: known-good examples
• positionals: required path/identity arguments
• input.required: whether JSON input is required
• input.schema: accepted CLI JSON input, including query/body fields
• schemas: raw server route schemas for deeper debugging

JSON and output contract

mastra api accepts at most one inline JSON object as input. Do not use stdin or files unless the user explicitly asks.

For non-GET routes, the CLI splits the one JSON object into query parameters and request body according to the server route schema.

Output envelopes:

Error handling

• INVALID_JSON: fix shell quoting; input must be one JSON object.
• MISSING_INPUT: run the same command with --schema and supply required JSON.
• MISSING_ARGUMENT: provide the positional shown by --help / --schema.
• HTTP_ERROR: inspect error.details, then compare against --schema or route schema.
• REQUEST_TIMEOUT: retry with larger --timeout, especially for workflow execution.
• SERVER_UNREACHABLE: verify the URL and the server check. If localhost is not running, ask whether the user wants to use a Mastra platform deployment or another remote server URL.

Route-level debugging

If CLI behavior seems wrong, inspect the route-derived schema manifest instead of guessing.

Find routes by path:

Inspect one route:

Known notes

• Tool and MCP tool execution accept raw tool input; explicit { "data": ... } also works.
• Workflow resume only works for suspended workflow runs.
• Working memory update requires the agent’s memory to have working memory enabled.
• Empty lists may simply mean the server has no matching stored data yet.
• trace list and trace get return lightweight payloads by default (no span input, output, attributes, or metadata). Pass --verbose to fetch full span records, or use trace span <traceId> <spanId> to fetch one specific span in full.
• trace query requires inline JSON, queries completed traces, and preserves its opaque cursor at data.page.next. Pass that value unchanged as page.after with the same query shape.