Updated 2026-05-04

API Reference

Multiplist exposes a REST API at /api/v1/* for headless integrations. For tool-style access from MCP clients (Claude Desktop, ChatGPT, agent frameworks), use the MCP endpoint at /mcp instead — it takes a different token type. See Authentication for the full split.

# Base URL

https://multiplist.ai/api/v1

# Authentication

Every request requires an API Key. Generate one in Settings → API Keys inside the Multiplist app.

Authorization: Bearer mp_live_…

API Keys use the mp_live_ prefix, are SHA-256 hashed at rest, and carry scoped permissions. They are not valid on the /mcp endpoint — use an MCP Token for that.

# Bring-your-own-LLM headers

Endpoints that run inference (/extract, /synthesize, /batch/extract) require you to supply an LLM key on each request:

X-LLM-Provider: openai      # or "anthropic"
X-LLM-API-Key: sk-…

Multiplist never stores these — they're used for the lifetime of the request and discarded.

# Scopes

ScopeWhat it grants
extractPOST /extract, POST /batch/extract, POST /batch/:jobId/cancel
readGET /seeds/:sourceId, GET /batch/:jobId, GET /batch
synthesizePOST /synthesize (also requires extract and read)

Grant the minimum scope needed at key creation.

# Rate limiting

Rate limits are tiered by plan:

Exceeding the limit returns HTTP 429 with a Retry-After header.

# Response envelope

Every response — success or error — uses the same shape:

Success:

{
  "ok": true,
  "data": { },
  "meta": {
    "requestId": "req_abc123",
    "duration_ms": 42,
    "version": "v1"
  }
}

Error:

{
  "ok": false,
  "error": {
    "code": "INVALID_API_KEY",
    "message": "The provided API key is invalid or has been revoked.",
    "details": { "keyPrefix": "mp_live_xxxxxxxx..." }
  },
  "meta": { "requestId": "req_abc123", "version": "v1" }
}

Common error codes: INVALID_API_KEY, INSUFFICIENT_SCOPE, MISSING_LLM_KEY, INVALID_REQUEST, CONTENT_TOO_LARGE, RATE_LIMITED, NOT_FOUND, INTERNAL_ERROR.

# Endpoints

# POST /extract

Send content (a conversation transcript, document, voice memo, article) and get back structured seeds. Requires the extract scope and X-LLM-Provider / X-LLM-API-Key headers.

Body:

{
  "content": "string (required, ≤ 500KB)",
  "source_type": "conversation | document | voice_memo | article",
  "platform": "string",
  "title": "string",
  "container_id": "uuid (required, but informational only — sources are vault-native)",
  "skill_id": "uuid",
  "categories": "all" ,
  "options": {
    "confidence_threshold": "high | medium | low",
    "include_emergence": true,
    "include_provenance": true
  }
}

# GET /seeds/:sourceId

Retrieve all seeds extracted from a given source. Requires the read scope.

# POST /synthesize

Cross-source pattern detection. Pass 2–10 source IDs and an optional focus prompt to surface convergence, contradictions, and evolution across them. Requires extract + read scopes and BYO-LLM headers.

Body:

{
  "source_ids": ["uuid", "uuid"],
  "focus": "string",
  "options": {
    "detect_convergence": true,
    "detect_contradictions": true,
    "detect_evolution": true
  }
}

# POST /batch/extract

Queue many extractions in a single batch job. Requires the extract scope.

# GET /batch/:jobId

Poll progress on a batch job. Requires the read scope.

# POST /batch/:jobId/cancel

Cancel an in-flight batch job. Requires the extract scope.

# GET /batch

List recent batch jobs for the calling key's user. Requires the read scope.