Complete partner contract · v1

Build against the API that shows its work.

Sixteen documented operations, one partner write, and explicit evidence authority. Every example is generated from the same endpoint catalog; the three flagship calls can be rerun against the live deployment.

Start in two minutes Browse all endpoints

Verified live release69c980a6

API base: openwellbeingprotocol.com/agent
Authentication: HTTP Basic · partner-scoped
Corpus label: live-web@2026-06-28
Verified live: 24 July 2026

The running API still reports promotion_status: local_demo. Live, verified, and generally available are intentionally different claims.

Two-minute quickstart

Discover. Pin. Screen. Inspect.

Treat corpus identity and trust state as inputs to the integration—not incidental metadata.

Set server credentials

Keep the Basic credential in your backend or secret store.

OWP_BASE=https://openwellbeingprotocol.com/agent
OWP_USER=…
OWP_PASSWORD=…

Read and pin meta

Capture corpus_version or corpus_id and every closed enum.

curl "$OWP_BASE/v1/meta" --user "$OWP_USER:$OWP_PASSWORD"

Call one workflow

Pin the corpus, send structured context, and keep the returned proof.

X-Corpus-Version: live-web@2026-06-28
POST /v1/screen

Follow the authority

Read the trust posture and inspect the evidence chain behind a claim.

GET /v1/trust
GET /v1/evidence/dossier/{claim_id}

API reference

16 operations

Demo liveProvenance labeledAuthority gated

Discover & pin

Discover the partner surface, read every closed vocabulary, and bind an integration to a corpus.

GET/v1

Demo live

Self-describing index

The front door to every partner-visible section of the API.

Returns a typed index and a links map, so an integration can discover the live surface instead of hard-coding an undocumented route list.

EnvelopeVersion + corpus + promotion stampExample path/v1HTTP status · cache200 · 400 · 401 · 403 · 409 · 429 · 503 · ETag / corpus revalidation

Request & response contract

Parameters

No operation-specific parameters.

Response fields

kind

string

Response discriminator for exhaustive client handling.

corpus_version / corpus_id

string

Human-readable corpus label and content-addressed identity.

promotion_status

string

The serving corpus promotion state, carried on the response.

title

string

Name of the partner API.

links

Record<string, string>

Discoverable links and URI templates for the partner surface.

cURLCopy into a server-side terminal

curl --request GET \
  "$OWP_BASE/v1" \
  --user "$OWP_USER:$OWP_PASSWORD" \
  --header "Accept: application/json" \
  --header "X-Corpus-Version: $OWP_CORPUS"

GET/v1/meta

Demo live

Enum registry & corpus identity

Every closed vocabulary, mandatory notice, and corpus stamp.

Use this during integration startup. Clients can build exhaustive enum handling, surface the required notices, and pin the corpus label or hash on later requests.

EnvelopeVersion + corpus + promotion stampExample path/v1/metaHTTP status · cache200 · 400 · 401 · 403 · 409 · 429 · 503 · ETag / corpus revalidation

Request & response contract

Parameters

X-Corpus-Versionheader

string

Optional label or corpus id. A mismatch returns 409.

Response fields

kind

string

Response discriminator for exhaustive client handling.

corpus_version / corpus_id

string

Human-readable corpus label and content-addressed identity.

promotion_status

string

The serving corpus promotion state, carried on the response.

mode

"A"

Screening-only mode; no ranking or selection.

mandatory_notices

string[]

Notices a consumer surface must display.

evidence_families

string[]

The five closed evidence-family route values.

enums

Record<string, { values, doc }>

Self-documented closed vocabularies, including API error codes.

cURLCopy into a server-side terminal

curl --request GET \
  "$OWP_BASE/v1/meta" \
  --user "$OWP_USER:$OWP_PASSWORD" \
  --header "Accept: application/json" \
  --header "X-Corpus-Version: $OWP_CORPUS"

GET/v1/openapi.json

Demo live

OpenAPI 3.1 document

The live machine contract for the partner plane.

Served as OpenAPI 3.1 / JSON Schema 2020-12. It declares Basic auth, operation paths, closed enums, the standard envelope, and evidence schemas built from the same allow-list used at runtime.

