API reference

KYE Protocol™ — Consultant Program™ API

37 operations · consultant-programme.openapi.yaml

Servers: https://admin.kyeprotocol.com https://app.kyeprotocol.com https://kyeprotocol.com
Version: 1.0.0
Source: consultant-programme.openapi.yaml

Admin authoring (owner-gated), tenant-scoped read endpoints, and the public lead-capture endpoint for the KYE™ Consultant Program™.

All POST endpoints accept an Idempotency-Key header; if present, the response is cached per (tenant_id, scope, key) and returned verbatim on retry. Soft-delete only — deleted_at is set; rows are never physically removed.

Patent-safety: this spec MUST stay free of mechanism vocabulary.

Base path: /api/v1/ (admin + cloud) and /api/ (public site).

consultant-programme

GET/api/v1/consultantsList consultants (admin)

Auth: bearerAuth

Parameters

name	in	type
`status`	query	string
`level`	query	string
`country`	query	string
`q`	query	string

Responses

200 OK

POST/api/v1/consultantsCreate a consultant (admin)

Auth: bearerAuth

Parameters

name	in	type	description
`Idempotency-Key`	header	string

Request body (required)

field	type	description
`display_name` required	string
`legal_name`	string
`email` required	string
`phone`	string
`country`	string
`sectors`	array
`languages`	array
`bio`	string
`website`	string
`linkedin`	string
`status`	string	One of applied, onboarding, certified, suspended, retired
`certification_level`	string	One of associate, professional, master
`attribution_kid`	string

Responses

201 Created
400 Validation error
409 Duplicate email

GET/api/v1/consultants/{id}Fetch a consultant (admin)

Auth: bearerAuth

Parameters

name	in	type	description
`id` required	path	string

Responses

200 OK
404 Not found

PATCH/api/v1/consultants/{id}Update a consultant (admin)

Auth: bearerAuth

Parameters

name	in	type	description
`id` required	path	string

Request body (required)

field	type	description
`display_name`	string
`legal_name`	string
`phone`	string
`country`	string
`sectors`	array
`languages`	array
`bio`	string
`website`	string
`linkedin`	string
`status`	string
`certification_level`	string
`attribution_kid`	string

Responses

200 OK

DELETE/api/v1/consultants/{id}Soft-delete a consultant (admin)

Auth: bearerAuth

Parameters

name	in	type	description
`id` required	path	string

Responses

200 OK

POST/api/v1/consultants/{id}/certifyCertify a consultant (admin)

Auth: bearerAuth

Parameters

name	in	type	description
`id` required	path	string
`Idempotency-Key`	header	string

Request body (required)

field	type	description
`level` required	string	One of associate, professional, master
`program`	string
`not_before`	string
`not_after`	string
`evidence_pack_id`	string
`signature_kid`	string
`signature_value_b64`	string

Responses

201 Created

POST/api/v1/consultants/{id}/suspendSuspend a consultant (admin)

Auth: bearerAuth

Parameters

name	in	type	description
`id` required	path	string
`Idempotency-Key`	header	string

Request body (required)

field	type	description
`reason` required	string

Responses

200 OK

GET/api/v1/consultant-certificationsList certifications (admin)

Auth: bearerAuth

Parameters

name	in	type
`consultant_id`	query	string
`level`	query	string
`program`	query	string

Responses

200 OK

POST/api/v1/consultant-certificationsCreate a certification (admin)

Auth: bearerAuth

Parameters

name	in	type	description
`Idempotency-Key`	header	string

Request body (required)

field	type	description
`consultant_id` required	string
`level` required	string	One of associate, professional, master
`program`	string
`not_before`	string
`not_after`	string
`evidence_pack_id`	string
`signature_kid`	string
`signature_value_b64`	string

Responses

201 Created

GET/api/v1/consultant-certifications/{id}

Auth: bearerAuth

Parameters

name	in	type	description
`id` required	path	string

Responses

200 OK
404 Not found

PATCH/api/v1/consultant-certifications/{id}Revoke or update certification validity (admin)

Auth: bearerAuth

Parameters

name	in	type	description
`id` required	path	string

Request body (required)

field	type	description
`revoke`	boolean
`revoke_reason`	string
`not_after`	string

Responses

200 OK

DELETE/api/v1/consultant-certifications/{id}

Auth: bearerAuth

Parameters

name	in	type	description
`id` required	path	string

Responses

200 OK

GET/api/v1/consultant-tenant-linksList consultant↔tenant links (admin)

Auth: bearerAuth

Parameters

name	in	type
`tenant_id`	query	string
`consultant_id`	query	string
`status`	query	string

Responses

200 OK

POST/api/v1/consultant-tenant-linksInvite a consultant to a tenant (admin)

Auth: bearerAuth

Parameters

name	in	type	description
`Idempotency-Key`	header	string

Request body (required)

field	type	description
`consultant_id` required	string
`tenant_id` required	string
`scope`	string	One of view_only, operate, attest
`status`	string	One of invited, active

Responses

201 Created
409 Duplicate consultant_id + tenant_id pair

GET/api/v1/consultant-tenant-links/{id}

Auth: bearerAuth

Parameters

name	in	type	description
`id` required	path	string

Responses

200 OK
404 Not found

PATCH/api/v1/consultant-tenant-links/{id}Accept invite or change scope (admin)

Auth: bearerAuth

Parameters

name	in	type	description
`id` required	path	string

Request body (required)

field	type	description
`accept`	boolean
`scope`	string	One of view_only, operate, attest

Responses

200 OK

DELETE/api/v1/consultant-tenant-links/{id}

Auth: bearerAuth

Parameters

name	in	type	description
`id` required	path	string

Responses

200 OK

POST/api/v1/consultant-tenant-links/{id}/revokeRevoke a consultant↔tenant link (admin)

Auth: bearerAuth

Parameters

name	in	type	description
`id` required	path	string
`Idempotency-Key`	header	string

Request body (required)

field	type	description
`reason` required	string

Responses

200 OK

GET/api/v1/white-label-configsList white-label brand configs (admin)

Auth: bearerAuth

Parameters

name	in	type
`consultant_id`	query	string
`tenant_id`	query	string
`status`	query	string

Responses

200 OK

POST/api/v1/white-label-configsCreate a white-label brand config (admin)

Auth: bearerAuth

Parameters

name	in	type	description
`Idempotency-Key`	header	string

Request body (required)

field	type	description
`consultant_id` required	string
`tenant_id`	string
`brand_name` required	string
`primary_colour_hex`	string
`secondary_colour_hex`	string
`logo_url`	string
`domain`	string
`support_email`	string
`legal_footer`	string
`status`	string	One of draft, active, archived

Responses

201 Created

GET/api/v1/white-label-configs/{id}

Auth: bearerAuth

Parameters

name	in	type	description
`id` required	path	string

Responses

200 OK
404 Not found

PATCH/api/v1/white-label-configs/{id}

Auth: bearerAuth

Parameters

name	in	type	description
`id` required	path	string

Request body (required)

field	type	description
`brand_name`	string
`primary_colour_hex`	string
`secondary_colour_hex`	string
`logo_url`	string
`domain`	string
`support_email`	string
`legal_footer`	string
`status`	string

Responses

200 OK

DELETE/api/v1/white-label-configs/{id}

Auth: bearerAuth

Parameters

name	in	type	description
`id` required	path	string

Responses

200 OK

GET/api/v1/consultant-leadsList consultant leads (admin)

Auth: bearerAuth

Parameters

name	in	type
`status`	query	string
`sector`	query	string
`assigned_consultant_id`	query	string
`q`	query	string

Responses

200 OK

POST/api/v1/consultant-leadsCreate a consultant lead (admin / import)

Auth: bearerAuth

Parameters

name	in	type	description
`Idempotency-Key`	header	string

Request body (required)

field	type	description
`submitter_email` required	string
`submitter_name`	string
`organisation`	string
`sector`	string
`country`	string
`message`	string
`consent_marketing`	boolean
`source`	string
`utm`	object

Responses

201 Created

GET/api/v1/consultant-leads/{id}

Auth: bearerAuth

Parameters

name	in	type	description
`id` required	path	string

Responses

200 OK
404 Not found

PATCH/api/v1/consultant-leads/{id}

Auth: bearerAuth

Parameters

name	in	type	description
`id` required	path	string

Request body (required)

field	type	description
`assigned_consultant_id`	string
`sector`	string
`message`	string
`status`	string	One of captured, qualified, converted, rejected

Responses

200 OK

DELETE/api/v1/consultant-leads/{id}

Auth: bearerAuth

Parameters

name	in	type	description
`id` required	path	string

Responses

200 OK

POST/api/v1/consultant-leads/{id}/qualifyMark a lead qualified (admin)

Auth: bearerAuth

Parameters

name	in	type	description
`id` required	path	string
`Idempotency-Key`	header	string

Responses

200 OK

POST/api/v1/consultant-leads/{id}/convertMark a lead converted (admin)

Auth: bearerAuth

Parameters

name	in	type	description
`id` required	path	string
`Idempotency-Key`	header	string

Request body (required)

field	type	description
`converted_tenant_id` required	string

Responses

200 OK

GET/api/v1/app/consultantsList consultants attested into the caller's tenant (cloud)

Auth: bearerAuth

Parameters

name	in	type
`level`	query	string
`sector`	query	string
`limit`	query	integer

Responses

200 OK

GET/api/v1/app/consultants/{id}Fetch a consultant scoped to the caller's tenant (cloud)

Auth: bearerAuth

Parameters

name	in	type	description
`id` required	path	string

Responses

200 OK
404 Not found / not linked to tenant

GET/api/v1/app/consultant-tenant-linksList the caller's tenant links (cloud)

Auth: bearerAuth

Parameters

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

Responses

200 OK

GET/api/v1/app/consultant-tenant-links/{id}

Auth: bearerAuth

Parameters

name	in	type	description
`id` required	path	string

Responses

200 OK
404 Not found

GET/api/v1/app/white-label-configFetch the active white-label brand config for the caller's tenant (cloud)

Auth: bearerAuth

Responses

200 OK
404 Not found

GET/api/consultant-leadAggregate lead-counter (no PII; public)

Responses

200 OK

POST/api/consultant-leadCapture a consultant program enquiry (public)

Request body (required)

field	type	description
`email` required	string
`name`	string
`organisation`	string
`sector`	string
`country`	string
`message`	string
`consent_marketing`	boolean
`source`	string

Responses

200 Captured
400 Validation error
429 Rate limited