Toilville Ritual Engine API

SPELWork-native API for wishes, rituals, and deliberative workflows. Routes intent through semantic patterns, Kafka event streams, and graph-backed knowledge — governed by actor consent and dimensional rubrics.

AI Agent Tiers — Reading this API response is T0 (default). Summarizing for a user is T1. Taking action on behalf of a user is T2+.

Declare your tier in the X-SPELWork-Agent-Tier request header. Discovery: /.well-known/agent.json

Key Endpoints

POST

/rituals Submit a ritual for execution. Requires authenticated actor + wish payload.

GET

/rituals/{id} Retrieve ritual status, lineage, and dimensional scores.

POST

/wishes Register a new wish. Runs the Seven Questions rubric and queues for scheduling.

GET

/wishes/{id}/rubric Fetch the dimensional rubric scores for a wish.

GET

/actors/{id} Actor profile, consent state, and trust tier.

GET

/health Service health. No auth required.

SPEL Dimensions

Stewardship

Proximity and delegation of responsibility between actors.

Plurality

Variance across voices — diversity of perspective in a deliberation.

Evidence

Confidence and source count backing an assertion or output.

Lineage

Run provenance — dataset URN, pipeline run ID, and trace linkage.

Quick Start

# Health check
curl https://api.toilville.dev/health

# Submit a wish (authenticated)
curl -X POST https://api.toilville.dev/wishes \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"intent": "generate weekly report", "actor_id": "..."}'

Resources

API Docs Source SSO / Auth agent.json Forge Portal