Open Primitive Protocol · v1

Integrate with the Open Primitive Protocol

Every response is signed, sourced, and scored. Your agent gets data it can trust and cite.

01 — The Envelope

Every OPP response wraps federal data in a standard envelope. The data field carries the query result. The confidence field tells your agent how much to trust it. The proof field lets you verify the response was not tampered with.

OPP Response Envelope

{
  "domain": "drugs",
  "source": "FDA FAERS",
  "source_url": "https://api.fda.gov",
  "freshness": "2026-03-19T14:00:00Z",
  "data": {
    "drug": "metformin",
    "totalEvents": 428748,
    "seriousEvents": 287312,
    "deaths": 14891,
    "topReactions": [
      { "reaction": "DRUG INEFFECTIVE", "count": 22847 },
      { "reaction": "NAUSEA", "count": 18294 },
      { "reaction": "DIARRHOEA", "count": 16103 }
    ]
  },
  "confidence": {
    "completeness": 0.10,
    "methodology": "voluntary-reporting",
    "note": "FDA FAERS captures 1-10% of adverse events"
  },
  "citations": {
    "statement": "According to FDA FAERS, metformin has 428,748 reported adverse events",
    "source_url": "https://api.fda.gov"
  },
  "proof": {
    "type": "DataIntegrityProof",
    "cryptosuite": "eddsa-jcs-2022",
    "created": "2026-03-19T14:00:00Z",
    "verificationMethod": "https://openprimitive.com/.well-known/opp.json#key-1",
    "proofValue": "z3FXQqFcCCAMdMgp8GrXKbTnVEr4A8WjYvN..."
  }
}

Field	Purpose
domain	Which data domain this response covers
source	The federal agency or database that produced the underlying data
source_url	Direct link to the upstream API or dataset
freshness	ISO 8601 timestamp of when this data was fetched from the source
data	The query result. Structure varies by domain.
confidence	How complete and reliable this data is, with methodology context
citations	A pre-built citation your agent can drop into output verbatim
proof	Cryptographic signature proving this response originated from Open Primitive

02 — Quick Start

The API lives at api.openprimitive.com. Free. No API key. No limits. Public data for public good.

curl

curl https://api.openprimitive.com/v1/drugs?name=metformin

# Water safety by ZIP
curl https://api.openprimitive.com/v1/water?zip=10001

# Hospital quality by name
curl https://api.openprimitive.com/v1/hospitals?name=mayo+clinic

# Car safety by make/model/year
curl https://api.openprimitive.com/v1/cars?make=toyota&model=camry&year=2024

JavaScript

const res = await fetch('https://api.openprimitive.com/v1/drugs?name=metformin');
const envelope = await res.json();

// Use the pre-built citation
console.log(envelope.citations.statement);
// → "According to FDA FAERS, metformin has 428,748 reported adverse events"

// Check data freshness
console.log(envelope.freshness);
// → "2026-03-19T14:00:00Z"

// Inspect confidence before trusting
console.log(envelope.confidence.completeness);
// → 0.10 (FAERS captures ~10% of events)

Python

import requests

envelope = requests.get(
    'https://api.openprimitive.com/v1/water',
    params={'zip': '10001'}
).json()

# The data, the citation, and the confidence score
print(envelope['data']['violations'])
print(envelope['citations']['statement'])
print(envelope['confidence']['completeness'])

03 — MCP Server

Add Open Primitive to Claude, Cursor, or any MCP-compatible client. One line in your config.

claude_desktop_config.json

{
  "mcpServers": {
    "open-primitive": {
      "command": "npx",
      "args": ["-y", "open-primitive-mcp"]
    }
  }
}

Once connected, your agent has 13 tools:

lookup_drug -- adverse events by drug name

lookup_drug_interactions -- interaction risks

check_water_safety -- violations by ZIP

check_food_recalls -- active FDA recalls

lookup_hospital -- quality scores by name

compare_hospitals -- side-by-side comparison

lookup_car_safety -- crash ratings, recalls

check_car_recalls -- open recalls by VIN

search_health_claims -- PubMed study volume

check_flight_risk -- delay probability

ask_question -- natural language query

