API Reference
The authoritative per-endpoint reference for Honeyframe is the OpenAPI specification each service publishes. This page links to it and explains how to read it; a hand-maintained mirror would drift the moment a release ships.
Live specs
| Service | Spec URL | Interactive UI |
|---|---|---|
| Platform | https://platform.your-domain.com/openapi.json | https://platform.your-domain.com/docs |
| Hospital | https://hospital.your-domain.com/openapi.json | https://hospital.your-domain.com/docs |
| Cloud | https://cloud.your-domain.com/openapi.json | https://cloud.your-domain.com/docs |
The Swagger UI at /docs is interactive — paste a token into the Authorize dialog and try endpoints directly.
A ReDoc rendering is also available at /redoc on each service if you prefer the long-form layout.
Reading the spec
Each path in the OpenAPI document includes:
- HTTP method + path —
POST /api/datasets. - Tags — group endpoints by router (
datasets,dashboards,auth, ...). - Parameters — path, query, header, and request body schemas.
- Responses — status codes and the response body schema for each.
- Security —
bearerAuthfor endpoints that require a JWT (i.e. nearly all of them).
The spec does not document:
- The
X-Org-Idheader convention (covered under Authentication and API overview). - Rate limits (covered under Reverse Proxy).
- The error-body shape for
403responses (covered under Permissions Reference).
Read those operator-narrative pages alongside the spec for full context.
Quick navigation by router
Platform routers and their primary surfaces:
| Tag | Spec section | Operator narrative |
|---|---|---|
auth | /api/auth/* | Authentication |
users | /api/users/* | — |
groups | /api/groups/* | Groups |
organizations | /api/organizations/* | — |
projects | /api/projects/* | — |
connectors | /api/connectors/* | Connectors |
datasets | /api/datasets/* | Datasets |
dashboards | /api/dashboards/* | Dashboards |
pipeline | /api/pipeline/* | Flows |
lineage | /api/lineage/* | Flow |
audit | /api/audit/* | Audit Logging |
chat | /api/chat/* | — |
agent_tools | /api/agent-tools/* | — |
knowledge | /api/knowledge/* | — |
publishing | /api/publishing/* | — |
branding | /api/branding/* | — |
notifications | /api/notifications/* | — |
Generated clients
Generate a typed client from the spec — see SDK for the openapi-generator-cli workflow. Re-generate after each release; the generator's output is deterministic against a given spec.
Spec stability
OpenAPI changes follow semver:
- Patch releases (
v0.0.X) — backward-compatible changes only. New optional fields, new endpoints, expanded enum values. - Minor releases (
v0.X.0) — additive changes that may include new required fields on response bodies. Old clients keep working but may miss new data. - Major releases (
vX.0.0) — breaking changes. Removed endpoints, renamed fields, narrowed types. Update your generated client.
Honeyframe is in pre-1.0; treat every release as potentially breaking until the project commits to a stability window.
Diffing specs across releases
# Save the current spec
curl -s https://platform.your-domain.com/openapi.json > spec.current.json
# Compare against the spec from a tagged release
curl -s https://raw.githubusercontent.com/HubStudio-id/honeyframe/v0.0.3/openapi.json > spec.0.0.3.json
openapi-diff spec.0.0.3.json spec.current.json
openapi-diff prints a structured changelog (added/changed/removed paths and fields). Run it as part of your client-update workflow.
A note on undocumented endpoints
A handful of endpoints exist outside the OpenAPI doc — admin-only debugging surfaces, internal health checks, and deprecated paths kept for backward-compat. Treat the OpenAPI spec as the public contract; anything missing from it is not guaranteed to remain.
If you depend on an endpoint that's not in the spec, file an issue requesting its formalization.