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 /api/auth/login, /api/auth/google, and /api/csp-report) requires a JWT 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/me

Tokens are short-lived (typically 1 hour). Refresh by logging in again — there is no refresh-token endpoint. For long-running processes, store the credentials and re-login on 401.

For programmatic access where you don't have a user session, mint a token via the Service Account flow documented under Authentication.

Multi-tenant context

Honeyframe is multi-tenant. Most write endpoints require an X-Org-Id header that scopes the request to a specific organization. Read endpoints infer the org from the token's default-org claim, but writes require explicit scoping to avoid mistakes when a user belongs to multiple orgs.

curl -X POST https://platform.your-domain.com/api/datasets \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Org-Id: 42" \
  -H "Content-Type: application/json" \
  -d '{ "name": "...", "connector_id": 7 }'

Surface map

The Platform API is grouped into ~40 routers. The most commonly hit are:

Prefix	What it covers
/api/auth/*	Login, password change, Google sign-in, password reset.
/api/users/*	User CRUD, role assignment.
/api/groups/*	Groups, memberships, permissions (Phase 1 RBAC).
/api/organizations/*	Org-level admin: create, members, settings.
/api/projects/*	Projects within an org.
/api/connectors/*	Connector CRUD + test.
/api/datasets/*	Dataset CRUD, schema, preview, explore (run a query).
/api/dashboards/*	Dashboard CRUD + render.
/api/pipeline/*	Run recipes / Flow targets, list runs, get logs.
/api/lineage/*	Lineage graph for a dataset, including column-level.
/api/audit/*	Read the audit log (admin only).
/api/branding/*	Org-level customer branding overrides (logo, tagline, colors).
/api/chat/*	Chat surface — SQL, knowledge, agent modes.
/api/agent_tools/*	Tool definitions for the Agent Builder.
/api/knowledge/*	Knowledge bases + RAG search.
/api/publishing/*	Publish dashboards / API endpoints / app pages to the SaaS surface.

The App service exposes a vertical-specific subset. The exact prefixes depend on the published app's domain model — typically read-only entity lookups plus published dashboards. The reference template ships with:

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/domains/*	Domain mappings to services.
/api/license/*	Org license details, seat usage.
/api/organizations/*	Cross-org admin (root operator only).

Discovery

Each service exposes an OpenAPI document at /openapi.json and an interactive Swagger UI at /docs (e.g. https://platform.your-domain.com/docs). The OpenAPI doc is the authoritative per-endpoint reference; this page is the operator narrative.

For a richer per-endpoint walkthrough (request/response examples, auth nuances, webhook payloads), see Developer → Core API.

Pagination, sorting, filtering

Most list endpoints share a common shape:

GET /api/<resource>?limit=50&offset=0&sort=created_at&order=desc&q=<search>

• limit — capped at 200.
• offset — opaque integer offset. There is no cursor pagination today.
• sort — column name from the resource's schema.
• order — asc or desc.
• q — free-text search, matched against name + description fields.

Resources with a status enum accept ?status=published&status=draft (repeatable).

Error model

Errors are JSON with a stable shape:

{
  "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, 500 server). The body adds machine-readable context.

Rate limits

The reverse proxy enforces two rate-limit zones — see Reverse Proxy:

• /api/auth/* — 5 req/s sustained, burst 10.
• /api/* — 30 req/s sustained, burst 60.

These are per client IP. Behind a load balancer that masks client IPs, configure set_real_ip_from in nginx so the limit applies to real clients.

SDK

A first-party SDK is on the roadmap. Until it ships, generate a client from /openapi.json using openapi-generator-cli or any equivalent tool. The OpenAPI document is updated on every release; a generated Python or TypeScript client should require minimal hand-tuning.