DocumentStandard OpenAPI documentExample path/v1/openapi.jsonHTTP status · cache200 · 400 · 401 · 403 · 409 · 429 · 503 · ETag / corpus revalidation

Request & response contract

Parameters

No operation-specific parameters.

Response fields

openapi

"3.1.0"

OpenAPI document version.

paths

object

Documented partner operations.

components.schemas

object

Envelope, enums, errors, and endpoint schemas.

security

[{ basicAuth: [] }]

HTTP Basic authentication requirement.

cURLCopy into a server-side terminal

curl --request GET \
  "$OWP_BASE/v1/openapi.json" \
  --user "$OWP_USER:$OWP_PASSWORD" \
  --header "Accept: application/json" \
  --header "X-Corpus-Version: $OWP_CORPUS"

Knowledge graph

Resolve shared concepts, traverse bounded relationships, and open one entity-level knowledge card.

GET/v1/taxonomy

Demo live

Partner vocabulary

Canonical concepts, units, definitions, and surface-name synonyms.

The shared interlingua used across screening and graph operations. Concepts span goals, biomarkers, wearable metrics, medications, candidates, and other reviewed node kinds.

EnvelopeVersion + corpus + promotion stampExample path/v1/taxonomyHTTP status · cache200 · 400 · 401 · 403 · 409 · 429 · 503 · ETag / corpus revalidation

Request & response contract

Parameters

No operation-specific parameters.

Response fields

kind

string

Response discriminator for exhaustive client handling.

corpus_version / corpus_id

string

Human-readable corpus label and content-addressed identity.

promotion_status

string

The serving corpus promotion state, carried on the response.

concept_count

integer

Number of canonical concepts in this corpus.

concepts[]

Concept[]

Canonical id, axis, code, definition, units, category, and synonyms.

cURLCopy into a server-side terminal

curl --request GET \
  "$OWP_BASE/v1/taxonomy" \
  --user "$OWP_USER:$OWP_PASSWORD" \
  --header "Accept: application/json" \
  --header "X-Corpus-Version: $OWP_CORPUS"

GET/v1/taxonomy/graph

Demo live

Whole partner graph

Codes-only nodes and typed edges with provenance counts.

Returns the complete partner-visible substrate. Each edge retains its provenance, and the response counts how much of the graph is repo-grounded, derived, or awaiting stronger authority.

EnvelopeVersion + corpus + promotion stampExample path/v1/taxonomy/graphHTTP status · cache200 · 400 · 401 · 403 · 409 · 429 · 503 · no-store

Request & response contract

Parameters

No operation-specific parameters.

Response fields

kind

string

Response discriminator for exhaustive client handling.

corpus_version / corpus_id

string

Human-readable corpus label and content-addressed identity.

promotion_status

string

The serving corpus promotion state, carried on the response.

nodes[]

{ id, kind, code }[]

Codes-only nodes.

edges[]

{ source, target, label, provenance }[]

Typed, provenance-bearing relationships.

provenance_counts

Record<string, integer>

Count by graph provenance status.

cURLCopy into a server-side terminal

curl --request GET \
  "$OWP_BASE/v1/taxonomy/graph" \
  --user "$OWP_USER:$OWP_PASSWORD" \
  --header "Accept: application/json" \
  --header "X-Corpus-Version: $OWP_CORPUS"

GET/v1/graph/query

Demo live

Rooted graph traversal

A bounded breadth-first traversal from one or more canonical roots.

Every control is bounded or closed: roots, labels, direction, depth, kinds, and node cap. Unresolved roots and truncation are explicit response fields.

EnvelopeVersion + corpus + promotion stampExample path/v1/graph/query?root=goal:sleep&direction=both&depth=1&node_cap=200HTTP status · cache200 · 400 · 401 · 403 · 409 · 429 · 503 · no-store

Request & response contract

Parameters

rootrequiredquery

csv<{kind}:{code}>

One or more canonical roots.

labelsquery

csv<EdgeLabel>

Optional edge-label filter.

directionquery

out | in | both

Traversal direction. Default: both.

depthquery

integer 0–3

Maximum hops. Default: 1.

kindsquery

csv<NodeKind>

Optional returned-node filter.

node_capquery

integer 1–200

Maximum returned nodes. Default: 200.

Response fields

kind

string

Response discriminator for exhaustive client handling.

corpus_version / corpus_id

