Skip to content

Runtime API

The Runtime API exposes Zakardo functionality through REST endpoints and Server-Sent Events (SSE) streaming.

import { Hono } from 'hono';
import { createZakardoApp } from '@zakardo/core';
const { app: zakardoApp } = await createZakardoApp({
config,
capabilities,
implementations,
policies,
});
const app = new Hono();
app.route('/zakardo', zakardoApp);
MethodPathDescription
POST/v1/intentSubmit a new intent
POST/v1/intent/clarificationRespond to a clarification
MethodPathDescription
GET/v1/executionsList recent executions
GET/v1/executions/:idGet execution detail
POST/v1/executions/:id/approveApprove a gate
POST/v1/executions/:id/rejectReject a gate
POST/v1/executions/:id/cancelCancel execution
MethodPathDescription
GET/v1/capabilitiesList capabilities
GET/v1/capabilities/:nameGet capability detail
MethodPathDescription
GET/v1/plansList plans
GET/v1/plans/:idGet plan detail
MethodPathDescription
GET/v1/tracesList traces
GET/v1/traces/:idGet trace detail
MethodPathDescription
GET/v1/healthRuntime health check

Connect to /v1/stream/:execution_id for real-time execution events:

const eventSource = new EventSource('/zakardo/v1/stream/exec_123');
eventSource.onmessage = (event) => {
const data = JSON.parse(event.data);
console.log(data.type, data);
};

The @zakardo/client package provides a typed SDK:

import { ZakardoClient } from '@zakardo/client';
const client = new ZakardoClient({
baseUrl: 'http://localhost:3000/zakardo',
});
// Submit intent
const result = await client.intent.submit({ message: 'List all contacts' });
// Stream execution
client.executions.stream(result.execution_id, {
onStepCompleted: (event) => console.log('Step done:', event),
onCompleted: (event) => console.log('Done:', event),
});