Runtime API
The Runtime API exposes Zakardo functionality through REST endpoints and Server-Sent Events (SSE) streaming.
Mounting the API
Section titled “Mounting the API”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);Endpoints
Section titled “Endpoints”Intent
Section titled “Intent”| Method | Path | Description |
|---|---|---|
POST | /v1/intent | Submit a new intent |
POST | /v1/intent/clarification | Respond to a clarification |
Executions
Section titled “Executions”| Method | Path | Description |
|---|---|---|
GET | /v1/executions | List recent executions |
GET | /v1/executions/:id | Get execution detail |
POST | /v1/executions/:id/approve | Approve a gate |
POST | /v1/executions/:id/reject | Reject a gate |
POST | /v1/executions/:id/cancel | Cancel execution |
Capabilities
Section titled “Capabilities”| Method | Path | Description |
|---|---|---|
GET | /v1/capabilities | List capabilities |
GET | /v1/capabilities/:name | Get capability detail |
| Method | Path | Description |
|---|---|---|
GET | /v1/plans | List plans |
GET | /v1/plans/:id | Get plan detail |
Traces
Section titled “Traces”| Method | Path | Description |
|---|---|---|
GET | /v1/traces | List traces |
GET | /v1/traces/:id | Get trace detail |
Health
Section titled “Health”| Method | Path | Description |
|---|---|---|
GET | /v1/health | Runtime health check |
SSE Streaming
Section titled “SSE Streaming”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);};Client SDK
Section titled “Client SDK”The @zakardo/client package provides a typed SDK:
import { ZakardoClient } from '@zakardo/client';
const client = new ZakardoClient({ baseUrl: 'http://localhost:3000/zakardo',});
// Submit intentconst result = await client.intent.submit({ message: 'List all contacts' });
// Stream executionclient.executions.stream(result.execution_id, { onStepCompleted: (event) => console.log('Step done:', event), onCompleted: (event) => console.log('Done:', event),});