string

Human-readable corpus label and content-addressed identity.

promotion_status

string

The serving corpus promotion state, carried on the response.

query

object

Normalized request controls.

nodes[] / edges[]

array

Reached nodes with hop distance and the relationships between them.

unresolved_roots

string[]

Validly formed roots that are absent from the corpus.

truncated / truncation

boolean / object

Whether and why the traversal was clipped.

cURLCopy into a server-side terminal

curl --request GET \
  "$OWP_BASE/v1/graph/query?root=goal:sleep&direction=both&depth=1&node_cap=200" \
  --user "$OWP_USER:$OWP_PASSWORD" \
  --header "Accept: application/json" \
  --header "X-Corpus-Version: $OWP_CORPUS"

GET/v1/entities/{id}/dossier

Demo live

Universal entity dossier

A kind-aware knowledge card for any canonical graph node.

Accepts a canonical id, an alias prefix, or a bare code. It returns one resolved entity header, facts, typed edges, inline evidence where available, and explicit gaps.

EnvelopeVersion + corpus + promotion stampExample path/v1/entities/goal:sleep/dossierHTTP status · cache200 · 400 · 401 · 403 · 404 · 409 · 429 · 503 · no-store

Request & response contract

Parameters

idrequiredpath

{kind}:{code} | alias | code

Canonical id, accepted alias, or unambiguous bare code.

Response fields

kind

string

Response discriminator for exhaustive client handling.

corpus_version / corpus_id

string

Human-readable corpus label and content-addressed identity.

promotion_status

string

The serving corpus promotion state, carried on the response.

entity

{ id, kind, code, display_name, resolved_from }

Resolved entity header.

facts

object

Definition, category, units, and synonyms.

edges

Record<EdgeLabel, Edge[]>

Typed relationships grouped by label.

gaps

array

Known holes, surfaced explicitly.

cURLCopy into a server-side terminal

curl --request GET \
  "$OWP_BASE/v1/entities/goal:sleep/dossier" \
  --user "$OWP_USER:$OWP_PASSWORD" \
  --header "Accept: application/json" \
  --header "X-Corpus-Version: $OWP_CORPUS"

GET/v1/goals/{code}/dossier

Demo live

Goal dossier alias

A convenience alias for the universal entity dossier.

Maps a goal code to the canonical goal entity and returns the identical dossier body. It exists for integrations that start from a goal-first workflow.

EnvelopeVersion + corpus + promotion stampExample path/v1/goals/sleep/dossierHTTP status · cache200 · 400 · 401 · 403 · 404 · 409 · 429 · 503 · no-store

Request & response contract

Parameters

coderequiredpath

GoalCode

Canonical or accepted legacy goal code.

Response fields

kind

string

Response discriminator for exhaustive client handling.

corpus_version / corpus_id

string

Human-readable corpus label and content-addressed identity.

promotion_status

string

The serving corpus promotion state, carried on the response.

entity / facts / edges / gaps

EntityDossier

Identical body to /v1/entities/goal:{code}/dossier.

cURLCopy into a server-side terminal

curl --request GET \
  "$OWP_BASE/v1/goals/sleep/dossier" \
  --user "$OWP_USER:$OWP_PASSWORD" \
  --header "Accept: application/json" \
  --header "X-Corpus-Version: $OWP_CORPUS"

Evidence & trust

Inspect evidence rows, the grading method, signed promotion authority, replay state, and deployment trust.

GET/v1/methodology

Demo live

GRADE method as data

Certainty ladder, study ceilings, adjustment rules, gates, and census.

Makes the grading policy inspectable. The methodology and the provenance census of the corpus it would grade travel together.

EnvelopeVersion + corpus + promotion stampExample path/v1/methodologyHTTP status · cache200 · 400 · 401 · 403 · 409 · 429 · 503 · no-store

Request & response contract

Parameters

No operation-specific parameters.

Response fields

kind

string

Response discriminator for exhaustive client handling.

corpus_version / corpus_id

string

Human-readable corpus label and content-addressed identity.

promotion_status

string

The serving corpus promotion state, carried on the response.

verified_only_mode

boolean

Whether only verified-acquisition rows are served.

certainty_order / tier_weights

array

GRADE ladder and maximum certainty by study tier.

