Retrieve the controlling source. One call.

Authentication

All requests authenticate with a bearer token in the Authorization header. Tokens are issued per design-partner organization and can be scoped to specific corpora.

Authorization: Bearer pmk_live_

POST /v1/retrieve

The primary endpoint. Returns the controlling source passage for a question over a specific corpus, with currency state, confidence, and a per-stage retrieval trace.

curl -X POST https://api.portmem.com/v1/retrieve \
  -H "Authorization: Bearer $PORTMEM_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "Is ASC 842 still the controlling lease standard?",
    "corpus": "fasb",
    "k": 3,
    "options": {
      "include_trace": true,
      "abstain_threshold": 0.40,
      "return_superseded": false
    }
  }'

Corpora

Design partners can ingest their own corpora. The hosted endpoint also exposes the published research corpora for evaluation.

Response schema

{
  "passage": "ASC 842 (Leases), effective for public entities for
              fiscal years beginning after Dec 15, 2018...",
  "source": {
    "id":        "fasb-asc-842",
    "type":      "accounting_standard",
    "effective": "2019-01-01",
    "issued_by": "FASB",
    "url":       "https://asc.fasb.org/842"
  },
  "currency":   "controlling",        // controlling | superseded | unknown
  "supersedes": "fasb-asc-840",
  "confidence": 0.97,
  "abstained":  false,
  "alternates": [
    { "source": {...}, "confidence": 0.42, "currency": "superseded" },
    { "source": {...}, "confidence": 0.18, "currency": "controlling" }
  ],
  "trace":      [...]                 // see "Per-stage trace"
}

All timestamps ISO 8601. currency: "unknown" means the system has no authority signal for this document (treat as caution).

Per-stage trace

Every retrieval produces an audit trail. This is what your compliance team reads to defend a decision. Each stage records what entered, what exited, and how long it took.

"trace": [
  {
    "stage":  "anchor",          // semantic candidate set
    "method": "phasegraph_pit",  // see paper 1
    "in":     1,
    "out":    32,
    "ms":     84
  },
  {
    "stage":  "authority",       // authority closure + frontier
    "method": "car_two_stage",   // see paper 4
    "in":     32,
    "out":    7,
    "ms":     41,
    "removed": ["fasb-asc-840", "fasb-asc-13"]
  },
  {
    "stage":  "frontier",        // controlling-document selection
    "method": "regime_router",   // see paper 3
    "in":     7,
    "out":    1,
    "ms":     29
  }
]

Abstention

When evidence is weak, contradictory, or the query is out of corpus scope, the response sets abstained: true and passage: null. This is the difference between PortMem and standard RAG: silence is a first-class return value.

{
  "passage":    null,
  "abstained":  true,
  "reason":     "low_confidence",   // low_confidence | out_of_scope | contradictory
  "confidence": 0.18,
  "trace":      [...]
}

Errors

Rate limits

Design-partner tokens default to:

• 10 requests per second per organization
• 50,000 requests per day per organization
• Burst tolerance: 50 in a 10-second window

Pilot agreements lift these for production load. All responses include X-RateLimit-Remaining and X-RateLimit-Reset headers.

SDKs

pip install portmem

from portmem import Client
client = Client(api_key="pmk_live_...")

result = client.retrieve(
  query="Is ASC 842 still in force?",
  corpus="fasb",
)
print(result.passage, result.currency)

npm i @portmem/client

import { PortMem } from "@portmem/client";
const pm = new PortMem({ apiKey: "pmk_live_..." });

const r = await pm.retrieve({
  query: "Is ASC 842 still in force?",
  corpus: "fasb",
});
console.log(r.passage, r.currency);

SDKs in design-partner beta. openapi.yaml spec ships at the request-a-key step.

MCP server

For Claude Desktop, Cursor, and any MCP-compatible client, PortMem ships as an MCP server exposing the retrieve tool with the same schema as the REST endpoint. Add to your ~/.claude/claude_desktop_config.json:

{
  "mcpServers": {
    "portmem": {
      "command": "npx",
      "args": ["-y", "@portmem/mcp-server"],
      "env": { "PORTMEM_API_KEY": "pmk_live_..." }
    }
  }
}

Deployment options