API Overview

Last updated: December 18, 2025

The MIR API lets partners submit user activity and query neutral history signals. Here's what each capability does and why it matters.

Core Capabilities

Submit Events

When users do things on your platform—complete purchases, post reviews, finish projects—you tell MIR about it. These events build the user's portable participation history that travels with them across the internet.

Events are simple: who did it, what happened, and optionally how significant it was. MIR handles the rest.

Query History Signals

Before making decisions about a user, ask MIR what history exists. You'll get neutral facts: how many events, how many platforms, how recent. Use this as context for your own judgment—MIR doesn't tell you what to decide.

History tiers (0, 1, 2, 3) tell you depth only — not quality, not trustworthiness. Tier 0 isn't negative — it just means no recorded activity yet.

Account Linking

Users can link their identity across platforms. When they do, their activity on your platform contributes to their portable history, and you can see history they've built elsewhere.

Linking is always user-initiated. You can't look up arbitrary users—only those who've chosen to connect with you.

Available Endpoints

POST /events

Submit a participation event for a user on your platform. Creates the user record automatically if they don't exist yet.

POST /resolve

Look up a user's history signals. Returns tier, event count, partner count, and recency—neutral facts only, not scores or judgments.

POST /partners/link/invite

Generate an invite link for a user to connect their MIR account to your platform. They click the link, log in to MIR, and confirm.

POST /partners/link/code

Generate a short verification code for user-initiated linking. Useful when users want to link from your settings page.

GET /partners/link/status

Check if a user has linked their MIR account. Use this to show "Connected to MIR" status in your UI.

GET /events

List events you've submitted. Useful for debugging and verifying your integration is working.

Authentication: All partner endpoints require your API key in the x-api-key header. You receive this when your partner application is approved.

Agent Management (Enterprise)

Enterprise partners can register AI agents and service accounts with scoped permissions, event-type allowlists, and independent API keys. The full agent lifecycle is managed through the API — no portal required.

POST /v1/agents

Register an agent with a name, type (AI_AGENT or SERVICE_ACCOUNT), permission preset, and allowed event types. Returns a scoped API key shown once.

GET /v1/agents

List all agents for your organization with status, auth mode, and last activity.

POST /v1/agents/:id/suspend · /revoke · /reactivate

Suspend temporarily, revoke permanently (nulls the key hash), or reactivate a suspended agent. All actions are instant and audited.

POST /v1/agents/:id/key/rotate

Generate a new API key. The old key is invalidated immediately.

AI Agent Guardrails: Agents typed as AI_AGENT enforce idempotency, cap bulk operations, block the admin preset, and require an explicit event-type allowlist. Full documentation is available in the Enterprise Dashboard.

Agent Genealogy

When AI agents spawn subordinate agents, MIR tracks the full lineage — who created whom, at what depth, and under which enterprise. MIR records the genealogy; your enterprise decides what to do about it.

POST /v1/agents/:id/spawn

Spawn a child agent from an existing parent. The child automatically joins the parent's enterprise with inherited (never escalated) permissions. Requires enterprise spawn policy to be enabled.

GET /v1/agents/:id/lineage

Returns the full spawn ancestry chain from root orchestrator to self, plus direct children. Use this to reconstruct how any agent came to exist.

GET /v1/agents/tree

Returns the complete agent genealogy tree for the enterprise. Filterable by root agent ID. Shows spawn depth, membership source, and status for every agent in the hierarchy.

POST /v1/agents/:id/revoke-descendants

Kill switch — revoke an agent and all of its descendants. API keys are nullified permanently. Each revocation is individually audited.

Spawn guardrails: Child agents can never have more permissions, higher rate limits, or broader event-type access than their parent. Enterprise policy controls max spawn depth and optional human approval thresholds.

What MIR Doesn't Do

No scores or ratings. MIR provides history depth, not trust scores. You decide what the data means.
No user surveillance. You can only see users who've linked to your platform or whose events you submitted.
No automated decisions. MIR gives you context. Your policies determine the outcome.
No data selling. User history exists to serve users, not to be monetized.

Event Types

Events use the format mir.category.action—like mir.transaction.completed or mir.account.verified.

Common categories include commerce events (transactions, chargebacks), community events (content, moderation), and platform events (verification, subscriptions). The Partner Guide has a complete reference.

Ready to Integrate?

The Partner Guide has everything you need: code examples, event type reference, and implementation patterns.

Partner Portal Integration Guide

Questions?

If you're evaluating MIR or have questions about the API, reach out. We're happy to discuss your use case.