API Overview

SkillHub is built on one typed contract. That contract is served two ways: as a native RPC endpoint for first-party clients, and as a REST + OpenAPI façade for everyone else. The CLI and the web dashboard both talk to it — so the REST API documented here is not a second-class surface bolted on afterwards, it is the very same implementation exposed over HTTP.

The shape of it

• One contract, two transports. Every REST endpoint mirrors exactly one contract procedure. There is no separate REST codebase to drift out of sync.
• Typed end to end. Request and response schemas are generated from the contract, so the OpenAPI document always matches what the server actually accepts and returns.
• OpenAPI 3.1. The Reference section in the sidebar is generated from that document — one interactive page per endpoint, with parameters, request and response schemas, code samples, and a "Try it" playground.

Base URL

REST endpoints are mounted under /api/v1 on the same origin that serves the dashboard, so the base URL is https://skillhub.fyi/api/v1. A full request path is that prefix plus the endpoint's path — for example:

GET /api/v1/registries/{ownerHandle}/{slug}

Reads use GET; mutations use POST / PUT / PATCH / DELETE. Query parameters bind to an endpoint's non-path inputs.

Most endpoints need a credential, but not all: everything under /api/v1/public/* answers anonymously, as do the two device-flow endpoints (they are how you obtain a credential, so they cannot require one) and the invitation preview at GET /api/v1/invites/{token}. Where a credential is required, a Bearer token is the portable way to send one — the facade also accepts the dashboard's own session cookie, since it is mounted on the same origin, which is what lets the web app call it without minting a token.

About the playground

Read on