downgrade_reasons / upgrade_reasons

array

Closed reason codes and step weights.

gates / census

object

Methodology gates and per-family provenance counts.

cURLCopy into a server-side terminal

curl --request GET \
  "$OWP_BASE/v1/methodology" \
  --user "$OWP_USER:$OWP_PASSWORD" \
  --header "Accept: application/json" \
  --header "X-Corpus-Version: $OWP_CORPUS"

GET/v1/evidence/{family}

Provenance labeled

Browse an evidence family

Paged, allow-listed evidence rows with a provenance label on every row.

Lists one of five closed families. Legacy rows remain visible with their label; verified_acquisition appears only after the governed receipt chain verifies.

EnvelopeVersion + corpus + promotion stampExample path/v1/evidence/synthesized-claim?limit=1&offset=0HTTP status · cache200 · 400 · 401 · 403 · 404 · 409 · 429 · 503 · no-store

Request & response contract

Parameters

familyrequiredpath

enum(5)

synthesized-claim, effect-claim, source, grade-worksheet, or evidence-hole.

limitquery

integer ≤ 1000

Page size. Default: 1000.

offsetquery

integer ≥ 0

Page offset. Default: 0.

Response fields

kind

string

Response discriminator for exhaustive client handling.

corpus_version / corpus_id

string

Human-readable corpus label and content-addressed identity.

promotion_status

string

The serving corpus promotion state, carried on the response.

family

string

Normalized evidence family.

total / count / limit / offset

integer

Collection and page window metadata.

rows[].provenance_status

ProvenanceStatus

Verifier-derived status, present on every served row.

provenance_counts

Record<ProvenanceStatus, integer>

Family-wide count by provenance status.

cURLCopy into a server-side terminal

curl --request GET \
  "$OWP_BASE/v1/evidence/synthesized-claim?limit=1&offset=0" \
  --user "$OWP_USER:$OWP_PASSWORD" \
  --header "Accept: application/json" \
  --header "X-Corpus-Version: $OWP_CORPUS"

GET/v1/evidence/{family}/{row_id}

Provenance labeled

One evidence row

A single allow-listed row and its verifier-derived provenance state.

Fetches one served row by family and id. Internal-only columns never enter the partner projection.

EnvelopeVersion + corpus + promotion stampExample path/v1/evidence/synthesized-claim/synth_psyllium_ldl_2026_06_28HTTP status · cache200 · 400 · 401 · 403 · 404 · 409 · 429 · 503 · no-store

Request & response contract

Parameters

familyrequiredpath

enum(5)

Evidence family; underscore aliases are accepted.

row_idrequiredpath

string

The stable row id.

Response fields

kind

string

Response discriminator for exhaustive client handling.

corpus_version / corpus_id

string

Human-readable corpus label and content-addressed identity.

promotion_status

string

The serving corpus promotion state, carried on the response.

family / id

string

Normalized family and row identity.

row

object

Allow-listed public fields for this family.

row.provenance_status

ProvenanceStatus

Verifier-derived row status.

cURLCopy into a server-side terminal

curl --request GET \
  "$OWP_BASE/v1/evidence/synthesized-claim/synth_psyllium_ldl_2026_06_28" \
  --user "$OWP_USER:$OWP_PASSWORD" \
  --header "Accept: application/json" \
  --header "X-Corpus-Version: $OWP_CORPUS"

GET/v1/evidence/dossier/{claim_id}

Provenance labeled

Full evidence join

One synthesis, its worksheet, effects, and sources in a single chain.

The dossier joins all rows behind a synthesized claim. chain_verified only becomes true when the entire joined chain verifies against signed promotion receipts.

EnvelopeVersion + corpus + promotion stampExample path/v1/evidence/dossier/synth_psyllium_ldl_2026_06_28HTTP status · cache200 · 400 · 401 · 403 · 404 · 409 · 429 · 503 · no-store

Request & response contract

Parameters

claim_idrequiredpath

string

A synthesized-claim id.

Response fields

kind

string

Response discriminator for exhaustive client handling.

corpus_version / corpus_id

string

Human-readable corpus label and content-addressed identity.

promotion_status

string

The serving corpus promotion state, carried on the response.

chain_verified

boolean

Whether every joined row verifies as one governed chain.

synthesized_claim

object

