REST API¶
Starting the Server¶
Endpoints¶
Get Rules¶
curl http://localhost:8000/api/v1/scopes/python-general/rules
curl -H "Accept: application/json" \
http://localhost:8000/api/v1/scopes/python-general/rules
curl -H "Accept: text/markdown" \
http://localhost:8000/api/v1/scopes/python-general/rules
List Available Scopes¶
Force Reload¶
Clear all in-memory caches and reload rules, katas, and tenka from disk. This is also propagated to the master server if federation is configured.
Filter by Categories¶
Debug Mode¶
Debug mode skips template expansion and returns the original, unprocessed content:
# Get raw rules without template rendering
curl "http://localhost:8000/api/v1/scopes/python-general/rules?debug=true"
# Get raw category index without template rendering
curl "http://localhost:8000/api/v1/scopes/python-general/index?debug=true"
The debug parameter (default: false) is useful for:
- Viewing the original rules and categories as defined in YAML files
- Debugging why templates may be changing content unexpectedly in production
- Inspecting template syntax before variables are substituted
Submit Feedback¶
POST /api/v1/feedback — append a feedback entry to the JSONL file. See Feedback for full details and examples.
curl -X POST http://localhost:8000/api/v1/feedback \
-H "Content-Type: application/json" \
-d '{"type":"missed_categories","task":"Adding a REST endpoint","categories":["development.domain_specific.apis.rest"],"reason":"Focused on Python rules initially"}'
Tenka Endpoints¶
Get User Stories¶
curl http://localhost:8000/api/v1/scopes/python-general/tenka/stories
curl "http://localhost:8000/api/v1/scopes/python-general/tenka/stories?status=not_validated"
curl "http://localhost:8000/api/v1/scopes/python-general/tenka/stories?tags=Functional,Technical"
Returns user stories for a scope in Markdown format. Supports ?status= filter (validated, not_validated, all), ?include_inactive=true, and ?tags= (comma-separated tags).
Get Acceptance Criteria¶
curl http://localhost:8000/api/v1/scopes/python-general/tenka/acs
curl "http://localhost:8000/api/v1/scopes/python-general/tenka/acs?stories=US123,US456"
curl "http://localhost:8000/api/v1/scopes/python-general/tenka/acs?tags=OWASP%20A03:2021"
Returns a flat list of acceptance criteria in Markdown format. Supports ?stories= (comma-separated IDs), ?status=, ?include_inactive=true, and ?tags= (comma-separated tags).
Get Validation Status¶
curl http://localhost:8000/api/v1/scopes/python-general/tenka/validation
curl "http://localhost:8000/api/v1/scopes/python-general/tenka/validation?passing=not_validated&automation=automated"
Returns the validation status of ACs. Supports ?acs= (comma-separated AC refs), ?passing= (validated, not_validated, all), and ?automation= (automated, has_manual, all).
Kata Endpoints¶
Get Kata Category Index¶
curl http://localhost:8000/api/v1/scopes/python-general/katas/index
curl -H "Accept: application/json" \
http://localhost:8000/api/v1/scopes/python-general/katas/index
curl -H "Accept: text/markdown" \
http://localhost:8000/api/v1/scopes/python-general/katas/index
Returns a hierarchical index of all categories that contain katas, with their when descriptions. Does not support ?categories= filtering.
List Katas¶
curl http://localhost:8000/api/v1/scopes/python-general/katas
curl "http://localhost:8000/api/v1/scopes/python-general/katas?categories=python.testing"
Returns kata names organised by category. Supports the same ?categories= prefix filter as rule endpoints.
Get Kata Procedure¶
Returns the rendered procedure for a single kata in markdown. Scope inheritance is applied — the kata may originate from a parent scope.
When the same kata name exists in multiple categories, use ?category= to select the correct one:
All kata endpoints accept ?debug=true to skip Jinja2 template rendering.
Interactive API Documentation¶
Visit http://localhost:8000/docs for interactive API documentation (Swagger UI).