K3 API Reference

Last validated: 2026-05-14

This reference is now split into service-focused pages so you can jump directly to the API surface you need.

Validation sources:

• dodil-k3/proto/proto-k3/*.proto
• dodil-k3/bin/api/src/http/api/mod.rs

Start Here

1. Common Conventions
   • Auth headers, pagination, optional field semantics, compatibility notes.
2. StorageService
   • AWS S3-compatible bucket/object operations, plus policy, CORS, and object metadata/url APIs.
3. SourceService
   • Sources, credentials, OAuth authorization and token exchange.
4. PipelineService
   • Pipeline lifecycle and Scriptum template catalog APIs.
5. IngestService
   • Rules, discovery, source ingestion triggers, and ingest jobs.
6. VectorService
   • Vector engine, collections, search, and external vector writes.
7. TableService
   • Table engine, table lifecycle, SQL execution, maintenance, and materialization.

DuckDB SQL Cheat Sheet (TableService)

Use these query patterns with TableService query endpoints (POST /:bucket/tables/_query or Execute).

-- 1) Grouped counts
SELECT kind, COUNT(*) AS cnt
FROM {table}
GROUP BY kind
ORDER BY cnt DESC;
 
-- 2) Time buckets
SELECT date_trunc('hour', created_at) AS hour_bucket, COUNT(*)
FROM {table}
GROUP BY 1
ORDER BY 1;
 
-- 3) Window ranking
SELECT id, kind, ROW_NUMBER() OVER (PARTITION BY kind ORDER BY created_at DESC) AS rn
FROM {table};
 
-- 4) JSON extraction
SELECT json_extract_string(payload, '$.customer_tier') AS tier, COUNT(*)
FROM {table}
GROUP BY tier;
 
-- 5) Percentile view
SELECT quantile_cont(duration_ms, 0.95) AS p95_ms
FROM {table};

For argument-level details and more examples, see TableService.

Service Packages

1. dodil.k3.storage.v1
2. dodil.k3.source.v1
3. dodil.k3.pipeline.v1
4. dodil.k3.ingest.v1
5. dodil.k3.vector.v1
6. dodil.k3.tables.v1

Probes and Observability

• GET /health
• GET /healthz
• GET /ready
• GET /readyz
• GET /metrics

For CLI command coverage and usage details, see 05-cli-guide.md.