Direction, magnitude, certainty, exposure, and provenance.

grade_worksheets[]

object[]

Stored grading arithmetic and adjustments.

effect_claims[] / source_evidence[]

object[]

Per-study effects and their source records.

cURLCopy into a server-side terminal

curl --request GET \
  "$OWP_BASE/v1/evidence/dossier/synth_psyllium_ldl_2026_06_28" \
  --user "$OWP_USER:$OWP_PASSWORD" \
  --header "Accept: application/json" \
  --header "X-Corpus-Version: $OWP_CORPUS"

GET/v1/evidence/{family}/{row_id}/receipt

Authority gated

Promotion receipt

Signer identity, hashes, signature presence, and re-verification result.

Returns the authority record behind a row. The server re-verifies the receipt against its pinned signer set on every read rather than trusting a stored boolean.

EnvelopeVersion + corpus + promotion stampExample path/v1/evidence/synthesized-claim/synth_psyllium_ldl_2026_06_28/receiptHTTP status · cache200 · 400 · 401 · 403 · 404 · 409 · 429 · 503 · no-store

Request & response contract

Parameters

familyrequiredpath

enum(5)

The row’s evidence family.

row_idrequiredpath

string

The row id covered by the receipt.

Response fields

kind

string

Response discriminator for exhaustive client handling.

corpus_version / corpus_id

string

Human-readable corpus label and content-addressed identity.

promotion_status

string

The serving corpus promotion state, carried on the response.

provenance_status / review_ref

string

Row trust label and human-review reference.

receipt

object | null

Signer, covered hashes and ids, and signature presence.

verification

{ verified, signer_set }

Fresh verification result and signer-set pin.

cURLCopy into a server-side terminal

curl --request GET \
  "$OWP_BASE/v1/evidence/synthesized-claim/synth_psyllium_ldl_2026_06_28/receipt" \
  --user "$OWP_USER:$OWP_PASSWORD" \
  --header "Accept: application/json" \
  --header "X-Corpus-Version: $OWP_CORPUS"

GET/v1/grade/{claim_id}/replay

Authority gated

Replay a grade

Re-run the GRADE arithmetic and compare stored with replayed output.

The result is reproduced, failed, or unavailable. A claim without verified promotion authority returns unavailable rather than a grade the system cannot back.

EnvelopeVersion + corpus + promotion stampExample path/v1/grade/synth_psyllium_ldl_2026_06_28/replayHTTP status · cache200 · 400 · 401 · 403 · 404 · 409 · 429 · 503 · no-store

Request & response contract

Parameters

claim_idrequiredpath

string

A synthesized-claim id.

Response fields

kind

string

Response discriminator for exhaustive client handling.

corpus_version / corpus_id

string

Human-readable corpus label and content-addressed identity.

promotion_status

string

The serving corpus promotion state, carried on the response.

status

reproduced | failed | unavailable

Replay outcome.

reason_code

string | null

Why replay is unavailable or failed.

stored / replayed

object / object | null

Stored grade and fresh server-side recomputation.

precision_reasons

string[]

Imprecision reasons carried through the replay.

cURLCopy into a server-side terminal

curl --request GET \
  "$OWP_BASE/v1/grade/synth_psyllium_ldl_2026_06_28/replay" \
  --user "$OWP_USER:$OWP_PASSWORD" \
  --header "Accept: application/json" \
  --header "X-Corpus-Version: $OWP_CORPUS"

GET/v1/trust

Demo live

Deployment trust posture

The serving corpus, signer set, effective trust identity, and receipt counts.

Use this to attest the trust state of the deployment you are reading. It reports the signer-set pin, verified and effective evidence identities, receipt counts, and provenance counts by family.

EnvelopeVersion + corpus + promotion stampExample path/v1/trustHTTP status · cache200 · 400 · 401 · 403 · 409 · 429 · 503 · no-store

Request & response contract

Parameters

No operation-specific parameters.

Response fields

kind

string

Response discriminator for exhaustive client handling.

corpus_version / corpus_id

string

Human-readable corpus label and content-addressed identity.

promotion_status

string

The serving corpus promotion state, carried on the response.

verified_only_mode

boolean

Whether only verified-acquisition rows are served.

signer_set

{ sha256, pinned }

Allowed-signer digest and pin state.

