MFM API v1

Auth Model

1. Sign in to the API Portal (Supabase authentication) and complete email verification.
2. Create an API key with POST /v1/auth/api-keys using Authorization: Bearer <supabase_access_token>.
3. Use the returned API key for API calls:
   • Authorization: Bearer mfm_live_...

Email verification is required before creating API keys.

Core Resources

• GET /v1/episodes
• GET /v1/episodes/{episode_id}
• GET /v1/episodes/{episode_id}/segments
• GET /v1/episodes/{episode_id}/insights
• GET /v1/episodes/{episode_id}/people
• GET /v1/insights
• GET /v1/insights/{insight_id}
• GET /v1/insights/{insight_id}/related
• GET /v1/people
• GET /v1/people/{person_id}
• GET /v1/segments/{segment_id}
• GET /v1/segments/mfm

Machine-Readable Contracts

• GET /v1/contracts

This endpoint returns a discoverable contract payload for automation clients, including endpoint metadata and OpenAPI version.

Cursor Pagination

List endpoints are iterator-friendly with opaque page tokens.

• GET /v1/people?limit=50&page_token=<token>
• GET /v1/episodes?limit=50&page_token=<token>
• GET /v1/insights?limit=50&page_token=<token>

The limit parameter controls page size. If another page is available, the response includes:

• next_page_token in the JSON payload
• X-Next-Page-Token response header

Example successful page response:

{
  "items": [],
  "next_page_token": "MTA=",
  "total_count": 125
}

Markdown Mode

All core GET routes accept markdown output:

• Query param: ?format=markdown
• Header: Accept: text/markdown

This mode is intended for agent workflows that prefer LLM-friendly output.

Rate Limits

Rate limits are applied per API key.

• Default per-minute and per-day limits are set at key creation.

Telemetry Headers

Automations should read quota headers for robust retries:

• X-RateLimit-Limit-Minute
• X-RateLimit-Remaining-Minute
• X-RateLimit-Limit-Day
• X-RateLimit-Remaining-Day
• Retry-After (present on 429 responses)
• X-Request-ID

Request Tracing

Every response includes X-Request-ID.

Server logs are structured JSON and include:

• request ID
• path + path template
• status code
• duration
• auth context