MixMaster Pro Agent API

{
  "api_key": "mmp_agent_xxxxxxxxxxxxxxxx"",
  "prefix": "mmp_agent_Ep8I"",
  "created_at": "2026-06-20T12:00:00.000Z""
}
The full key is shown once at creation. Copy it immediately.

Manage keys in Account → API Key. Copy the full key when shown - it is not displayed again.

{ "agent_id": "my-integration", "label": "Production server" }

{
  "access_token": "eyJhbGciOiJIUzI1NiIs..."",
  "expires_in": 3600,
  "token_type": "Bearer""
}

Browser session cookie minting is supported for interactive testing only. Production integrations should use the Account API key.

Token revocation - session cookie plus token id or raw token:

curl -X POST https://mixmasterpro.io/agent-api/auth/revoke \
  -H "Content-Type: application/json" \
  --cookie "mmp_auth_session=YOUR_SESSION" \
  -d '{"access_token":"YOUR_AGENT_TOKEN"}'

{
  "id": "43bfb582-b321-43a4-af10-825ea64714bc"",
  "job_id": "43bfb582-b321-43a4-af10-825ea64714bc"",
  "status": "processing""
}
Repeat every 2-3 seconds until status is "completed" or "failed".

Common mistake: calling GET /agent-api/analyses/{analysis_id} before completion returns 404. Poll with job_id until status is completed.

When status is completed, the API returns only the public fields below. Do not expect diagnosis, action_items, raw_audio_full_json, canonical_v1, intelligence_packet, or Python analyzer payloads.

{
  "id": "YOUR_JOB_ID",
  "job_id": "YOUR_JOB_ID",
  "analysis_id": "YOUR_ANALYSIS_ID",
  "status": "completed",
  "mix_score": 87,
  "grade": "EXCELLENT",
  "analysis_url": "https://mixmasterpro.io/studio/analysis.details/YOUR_ANALYSIS_ID",
  "certificate_available": true,
  "certificate_url": "https://mixmasterpro.io/studio/shared.mix.score/YOUR_ANALYSIS_ID"
}

certificate_available: true when mix_score is 80 or higher. When eligible, certificate_url points to the Share Analysis Score page.

Grade labels match the certificate product: EXCEPTIONAL, EXCELLENT, VERY GOOD, GOOD MIX, and DECENT MIX. Users view and share certificates on MixMaster Pro - agents only receive eligibility and URLs.

Bearer-authenticated read-only endpoints for agent routing and commerce integrations:

• GET /agent-api/openapi.json - OpenAPI 3.0 spec generated from live routes
• /developers/swagger - Swagger UI in the MixMaster Pro site shell
• OpenAPI reference (schemas and samples) is embedded in Authentication, Upload, Analyses, Result contract, and Discovery APIs sections above.
• GET /agent-api/manifest - Agent discovery manifest for LLM and commerce integrations

Separate fixed windows per category (user, token, and IP composite checks):

• Token mint: 10 per user per hour (IP bucket at 2x)
• Uploads: 30 per hour per user and token
• Analyses: 20 per hour per user and token
• Discovery: 120 per minute per user and token

HTTP 429 responses include a Retry-After header.

Agent analysis consumes the same free monthly quota, monthly upload fair-use cap (300/month including revisions), Pro trial rules, and pay-as-you-go credits as the UI. Insufficient quota returns 403 with free_monthly_analysis_limit, monthly_analysis_upload_limit, or plan-specific messaging.

• Bearer tokens are opaque, hashed at rest, expiring, and revocable.
• No anonymous agent access or agent-side signup/payment flows.
• R2 keys are ownership-checked before analyze.
• Reviews and articles APIs are read-only for agents.
• Completed responses pass an internal forbidden-field guard before leaving the API.

See api/docs/agent/security.md in the repository for full threat model notes.

• Mint tokens server-side or in the user's authenticated browser - never embed session cookies in public clients.
• Store Bearer tokens securely and revoke them when the user disconnects your integration.
• Save job_id from POST /agent-api/analyses and poll GET /agent-api/analyses/{job_id} until status is completed.
• Read analysis_url from the completed poll response - there is no separate URL endpoint.
• After completion, GET /agent-api/analyses/{analysis_id} returns the same result if you only stored analysis_id.
• Poll with exponential backoff (start at 2-3s, cap around 15s).
• Send users to analysis_url on MixMaster Pro for action items, mentor chat, and certificates (requires their login).
• Do not fetch analysis_url from your backend - use mix_score, grade, and analysis_id from the Agent API response.
• Never expect diagnosis, action_items, raw_audio_full_json, or other internal analyzer fields.
• Handle 403 free_monthly_analysis_limit or monthly_analysis_upload_limit by surfacing upgrade or Studio+ contact paths in your agent UX.
• Use /agent-api/capabilities before promising Audio Tools features - they remain UI-only.