Share API
kilter share "description" publishes a project learning into this knowledge base's moderation queue. Admins review submissions at /admin/queue; approved notes appear on tagged doc pages and in semantic search.
Status
The CLI command is not shipped yet — this page defines the contract it will use. Until then, submit with curl (below) or the web form at /notes/new.
Endpoint
POST /api/share
Authorization: Bearer <KB_SHARE_TOKEN>
Content-Type: application/json
The token is the KB_SHARE_TOKEN env var configured on the kilterKB deployment (see kilter.yaml).
Request body
| Field | Type | Required | Notes |
|---|---|---|---|
body | string | ✓ | The learning, markdown ok. 10–10 000 chars. |
source | "cli" | ✓ | Literal — web submissions use the form instead. |
title | string | ≤ 200 chars. | |
project | string | Which project this came from. | |
author | string | Free-text attribution. | |
kilter_version | string | kilter version output. | |
suggested_docs | string[] | Doc slugs to suggest tagging (≤ 10). |
Responses
| Status | Meaning |
|---|---|
201 | Queued — body: { "id": "<uuid>", "status": "pending" } |
400 | Validation failed (details in body) |
401 | Missing/invalid bearer token |
429 | Rate limited (30/min) |
503 | KB_SHARE_TOKEN unset on the server |
Example
curl -X POST "$KB_URL/api/share" \
-H "Authorization: Bearer $KB_SHARE_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"body": "KIND clusters keep state across kilter stop / kilter up — only destroy loses it.",
"source": "cli",
"project": "my-app",
"suggested_docs": ["k8s-tutorials/kind"]
}'