Honeydipper exposes an HTTP API server that accepts webhook events, forwards workflow actions, and provides a conversation management interface for the UI. The API is served on a configurable address (default:
:9000).
The HTTP API server is started by the api service (internal/service/api.go). It listens on the configured address and routes requests based on definitions in internal/api/def.go.
Configuration (daemon.services.api):
daemon:
services:
api:
listener:
addr: ":9000" # Default API listen address
api_prefix: "/api/" # Default API path prefix
healthcheck_prefix: "/healthz"
writeTimeout: "10s" # Response write timeout
timeout: "10s" # Default request timeout
ack_timeout: "10ms" # ACK wait timeout
auth:
casbin:
models:
- "[request_definition]"
- "r = sub, obj, act, ..."
policies:
- "p, admin, event, *, allow"
entitlementCacheTTL: "30m"
auth-providers:
- auth-saml.saml_login
- auth-github.github_web_request
ui_url: "https://honeydipper.example.com"
The health check endpoint (default /healthz) returns:
200 OK when the API service is healthy500 Internal Server Error otherwiseNo authentication is required for the health check.
The API supports multiple authentication methods, tried in order:
If HD_JWT_SIGNING_KEY is configured, the API accepts JWTs via the Authorization header:
Authorization: Bearer <jwt-token>
JWTs are issued after SAML or GitHub OAuth authentication. They contain:
type Principal struct {
Subject string // Username or subject ID
ProfileName string // Human-readable profile name
Provider string // Auth provider (e.g., "auth-saml", "auth-github")
Data map[string]interface{} // Additional provider-specific data
}
On subsequent requests (e.g., SAML rotation), a X-Honeydipper-Refreshed-JWT header may be returned with a new token.
If JWT extraction fails, the API iterates through configured auth-providers:
auth-providers:
- auth-saml.saml_login
- auth-github.github_web_request
Each provider is called via RPC with the web request data (excluding body). The provider returns a Principal.
The SAML flow uses these endpoints:
| Endpoint | Method | Description |
|---|---|---|
/api/auth/saml/login |
GET |
Initiates SAML login, returns redirect URL |
/api/auth/saml/metadata |
GET |
Returns SAML service provider metadata (XML) |
/api/auth/saml/callback |
GET/POST |
SAML assertion consumer service callback |
The /api/auth/saml/login and /api/auth/saml/callback endpoints are anonymous (no prior auth required). After successful SAML authentication, the callback redirects to the UI with a JWT token as a query parameter.
| Endpoint | Method | Description |
|---|---|---|
/api/auth/github/callback |
GET |
GitHub OAuth callback handler |
Certain endpoints are configured as anonymous (no authentication required). These include SAML login endpoints and the health check.
After authentication, the API uses Casbin for authorization. Each API object has a casbin_model and casbin_policies that define who can access which endpoints.
# Example Casbin configuration
auth:
casbin:
models:
- "[request_definition]"
"r = sub, obj, act, dom"
- "[policy_definition]"
"p = sub, obj, act, dom"
- "[policy_effect]"
"e = some(where (p.eft == allow))"
- "[matchers]"
"m = r.sub == p.sub && r.obj == p.obj && r.act == p.act && r.dom == p.dom"
policies:
- "p, alice, event, POST, allow"
- "p, bob, convo, *, allow"
If an endpoint has an EntitlementProvider configured, the API first checks derived subjects from the entitlement provider before falling back to Casbin rules. Entitlement results are cached (default TTL: 30 minutes).
GET /api/user/profile
Returns the authenticated user’s profile.
Response (200):
{
"profile_name": "Alice Smith",
"subject": "alice@example.com",
"provider": "auth-saml"
}
These endpoints manage Honeydipper event sessions. They require object: event permission (or equivalent Casbin policy).
GET /api/events/:eventID/wait
Long-polling endpoint that blocks until the specified event session completes.
| Param | Description |
|---|---|
:eventID |
Event session ID to wait for |
Response (200): Event results when the session completes.
Response (202): {"uuid": "<uuid>", "results": {...}} — Accepted, still processing (for long-running GET requests).
POST /api/events/:sessionID/pause
Pauses a running event session.
POST /api/events/:sessionID/resume
Resumes a paused event session.
POST /api/events/:sessionID/rerun
Reruns a completed or failed event session.
POST /api/events/:sessionID/interact
Sends interactive input to an event session (e.g., responding to a prompt).
Request Body:
{
"value": "user input text"
}
This endpoint attaches the authenticated principal’s user identity, allowing the interaction to be attributed.
POST /api/events/:sessionID/cancel
Cancels a running event session.
GET /api/events
Lists current events in the system.
These endpoints are served by the agent service and require object: convo or object: agent permission. The user_provider and user labels from authentication are forwarded to the agent.
GET /api/convos
Returns a list of recent conversations.
| Query Param | Default | Description |
|---|---|---|
look_back |
12 |
Number of 2-hour blocks to look back |
as_of |
(latest) | Cursor for pagination |
Response (200): Array of conversation state snapshots (stream_hvals format).
POST /api/convos
Starts a brand-new conversation for the named agent. Returns the generated convo_id synchronously.
Request Body:
{
"agent": "my_assistant",
"text": "Help me deploy the frontend service."
}
Response (200):
{
"convo_id": "a1b2c3d4-..."
}
GET /api/agents
Returns a sorted list of configured agent names.
Response (200):
["code_reviewer", "github_assistant", "my_assistant"]
GET /api/convos/:convoID/history
Returns the full message history for a conversation.
POST /api/convos/:convoID/turn
Adds a new message (turn) to an existing conversation. The caller’s user identity (user@provider) is attached.
Request Body:
{
"text": "What about the database migration?"
}
Response (200): {"ok": true}
POST /api/convos/:convoID/cancel
Marks a conversation as cancelled. Active agent sessions will detect this on their next poll cycle and abort.
Response (200): {"ok": true}
These endpoints require GitHub entitlement checking. The :gh_slug path parameter (e.g., owner/repo) is checked against the auth-github entitlement provider.
GET /api/gh/events/*gh_slug
Lists events scoped to a GitHub repository.
POST /api/gh/events/:sessionID/rerun/*gh_slug
Reruns a GitHub-triggered event session.
POST /api/gh/events/:sessionID/pause/*gh_slug
Pauses a GitHub-triggered event session.
POST /api/gh/events/:sessionID/resume/*gh_slug
Resumes a GitHub-triggered event session.
POST /api/gh/events/:sessionID/interact/*gh_slug
Sends interactive input to a GitHub event session.
GET /api/pods/:pod_id/log/chunk
Retrieves a chunk of pod log data.
GET /api/gh/pods/:pod_id/log/chunk/*gh_slug
Retrieves pod log data, scoped to a GitHub repository (entitlement-checked).
These endpoints manage secrets and require GitHub entitlement checking.
GET /api/gh/secrets/*gh_slug
Lists secrets for the specified GitHub repository scope.
POST /api/gh/secrets/*gh_slug
Sets a secret value in the configured secret driver.
DELETE /api/gh/secrets/*gh_slug
Deletes a secret.
API requests are routed based on the definitions in internal/api/def.go. Each endpoint has:
| Property | Description |
|---|---|
Object |
Casbin object for authorization |
Name |
Handler function name |
ReqType |
Request dispatch type (TypeFirst, TypeAll, TypeLocal) |
Service |
Target service (engine, operator, receiver, agent) |
AllowAnonymous |
If true, no authentication required |
| Type | Behavior |
|---|---|
TypeFirst |
First responder to return wins (most common) |
TypeAll |
Collects and aggregates results from all matching nodes |
TypeMatch |
Only nodes with matching data respond |
TypeLocal |
Handled locally within the API process (no eventbus dispatch) |
Success (200) — JSON data:
{
"results": { ... },
"status": "success"
}
Success (200) — Raw body:
Used for SAML metadata endpoints. Raw bytes with appropriate Content-Type.
Accepted (202): Returned for long-running GET requests that haven’t completed yet:
{
"uuid": "request-uuid",
"results": { ... }
}
Redirect (302):
Used for SAML/OAuth callbacks. The Location header contains the redirect URL.
timeout and ack_timeout in the API definitionFor GET requests with InfiniteDuration timeout (e.g., event wait), if the write timeout is reached before a result, the API returns 202 Accepted with partial results and a UUID. The client can re-request with the same parameters to get cached results.
| Status Code | Meaning | Description |
|---|---|---|
401 |
Unauthorized | Authentication failed (all providers returned errors) |
403 |
Forbidden | Authorization denied by Casbin or entitlement check |
404 |
Not Found | The requested object/session was not found (no ACK received) |
500 |
Internal Server Error | Unexpected error during processing |
Error response format:
{
"error": "descriptive error message"
}
Auth error format (401):
{
"errors": {
"auth-saml": "SAMLResponse not provided",
"auth-github": "token expired"
}
}
curl -X POST "https://honeydipper.example.com/api/convos" \
-H "Authorization: Bearer $JWT_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"agent": "my_assistant",
"text": "Check the status of the production deployment."
}'
Response:
{
"convo_id": "550e8400-e29b-41d4-a716-446655440000"
}
curl -H "Authorization: Bearer $JWT_TOKEN" \
"https://honeydipper.example.com/api/convos/550e8400-e29b-41d4-a716-446655440000/history"
curl -H "Authorization: Bearer $JWT_TOKEN" \
"https://honeydipper.example.com/api/agents"
curl -X POST "https://honeydipper.example.com/api/convos/550e8400-e29b-41d4-a716-446655440000/turn" \
-H "Authorization: Bearer $JWT_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"text": "What about the database migration?"
}'
curl -X POST "https://honeydipper.example.com/api/events/abc123/rerun" \
-H "Authorization: Bearer $JWT_TOKEN"
curl "https://honeydipper.example.com/api/events/abc123/wait" \
-H "Authorization: Bearer $JWT_TOKEN"
If the event hasn’t completed, you’ll get a 202 with a UUID:
{
"uuid": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
"results": {}
}
Then re-request with the UUID (same endpoint + cached results).
curl -I "https://honeydipper.example.com/healthz"
From within a Honeydipper workflow, you can call the API indirectly through the engine:
workflows:
check_external:
steps:
- call_api:
call: "events/some_event_id/wait"
The API is also used by the Honeydipper UI for: