YMH Knowledge API v1

Read-only access to the curated marine engineering knowledge corpus that powers the YMH Engineer. Data Contract v0 compliant, Signal K paths, vesseliq.* extensions, six standard scopes.

Base URL

https://www.yachtmastershub.com/api/v1

Authentication

Every request requires a Bearer API key issued by YMH admin.

Authorization: Bearer ymhk_<your-key>

Keys carry a subset of the six Data Contract v0 scopes:

Scope	Grants
`read:documents`	Read reference manuals, standards, procedures
`read:maintenance`	Read service intervals, torque specs, part numbers
`read:telemetry`	Reserved for live vessel data (not yet exposed via this API)
`write:maintenance`	Reserved
`write:documents`	Reserved
`admin`	All scopes

To read the knowledge corpus, a key needs at least read:documents or read:maintenance.

Errors

All errors follow the Data Contract v0 envelope:

{ "ok": false, "error": "code_string", "retryable": true|false, "detail": "human-readable" }

Code	Meaning
`missing_token`	No Authorization header
`invalid_token`	Key not recognized
`revoked_token`	Key has been revoked
`insufficient_scope`	Key doesn't carry a scope this endpoint requires
`query_failed`	Server error executing the query (retryable)
`embedding_unavailable`	Semantic search unavailable (retryable)

GET `/knowledge`

Search or list knowledge entries. All parameters are optional.

Param	Type	Notes
`q`	string	Semantic search (embedded, top-k by cosine)
`path`	string	Signal K path filter. Exact match, or use `` as a suffix wildcard: `propulsion.engine1.`
`system`	string	Canonical category: `propulsion`, `generators`, `electrical`, `hvac`, `navigation_electronics`, `safety`, `stabilization`, `plumbing_watermaker`, `entertainment`, `tender_toys`
`make`	string	Manufacturer, case-insensitive substring
`model`	string	Model, case-insensitive substring
`limit`	int	1..50, default 10

Example

curl -H "Authorization: Bearer ymhk_..." \
  "https://www.yachtmastershub.com/api/v1/knowledge?q=Volvo+D6+oil+service&limit=3"

Response

{
  "ok": true,
  "count": 1,
  "results": [
    {
      "id": "volvo-d6-service-intervals",
      "contract_id": "9c2b5e...",
      "title": "Volvo Penta D6 service intervals",
      "system": "engine",
      "canonicalSystem": "propulsion",
      "signalKPaths": ["propulsion.engine1", "propulsion.engine1.oil.pressure", "..."],
      "vesseliqPaths": ["vesseliq.maintenance.event.oil_change", "..."],
      "scopes": ["read:documents", "read:maintenance"],
      "make": "Volvo Penta",
      "model": "D6",
      "content": "The Volvo Penta D6 ...",
      "source": "Volvo Penta Operator's Manual (public)",
      "provenance": "seed",
      "updatedAt": "2026-07-24T..."
    }
  ]
}

GET `/whoami`

Verify your key and see its scopes.

{ "ok": true, "name": "vesseliq-prod", "scopes": ["read:documents","read:maintenance"] }

Rate limits

Default: 60 requests per minute per API key, sliding window. Response headers on every successful call:

x-ratelimit-limit:     60
x-ratelimit-remaining: 42
x-ratelimit-window:    60

When you exceed the window, the API responds with 429, a retry-after header, and:

{ "ok": false, "error": "rate_limited", "retryable": true, "detail": "Rate limit exceeded: 60/60 requests in the last 60s. Retry after 60s." }

Well-behaved clients should back off on x-ratelimit-remaining: 0 rather than hammer the 429. Contact YMH if you have a legitimate reason to exceed 60/min.

Data model reference

The corpus follows the Signal K path taxonomy for standard vessel data, extended with vesseliq.* namespaces for maintenance events, documents, authorization, and charter operations. See the YMH Data Contract v0 for the full extension list.