API

Honeyframe exposes a REST API on each of its services. Most operator workflows go through the API — the platform UI is itself a client of the same endpoints.

This page is the operator-facing overview. For the developer reference (auth tokens, SDK usage, per-endpoint signatures, webhooks), see the Developer property.

Service surfaces

Service	Default URL	Purpose
Platform	https://platform.your-domain.com/api	Authoring surface — connectors, datasets, recipes, dashboards, agents, RBAC.
App (vertical SaaS)	https://app.your-domain.com/api	Customer-facing surface for a published vertical app — read-only routes for dashboards and the domain entities the app exposes.
Cloud	https://cloud.your-domain.com/api	Infrastructure surface — organizations, servers, domains, license.

The Platform API is the primary surface for analytics workflows. The App and Cloud surfaces expose narrower subsets for their respective audiences.

Authentication

Every endpoint except the sign-in routes (/api/auth/login, /api/auth/google, /api/auth/microsoft, password reset) and a few probes requires a bearer token. Get a token by logging in:

TOKEN=$(curl -s -X POST https://platform.your-domain.com/api/auth/login \
  -H 'Content-Type: application/json' \
  -d '{"username":"you@example.com","password":"<redacted>"}' \
  | jq -r '.access_token')

curl -H "Authorization: Bearer $TOKEN" https://platform.your-domain.com/api/auth/me

Session JWTs expire after 8 hours (480 minutes, configurable by the operator). There is no refresh-token endpoint — log in again when the token expires.

For scripts, CI, and the SDK, use a Personal Access Token (hf_…) instead of a JWT. Mint one from the platform UI or POST /api/auth/tokens, then send it on the same Authorization: Bearer header. See Authentication → Personal Access Tokens.

Organization and project context

Honeyframe is multi-tenant. A request runs in the caller's primary organization unless it names another one with the X-Org-Id header — the same switch the UI's org picker uses. X-Org-Id is honored only for organizations the caller belongs to (platform superadmins may name any org). The active project is chosen the same way, with X-Project-Id.

A Personal Access Token minted with an org or project scope is pinned to it: the token's scope overrides any X-Org-Id / X-Project-Id the caller sends.

curl https://platform.your-domain.com/api/datasets \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Org-Id: 42" \
  -H "X-Project-Id: 7"

Surface map

The Platform API is grouped into more than 150 routers. The most commonly used are:

Prefix	What it covers
/api/auth/*	Login, /me, password change and reset, Google / Microsoft sign-in, Personal Access Tokens (/api/auth/tokens).
/api/users/*	User administration.
/api/groups/*	Groups, memberships, permissions.
/api/organizations/*	Org-level admin: members, settings, per-org plugins.
/api/projects/*	Projects within an org.
/api/connectors/*	Connector CRUD, test, credential rotation.
/api/datasets/*	Dataset CRUD, schema, preview, explore.
/api/sql	Governed query endpoint — project-scoped, read-only, statement-timeout enforced.
/api/dbt/*	dbt authoring: read/write models, run / test / build / compile.
/api/flow/*	Flow recipes and the visual Flow.
/api/pipeline/*	Scenarios, triggers, runs, jobs, scheduler health — see Scheduler.
/api/dashboards/*	Dashboard CRUD, cards, execution, sharing.
/api/webapps/*	Webapps; anonymous public variants under /api/public/webapps/*.
/api/lineage/*, /api/column-lineage/*	Lineage graphs, including column level.
/api/catalog/*	Metadata catalog adapters and the cross-tool lineage walk.
/api/audit/*	The audit log (admin only).
/api/branding/*	Org-level branding (logo, tagline, colors).
/api/chat/*	Agent chat sessions and models.
/api/agent-tools/*	Tool definitions for agents.
/api/knowledge-bases/*	Knowledge Banks and retrieval.
/api/cobuild/*	Cobuild sessions.
/api/publish/*	Publish dashboards, API services, and app pages.
/api/admin/ldap-config	LDAP configuration, test, and sync.

The App service exposes a narrower, read-oriented subset for a published app — typically entity lookups plus published dashboards:

Prefix	What it covers
/api/<entity>/*	Domain entity detail + list (one set per entity defined in the app schema).
/api/dashboards/*	Published dashboards (read-only).

Cloud exposes infrastructure routes:

Prefix	What it covers
/api/servers/*	Server inventory and health.
/api/databases/*	Managed databases.
/api/domains/*	Domain mappings to services.
/api/cloud-accounts/*	Cloud provider accounts.
/api/billing/*	Usage and billing.
/api/organizations/*	Cross-org admin (platform operator only).

Discovery

The OpenAPI document (/openapi.json, plus Swagger UI at /docs) is served by the backend process itself, not on the public domain — the reference reverse-proxy configuration forwards only /api/*. Fetch it on the server (for example curl http://localhost:8001/openapi.json on the Platform host), or expose it deliberately behind authentication. The OpenAPI document is the authoritative per-endpoint reference; this page is the operator narrative. It also lists internal routes — routes not documented on this site are not a stable contract and can change between releases.

For per-endpoint walkthroughs (request/response examples, auth details, webhook payloads), see Developer → Core API.

Pagination and filtering

There is no single platform-wide list convention. Most list endpoints accept limit (with a per-endpoint maximum) and many accept offset; filters are endpoint-specific query parameters (for example status, scope, or category). Check the endpoint's page under Developer → Core API or the generated schema.

Error model

Errors use FastAPI's shape: a JSON object with a detail field. detail is a string for most errors and an object when the platform adds machine-readable context — for example a permission denial:

{
  "detail": {
    "error": "permission_denied",
    "permission": "dashboard.edit",
    "target_id": "7",
    "message": "Your group memberships do not grant 'dashboard.edit' on 7."
  }
}

The HTTP status code is the primary indicator (401 unauthenticated, 403 forbidden, 404 not found, 409 conflict, 422 validation, 5xx server or upstream failure).

Rate limits

The shipped reverse-proxy configuration defines two rate-limit zones — see Reverse Proxy:

• /api/auth/* — 5 requests/s per client IP, burst 10.
• /api/* — 30 requests/s per client IP, burst 60.

Behind a load balancer that masks client IPs, configure set_real_ip_from in nginx so the limits apply to real clients.

SDK

Honeyframe ships a first-party Python client, honeyframeapi (pip install honeyframeapi). It wraps the API behind typed handles for projects, datasets, recipes, dashboards, bundles, agents, and webapps, and includes a honeyframe CLI. Authenticate with a Personal Access Token. See Developer → SDK.