REST API Reference

Last updated April 7, 2026

All HTTP endpoints — where to find the live OpenAPI spec and the key surfaces of each service.

KB Labs exposes HTTP APIs across three services. Each serves its own OpenAPI spec at /openapi.json and Swagger UI at /docs. This page explains where to look, what's on each service, and the conventions that apply everywhere.

The live OpenAPI spec at /openapi.json is the canonical reference — it's generated from the running code and is always up to date. This page is a navigational guide; use the spec for exact request/response schemas.

Services and ports

Service	Default port	Swagger UI	OpenAPI spec
REST API	5050	`http://localhost:5050/docs`	`http://localhost:5050/openapi.json`
Workflow Daemon	7778	`http://localhost:7778/docs`	`http://localhost:7778/openapi.json`
Gateway	4000	`http://localhost:4000/docs`	`http://localhost:4000/openapi.json`
Gateway (merged)	4000	`http://localhost:4000/docs-all`	`http://localhost:4000/openapi-merged.json`

The Gateway's merged spec (/openapi-merged.json) aggregates the REST API and Workflow Daemon specs — useful for generating a single client or browsing all endpoints in one place.

Start services with:

Bash

kb-dev start          # all services
kb-dev start rest     # REST API + dependencies
kb-dev start workflow # Workflow Daemon + dependencies
kb-dev start gateway  # Gateway + all backend

URL conventions

All endpoints use the /api/v1 prefix:

POST  http://localhost:5050/api/v1/workflows/runs
GET   http://localhost:5050/api/v1/jobs/:jobId
GET   http://localhost:5050/api/v1/routes          # lists all registered routes

Without the prefix, requests return 404. Plugin endpoints follow the same pattern, nested under /api/v1/plugins/<plugin-id>/.

REST API (port 5050)

The main platform REST API. Key endpoint groups:

Platform

GET  /api/v1/health              Service health
GET  /api/v1/routes              All registered routes (meta-endpoint)
GET  /openapi.json               OpenAPI spec
GET  /openapi-plugins.json       Plugin manifests as OpenAPI spec

Workflows

POST   /api/v1/workflows/runs         Start a workflow run
GET    /api/v1/workflows/runs         List runs
GET    /api/v1/workflows/runs/:runId  Get run status
DELETE /api/v1/workflows/runs/:runId  Cancel run
GET    /api/v1/workflows/runs/:runId/logs  Run logs

Jobs

POST  /api/v1/jobs              Submit a background job
GET   /api/v1/jobs/:jobId       Job status and result

Marketplace

GET  /api/v1/marketplace/plugins        Installed plugins
POST /api/v1/marketplace/plugins        Install plugin
GET  /api/v1/marketplace/plugins/:id    Plugin detail
DELETE /api/v1/marketplace/plugins/:id  Uninstall plugin

Plugin routes

Each plugin with a rest section in its manifest gets endpoints mounted at:

/api/v1/plugins/<plugin-id>/<route-path>

For example, the commit plugin exposes:

POST /api/v1/plugins/commit/generate
POST /api/v1/plugins/commit/apply
GET  /api/v1/plugins/commit/status

Browse all plugin routes at /openapi-plugins.json or via Swagger UI.

Workflow Daemon (port 7778)

Orchestrates long-running workflow executions. Exposes its own REST surface for run management and step coordination.

GET  /api/v1/health
POST /api/v1/workflows/runs
GET  /api/v1/workflows/runs/:runId
GET  /api/v1/workflows/runs/:runId/steps

The Workflow Daemon spec is included in the Gateway's merged spec — you don't need to call it directly from client code (route through the Gateway or REST API instead).

Gateway (port 4000)

Central router that forwards requests to the appropriate backend service. Clients should prefer the Gateway over calling individual services directly — it handles:

Request routing to REST API or Workflow Daemon
Authentication middleware
Plugin execution dispatch (for plugins with a remote host agent)

GET  /api/v1/health
GET  /openapi.json              Gateway-native routes only
GET  /openapi-merged.json       All routes from all services
GET  /docs                      Swagger UI (gateway routes)
GET  /docs-all                  Swagger UI (merged spec)

Authentication

Most endpoints are unauthenticated in local development. For production deployments or multi-tenant setups, the Gateway supports:

Token auth — Authorization: Bearer <token> header
Tenant identification — X-Tenant-ID: <tenantId> header

See Gateway → Authentication for the full auth model.

Visibility rules

Not all routes appear in the OpenAPI spec. KB Labs uses tags as a visibility toggle:

Routes with tags: ['TagName'] are public — appear in /docs and /openapi.json
Routes without tags are hidden — internal or admin-only
Routes with schema: { hide: true } are explicitly excluded (SSE/streaming routes)

When a route you expect doesn't appear in Swagger UI, it may be intentionally hidden. Check GET /api/v1/routes for the complete unfiltered list of registered routes.

Consuming the API

Fetch the spec

Bash

# Download the merged spec for client generation
curl http://localhost:4000/openapi-merged.json > openapi.json
 
# Or REST API spec only
curl http://localhost:5050/openapi.json > openapi.json

Generate a typed client

Bash

# Using openapi-typescript
npx openapi-typescript http://localhost:5050/openapi.json -o ./api.d.ts
 
# Using @hey-api/openapi-ts
npx @hey-api/openapi-ts --input http://localhost:5050/openapi.json --output ./client

Common request headers

Content-Type: application/json
Accept: application/json
X-Tenant-ID: <tenantId>          # optional, defaults to 'default'
Authorization: Bearer <token>     # required in production

Error responses

All services return errors in a consistent shape:

JSON

{
  "error": {
    "code": "WORKFLOW_NOT_FOUND",
    "message": "Workflow run abc123 not found",
    "details": {}
  }
}

HTTP status codes follow standard semantics: 400 for bad input, 401/403 for auth failures, 404 for missing resources, 429 for rate limits, 500 for server errors. See Error Codes for the full catalog.