Specification
v0.1.0
A response envelope for structured, verifiable data exchange between data providers and AI agents. Every response carries its domain, source, freshness, confidence score, citations, and cryptographic proof.
Section 1
Every OPP response wraps data in a standard envelope. Agents parse it once and trust the structure across all providers.
cars, drugs, water.Section 2
| Component | Location | Purpose |
|---|---|---|
| Manifest | /.well-known/opp.json |
Provider declares domains, freshness schedule, and public key. Agents discover capabilities before making requests. |
| Envelope | Every response | Wraps data with domain, source, freshness, confidence, citations, and proof fields. |
| Verification | Ed25519 signature | Agents verify data integrity and provider identity. Public key published in manifest. |
Section 3
api.openprimitive.com serves 16 US federal data domains across 11 agencies.
| Domain | Endpoint | Source | Freshness | Completeness |
|---|---|---|---|---|
| Flights | /v1/flights |
BTS / FAA | Daily | Partial |
| Vehicle Recalls | /v1/cars |
NHTSA | Daily | Full |
| Food Recalls | /v1/food-recalls |
FDA | Weekly | Full |
| Water Safety | /v1/water |
EPA SDWIS | Quarterly | Partial |
| Health Claims | /v1/health |
NLM / PubMed | On-demand | Full |
| Hospital Quality | /v1/hospitals |
CMS | Quarterly | Full |
| Drug Effects | /v1/drugs |
FDA FAERS | Quarterly | Full |
| Nursing Homes | /v1/nursing-homes |
CMS | Monthly | Full |
| Clinical Trials | /v1/trials |
ClinicalTrials.gov | On-demand | Full |
| Air Quality | /v1/air |
EPA AQS | Hourly | Partial |
| Consumer Complaints | /v1/complaints |
CFPB | Daily | Full |
| Bank Failures | /v1/banks |
FDIC | Weekly | Full |
| Product Recalls | /v1/products |
CPSC | Daily | Full |
| Workplace Safety | /v1/workplace |
OSHA | Quarterly | Partial |
| Drug Labels | /v1/drug-labels |
FDA DailyMed | Daily | Full |
| Food Inspections | /v1/food-inspections |
USDA FSIS | Monthly | Partial |
Section 4
Agents calibrate trust using this table. Completeness reflects what the API returns relative to what the source agency publishes.
| Domain | Methodology | Completeness | Known Gaps |
|---|---|---|---|
| Flights | BTS T-100 bundled + FAA NAS XML + Open-Meteo weather | Partial | BTS data covers Jan-Oct 2024 only. FAA XML parsed via regex; silent failure returns default. |
| Vehicle Recalls | NHTSA Recalls API, real-time | High | None known. |
| Food Recalls | FDA openFDA enforcement endpoint | High | Voluntary recalls may lag 24-48h from announcement. |
| Water Safety | EPA SDWIS federal reporting system | Partial | State-only violations excluded. Primacy agency data may differ. |
| Health Claims | PubMed search + abstract analysis | High | Evidence scoring is heuristic. Abstract-only, no full-text. |
| Hospital Quality | CMS Hospital Compare datasets | High | Ratings lag 3-6 months. VA/DoD hospitals excluded. |
| Drug Effects | FDA FAERS quarterly data files | High | FAERS contains duplicates and unverified reports. Reporting bias toward serious events. |
| Nursing Homes | CMS Nursing Home Compare | High | Star ratings updated monthly. Inspection data can lag 2-4 weeks. |
| Clinical Trials | ClinicalTrials.gov API v2 | High | Registration required but compliance varies. Results posting often delayed. |
| Air Quality | EPA AQS + AirNow current conditions | Partial | EPA-monitored sites only. Rural and tribal areas underrepresented. |
| Consumer Complaints | CFPB complaint database API | High | Company responses are self-reported. Narrative text redacted in many records. |
| Bank Failures | FDIC BankFind API | High | Historical records complete since 2000. |
| Product Recalls | CPSC Recalls API | High | Voluntary recalls may appear before formal CPSC action. |
| Workplace Safety | OSHA inspection data API | Partial | State-plan states report with varying lag. Inspections with violations only. |
| Drug Labels | FDA DailyMed SPL files | High | OTC labels less consistently structured than Rx. |
| Food Inspections | USDA FSIS inspection data | Partial | FSIS-regulated facilities only. FDA-jurisdiction facilities excluded. |
Section 5
| Method | Endpoint | Description |
|---|---|---|
| MCP | npx open-primitive-mcp |
13 tools. Compatible with Claude, Cursor, and MCP-compatible clients. |
| REST | api.openprimitive.com/v1/{domain} |
Structured query with envelope response. All 16 domains. |
| Natural language | /v1/ask?q= |
Routes natural language questions to the correct domain. |
| Discovery | /.well-known/opp.json |
Protocol manifest. Declares domains, freshness, verification key. |
| LLM docs | /llms.txt |
LLM-readable documentation. /llms-full.txt includes full API spec. |
| OpenAPI | /openapi.json |
Machine-readable API specification. |
| A2A | /.well-known/agent.json |
Google A2A agent card. 13 skills for agent-to-agent discovery. |
Resources