---
title: "KYE Protocol™ Cloud Partner-Plane API | API reference"
description: "KYE Protocol™ Cloud Partner-Plane API: 18 operations from app-partner.yaml, a published KYE Protocol™ OpenAPI contract."
url: https://kyeprotocol.com/developers/api/app-partner/
lang: en
source: "KYE Protocol"
---

> KYE Protocol™ Cloud Partner-Plane API: 18 operations from app-partner.yaml, a published KYE Protocol™ OpenAPI contract.

API reference

# KYE Protocol™ Cloud Partner-Plane API

18 operations · `app-partner.yaml`

**Servers**

`https://app.kyeprotocol.com`

**Version**

1.0.0

**Source**

[app-partner.yaml](https://kyeprotocol.com/developers/api/app-partner.yaml)

Consultant / partner / trainer / auditor plane of the KYE™ Cloud™ dashboard — app.kyeprotocol.com/partner/ (Cloudflare Pages Functions backed by the kye-prod D1 database; consolidated from the retired dash.kyeprotocol.com surface, §07 §1a 2026-07-16).

Deny-by-default auth: /\_middleware.js verifies the Clerk RS256 JWT against the Clerk JWKS, resolves the signed-in user to a row in the consultants table by email (migration 008), and attaches the consultant context to every /api/v1/partner/\* request. Any verification failure returns 401. A signed-in user whose email is not on the consultants roster receives 403 not\_enrolled (with an apply\_url); a suspended consultant receives 403 consultant\_suspended. Responses are scoped to the calling consultant / partner / trainer-org id.

Consultant 5 Pipeline 5 Marketplace 1 Evidence 3 Replay 2 Training 2

## Consultant

GET `/api/v1/partner/me` Signed-in consultant profile + KPIs

Returns the consultant's own roster row plus aggregate KPI counts computed as live scalar D1 queries — open leads (captured / qualified), active tenant links, unexpired certifications, and signed attributions.

**Auth:** Session (Clerk JWT)

### Responses

- `200` Profile + KPI counters
- `401` Missing bearer token, or JWT verification failed (signature / issuer / expiry)
- `403` Signed in but not on the consultants roster (not\_enrolled) or suspended (consultant\_suspended)

GET `/api/v1/partner/settings` Read the consultant's editable profile fields

Returns the full consultants row for the signed-in consultant (identity, contact, sectors / languages JSON, bio, links, status, certification level, timestamps).

**Auth:** Session (Clerk JWT)

### Responses

- `200` Current settings row
- `401` Missing bearer token, or JWT verification failed (signature / issuer / expiry)
- `403` Signed in but not on the consultants roster (not\_enrolled) or suspended (consultant\_suspended)
- `404` Consultant row no longer present (consultant\_not\_found)

PATCH `/api/v1/partner/settings` Update the consultant's editable profile fields

Parameterised D1 update of the consultants row. Only the whitelisted fields are writable from this surface; any other key in the body is ignored. String values are capped at 2000 characters; null clears a field. At least one editable field must be provided.

**Auth:** Session (Clerk JWT)

### Request body (required)

| field | type | description |
| --- | --- | --- |
| `display_name` | string,null |  |
| `phone` | string,null |  |
| `country` | string,null |  |
| `sectors_json` | string,null | JSON-encoded array of sector slugs |
| `languages_json` | string,null | JSON-encoded array of language codes |
| `bio` | string,null |  |
| `website` | string,null |  |
| `linkedin` | string,null |  |

### Responses

- `200` Update applied
- `400` invalid\_json, field\_too\_long, or no\_editable\_fields\_provided
- `401` Missing bearer token, or JWT verification failed (signature / issuer / expiry)
- `403` Signed in but not on the consultants roster (not\_enrolled) or suspended (consultant\_suspended)

GET `/api/v1/partner/consultant-card` Read the consultant's signed Consultant Card™ envelope

Returns the latest signed kye.consultant\_card.v1 envelope row for the signed-in consultant. Envelope signing happens server-side in the consultant-engine runtime; if no card row is provisioned yet the endpoint returns a minimal card view derived from the roster row with provisioned: false and a null envelope.

**Auth:** Session (Clerk JWT)

### Responses

- `200` Card view + signed envelope (envelope is null until provisioned)
- `401` Missing bearer token, or JWT verification failed (signature / issuer / expiry)
- `403` Signed in but not on the consultants roster (not\_enrolled) or suspended (consultant\_suspended)
- `503` D1 binding KYE\_DB is not configured on the Pages project

GET `/api/v1/partner/tenants` Tenants the signed-in consultant operates on

Rows from consultant\_tenant\_links (migration 008) for the calling consultant — invited / accepted / revoked link states plus aggregate counts. Scoped to the caller's consultant id by the partner-plane middleware; no cross-consultant reads.

**Auth:** Session (Clerk JWT)

### Responses

- `200` Link rows + counts for the calling consultant
- `401` Missing bearer token, or JWT verification failed (signature / issuer / expiry)
- `403` Signed in but not on the consultants roster (not\_enrolled) or suspended (consultant\_suspended)

## Pipeline

GET `/api/v1/partner/leads` Leads assigned to the signed-in consultant

Lists consultant\_leads rows assigned to the caller, newest first. The status filter maps onto the underlying lead states (open = captured + qualified).

**Auth:** Session (Clerk JWT)

### Parameters

| name | in | type | description |
| --- | --- | --- | --- |
| `status` | query | string |  |
| `limit` | query | integer |  |

### Responses

- `200` Assigned leads
- `400` bad\_status\_filter — status not in open | qualified | converted | rejected | all
- `401` Missing bearer token, or JWT verification failed (signature / issuer / expiry)
- `403` Signed in but not on the consultants roster (not\_enrolled) or suspended (consultant\_suspended)

GET `/api/v1/partner/partner-leads` Partner lead pipeline (partners.html panel)

The partner-panel projection of the caller's assigned consultant\_leads rows (migration 008), mapped to the pipeline table shape (customer / stage / region / vertical / opened / ACV). expected\_acv\_usd is taken from the partner's own registered deal for the same customer when one exists and is null otherwise — no value is ever invented.

**Auth:** Session (Clerk JWT)

### Parameters

| name | in | type | description |
| --- | --- | --- | --- |
| `limit` | query | integer |  |

### Responses

- `200` Partner lead pipeline, newest first
- `401` Missing bearer token, or JWT verification failed (signature / issuer / expiry)
- `403` Signed in but not on the consultants roster (not\_enrolled) or suspended (consultant\_suspended)
- `503` D1 binding KYE\_DB is not configured on the Pages project

GET `/api/v1/partner/partner-payouts` Partner payout history (partners.html panel)

Quarterly revenue-share ACCRUALS derived from the caller's closed\_won deal\_registrations rows (share % fixed at registration time, constitution §10 §6). Status is always "accrued" — no disbursement ledger exists yet, so nothing is ever reported as paid. A partner with no closed-won deals receives an honest empty list.

**Auth:** Session (Clerk JWT)

### Responses

- `200` Per-quarter accruals, newest first
- `401` Missing bearer token, or JWT verification failed (signature / issuer / expiry)
- `403` Signed in but not on the consultants roster (not\_enrolled) or suspended (consultant\_suspended)
- `503` D1 binding KYE\_DB is not configured on the Pages project

GET `/api/v1/partner/deal-registrations` List deals registered by the calling partner

Returns up to 200 kye.deal\_registration.v1 rows owned by the calling partner, newest first.

**Auth:** Session (Clerk JWT)

### Responses

- `200` Registered deals
- `401` Missing bearer token, or JWT verification failed (signature / issuer / expiry)
- `403` Signed in but not on the consultants roster (not\_enrolled) or suspended (consultant\_suspended)
- `503` D1 binding KYE\_DB is not configured on the Pages project

POST `/api/v1/partner/deal-registrations` Register a new deal

Persists a kye.deal\_registration.v1 row tracked against the partner's signing kid with a default 30% revenue share. customer is required; stage must be one of the canonical pipeline stages.

**Auth:** Session (Clerk JWT)

### Request body (required)

| field | type | description |
| --- | --- | --- |
| `customer` **required** | string |  |
| `stage` **required** | string | One of qualifying, scoping, contracting, closed\_won, closed\_lost |
| `expected_close` | string | Expected close date (free-form ISO date string) |
| `expected_acv` | number | Expected annual contract value |
| `notes` | string |  |

### Responses

- `200` Deal registered
- `400` customer\_required or invalid\_stage
- `401` Missing bearer token, or JWT verification failed (signature / issuer / expiry)
- `403` Signed in but not on the consultants roster (not\_enrolled) or suspended (consultant\_suspended)
- `503` D1 binding KYE\_DB is not configured on the Pages project

## Marketplace

GET `/api/v1/partner/marketplace-listings` Marketplace listings owned by the caller

Lists the kye.{rule\_pack,sector\_pack,widget}\_listing.v1 rows the calling partner / consultant owns — pricing, sectors, revenue-share split, publication status. Optionally filtered by listing kind.

**Auth:** Session (Clerk JWT)

### Parameters

| name | in | type | description |
| --- | --- | --- | --- |
| `kind` | query | string |  |

### Responses

- `200` Owned listings (up to 200)
- `400` invalid\_kind — kind not in rule\_pack | sector\_pack | widget
- `401` Missing bearer token, or JWT verification failed (signature / issuer / expiry)
- `403` Signed in but not on the consultants roster (not\_enrolled) or suspended (consultant\_suspended)
- `503` D1 binding KYE\_DB is not configured on the Pages project

## Evidence

GET `/api/v1/partner/attributions` Signed attributions on evidence packs

Lists consultant\_attributions rows for the signed-in consultant — each a signed attribution placed on a customer evidence pack (tenant\_id, evidence\_pack\_id, attested\_by / attested\_at, signature alg + kid), newest first.

**Auth:** Session (Clerk JWT)

### Parameters

| name | in | type | description |
| --- | --- | --- | --- |
| `limit` | query | integer |  |

### Responses

- `200` Signed attributions
- `401` Missing bearer token, or JWT verification failed (signature / issuer / expiry)
- `403` Signed in but not on the consultants roster (not\_enrolled) or suspended (consultant\_suspended)

GET `/api/v1/partner/certifications` Certifications held by the signed-in consultant

Lists consultant\_certifications rows with a derived `active` flag computed from the not\_before / not\_after validity window at request time, plus total / active counts.

**Auth:** Session (Clerk JWT)

### Responses

- `200` Certification history
- `401` Missing bearer token, or JWT verification failed (signature / issuer / expiry)
- `403` Signed in but not on the consultants roster (not\_enrolled) or suspended (consultant\_suspended)

GET `/api/v1/partner/reports` Signed reports the partner-plane user has access to

KYE™ Reporting Engine™ partner-plane view. Returns signed kye.report.v1 envelope rows on tenants the consultant is attributed to (access derives from consultant\_attributions — a consultant who attested an evidence pack can read reports on that tenant). Optionally filtered by regulatory framework. Report synthesis itself is patent-track and not disclosed here.

**Auth:** Session (Clerk JWT)

### Parameters

| name | in | type | description |
| --- | --- | --- | --- |
| `framework` | query | string | Exact-match filter on the report's regulatory framework |

### Responses

- `200` Accessible report envelopes (up to 200, newest sealed first)
- `401` Missing bearer token, or JWT verification failed (signature / issuer / expiry)
- `403` Signed in but not on the consultants roster (not\_enrolled) or suspended (consultant\_suspended)
- `503` D1 binding KYE\_DB is not configured on the Pages project

## Replay

GET `/api/v1/partner/replay-runs` Recent Replay-Proof™ verifications by this user

Lists the last 100 replay-verify calls the caller has made via the partner console (decision id, verdict, signer kid, reason, timestamp).

**Auth:** Session (Clerk JWT)

### Responses

- `200` Verification history
- `401` Missing bearer token, or JWT verification failed (signature / issuer / expiry)
- `403` Signed in but not on the consultants roster (not\_enrolled) or suspended (consultant\_suspended)
- `503` D1 binding KYE\_DB is not configured on the Pages project

POST `/api/v1/partner/replay-verify` Verify a KYE-anchored artefact

Two clearly-separated verdict layers. (1) DISCLOSED — real Ed25519 signature verification of a { payload, signature: { alg: EdDSA, kid, sig } } envelope against the published self-audit JWKS (kyeprotocol.com/trust/self-audit-jwks.json); the §0.4 "Replay-Proof™ derivable from public keys alone" contract. (2) DEFERRED — offline replay reconstruction is patent-track; when the KYE\_REPLAY\_ENGINE service binding is present the call is proxied, otherwise that layer alone reports replay: deferred. Every call is recorded as a replay\_runs row for the caller.

**Auth:** Session (Clerk JWT)

### Request body (required)

| field | type | description |
| --- | --- | --- |
| `input` | string | A signed envelope as a JSON string (verified against the JWKS), or a kye:decision:... id (routed to the replay layer). |
| `live` | string | "latest" or a YYYY-MM-DD date — fetches and verifies the published LIVE self-audit bundle for that day. |

### Responses

- `200` Verification result (both layers reported separately)
- `400` empty\_input, invalid\_envelope\_json, unrecognised\_input, or live not "latest" / YYYY-MM-DD
- `401` Missing bearer token, or JWT verification failed (signature / issuer / expiry)
- `403` Signed in but not on the consultants roster (not\_enrolled) or suspended (consultant\_suspended)
- `502` The published LIVE self-audit bundle could not be fetched or was not JSON
- `503` D1 binding KYE\_DB is not configured on the Pages project

## Training

GET `/api/v1/partner/training-cohorts` Cohorts owned by the calling trainer-org

Lists up to 200 training cohorts owned by the caller with enrolled / passed counters. Signed completion records are surfaced separately via /api/v1/training-completions.

**Auth:** Session (Clerk JWT)

### Responses

- `200` Trainer-owned cohorts
- `401` Missing bearer token, or JWT verification failed (signature / issuer / expiry)
- `403` Signed in but not on the consultants roster (not\_enrolled) or suspended (consultant\_suspended)
- `503` D1 binding KYE\_DB is not configured on the Pages project

GET `/api/v1/partner/training-completions` Signed training completion records

Lists up to 200 kye.training.completion.v1 envelope rows the trainer-org has sealed — partner\_user\_id, cohort\_id, verdict (pass / fail / pending), score, sealed\_at + signed\_by\_kid.

**Auth:** Session (Clerk JWT)

### Responses

- `200` Sealed completion records
- `401` Missing bearer token, or JWT verification failed (signature / issuer / expiry)
- `403` Signed in but not on the consultants roster (not\_enrolled) or suspended (consultant\_suspended)
- `503` D1 binding KYE\_DB is not configured on the Pages project