verified_evidence_id / effective_evidence_trust_id

string

Content identities for verified and effective trust material.

receipts / reverification / provenance_counts

object

Authority artifact and row-state census.

cURLCopy into a server-side terminal

curl --request GET \
  "$OWP_BASE/v1/trust" \
  --user "$OWP_USER:$OWP_PASSWORD" \
  --header "Accept: application/json" \
  --header "X-Corpus-Version: $OWP_CORPUS"

Screening

The only partner-callable write: structured context in, deterministic proof-carrying screen out.

POST/v1/screen

Demo live

Screen a candidate stack

Structured profile, goals, and candidates in; proofs, gaps, and a receipt out.

This is the only partner-callable write and it is stateless. It screens; it does not rank, select, or recommend. results.selected is always an empty array.

EnvelopeVersion + corpus + promotion stampExample path/v1/screenHTTP status · cache200 · 400 · 401 · 403 · 409 · 413 · 415 · 429 · 500 · 503 · no-store

Request & response contract

Parameters

body.subjectrequiredbody

Subject

Strictly allow-listed age, sex, reproductive status, medications, conditions, allergies, labs, and wearables.

body.goalsrequiredbody

[{ code: GoalCode }]

1–16 closed goal codes from the taxonomy.

body.candidatesbody

[{ raw_name: string }]

Optional reviewed candidate restriction. Unmatched names stay visible by index.

X-Corpus-Versionheader

string

Optional corpus pin; a mismatch returns 409.

Response fields

kind

string

Response discriminator for exhaustive client handling.

corpus_version / corpus_id

string

Human-readable corpus label and content-addressed identity.

promotion_status

string

The serving corpus promotion state, carried on the response.

schema_version

2

Closed public screening contract version.

screening_id

"scr_" + sha256

Deterministic over parsed request, corpus, and verified-evidence identity.

results

seven buckets

Candidate outcome buckets; selected is structurally empty.

admissibility_proof

Q1–Q4 → NO | DEFER | ALLOWED

Question-by-question public proof for each candidate.

knowledge_gaps / resolution_report

object

Unknowns and raw-to-canonical resolution remain visible.

proof_receipt

{ trace_digest, trace, verified_evidence_id, replay }

Replayable structural trace and the evidence identity mixed into the screen.

cURLCopy into a server-side terminal

curl --request POST \
  "$OWP_BASE/v1/screen" \
  --user "$OWP_USER:$OWP_PASSWORD" \
  --header "Accept: application/json" \
  --header "X-Corpus-Version: $OWP_CORPUS" \
  --header "Content-Type: application/json" \
  --data '{
  "subject": {
    "age": 44,
    "sex": "female",
    "reproductive_status": "not_pregnant_not_trying",
    "medications": [
      {
        "raw_name": "sertraline",
        "raw_value": "50",
        "raw_unit": "mg"
      }
    ],
    "conditions": {
      "items": [],
      "completeness": "explicit_none"
    },
    "allergies": {
      "items": [],
      "completeness": "explicit_none"
    }
  },
  "goals": [
    {
      "code": "sleep"
    }
  ],
  "candidates": [
    {
      "raw_name": "5-HTP"
    },
    {
      "raw_name": "magnesium glycinate"
    }
  ]
}'

Error contract

Application failure is typed. Gateway failure stays HTTP.

Partner handlers use closed error codes. Corpus drift returns a conflict; ambiguous knowledge stays unresolved; missing trust authority stays unavailable. Authentication, scope, and rate-limit middleware can return plain text, so integrations must branch on both status and Content-Type.

400invalid_request

Unknown fields, invalid closed values, or missing required inputs.

401HTTP authentication

Missing or invalid Basic credentials. The body can be plain text.

403HTTP scope / origin

The credential or cross-origin request is outside the partner boundary.

404unknown_entity

The id is absent; entity lookup may include did_you_mean hints.

409corpus_version_conflict

The requested corpus pin does not match the serving corpus.

413request_too_large

A documented body or list cap was exceeded.

429HTTP rate limit

The partner limit was reached. Read retry headers; the body can be plain text.

503HTTP service unavailable

Partner or gateway configuration can fail before an application envelope exists.

503effective_trust_unavailable

The request cannot bind a valid effective-trust snapshot.