get_safety_report -- multi-domain by ZIP

compare_items -- cross-domain comparison

Each tool returns the full OPP envelope. Your agent gets the data, the confidence score, and a ready-to-use citation in one call.

04 — Natural Language

Your agent does not need to know which domain to query. Ask a plain question. The router figures out the domain and returns the same signed envelope.

Request

curl "https://api.openprimitive.com/v1/ask?q=is+the+water+safe+in+10001"

Response

{
  "domain": "water",
  "source": "EPA SDWIS",
  "source_url": "https://sdwis.epa.gov",
  "freshness": "2026-03-19T14:00:00Z",
  "data": {
    "zip": "10001",
    "system": "NEW YORK CITY DEP",
    "populationServed": 8336817,
    "violations": {
      "healthBased": 0,
      "monitoring": 2,
      "total": 2
    }
  },
  "confidence": {
    "completeness": 0.85,
    "methodology": "regulatory-reporting",
    "note": "EPA SDWIS covers all public water systems; private wells excluded"
  },
  "citations": {
    "statement": "According to EPA SDWIS, the water system serving ZIP 10001 (NEW YORK CITY DEP) has 0 health-based violations and 2 monitoring violations",
    "source_url": "https://sdwis.epa.gov"
  },
  "proof": {
    "type": "DataIntegrityProof",
    "cryptosuite": "eddsa-jcs-2022",
    "created": "2026-03-19T14:00:00Z",
    "verificationMethod": "https://openprimitive.com/.well-known/opp.json#key-1",
    "proofValue": "z8kJd2xVnPqR7mLwA5tYcN3bF..."
  }
}

05 — Cross-Domain Intelligence

Combine domains in a single call. Get a safety profile for a location, or compare two items across any domain.

Safety report by ZIP -- water + hospitals + food recalls

curl "https://api.openprimitive.com/v1/safety?zip=10001"

Location profile

curl "https://api.openprimitive.com/v1/location?zip=90210"

# Returns: water quality, nearest hospitals, active food recalls,
# all in one envelope with per-domain confidence scores

Drug comparison

curl "https://api.openprimitive.com/v1/compare?type=drugs&a=ibuprofen&b=acetaminophen"

# Side-by-side: total events, serious events, deaths,
# top reactions, confidence scores for both

Hospital comparison

curl "https://api.openprimitive.com/v1/compare?type=hospitals&a=mayo+clinic&b=cleveland+clinic"

06 — Implement the Protocol

Any data provider can adopt OPP. Three steps: publish a manifest, wrap your responses in the envelope, sign them.

1. Publish a manifest at /.well-known/opp.json

/.well-known/opp.json

{
  "opp_version": "1.0",
  "provider": "your-org-name",
  "domains": ["environment", "housing"],
  "endpoints": {
    "base_url": "https://api.your-domain.com/v1",
    "ask": "/ask",
    "domains": {
      "environment": "/environment",
      "housing": "/housing"
    }
  },
  "verification": {
    "method": "Ed25519",
    "publicKeys": [
      {
        "id": "#key-1",
        "type": "Ed25519VerificationKey2020",
        "publicKeyMultibase": "z6Mkf5rGMoatrSj1f..."
      }
    ]
  },
  "confidence_model": {
    "scale": "0-1",
    "methodology_types": [
      "regulatory-reporting",
      "voluntary-reporting",
      "census",
      "sample-survey"
    ]
  }
}

2. Return the OPP envelope on every response. Include domain, source, source_url, freshness, data, confidence, citations, and proof.

3. Sign your responses. Use Ed25519 (EdDSA) over JCS-canonicalized JSON. Consumers verify against the public key in your manifest.

Manifest Field	Required	Purpose
opp_version	Yes	Protocol version for compatibility
provider	Yes	Your organization identifier
domains	Yes	Array of data domains you serve
endpoints	Yes	Base URL and per-domain paths
verification	Yes	Public keys for proof verification
confidence_model	Yes	Scale and methodology types you use

OPP is open. No registration required. Publish the manifest, sign the responses, and agents that speak the protocol will find you. The full specification is at openprimitive.com/protocol.