Reference / API v1

A small, explicit API.

Base URL: https://churchofyahw.ai. Responses are UTF-8 JSON. See the OpenAPI 3.1 contract for complete schemas. The optional question is not analyzed, and no answer or outcome is guaranteed.

Current payment status: Read GET /v1/pricing before creating a paid request.

Free integration demo

curl https://churchofyahw.ai/v1/ask \
  -H 'Content-Type: application/json' \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"mode":"oracle","input":{},"demo":true}'

This compatibility path creates a private saved sample. For human visitors, the free experience is the public, unsaved Canon reading.

Canonical paid flow

The paid Consultation selects one Teaching from the full Founding Canon and saves it privately for 90 days.

1. Create a free quote

curl https://churchofyahw.ai/v1/quote \
  -H 'Content-Type: application/json' \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"mode":"oracle","input":{"question":"What am I overlooking?"}}'

The quote returns the fixed $1.00 USD price, expiry, terms version, and secret quote_token. Creating it does not charge anything.

2. Create the Consultation

curl https://churchofyahw.ai/v1/ask \
  -H 'Content-Type: application/json' \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"mode":"oracle","input":{"question":"What am I overlooking?"},"quote_id":"YOUR_QUOTE_ID","quote_token":"YOUR_QUOTE_TOKEN","accepted_terms":"2026-09-16-church"}'

Expect 402 Payment Required. Save request_id and access_token. The optional input.question gives the ritual a focus but does not affect the random selection.

3. Pay the available rail

When bitcoin_lightning_available is true, POST /v1/requests/{id}/lightning with the bearer token. Pay the returned BOLT11 invoice once before expires_at, then POST /v1/requests/{id}/lightning/verify. This endpoint accepts Lightning, not on-chain BTC.

When card_available is true, POST /v1/requests/{id}/checkout and open the returned Stripe URL. Do not assume card checkout is enabled. A request locks to one rail.

4. Retrieve the saved result

curl https://churchofyahw.ai/v1/requests/YOUR_REQUEST_ID \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN'

Poll every three seconds or slower, increase the interval, and stop at completed, failed, expired, or refunded.

{
  "request_id": "req_…",
  "status": "completed",
  "mode": "oracle",
  "result": {
    "reflection": "Every plan rests on something it has not proved.",
    "reflection_id": "ref_assumptions_01",
    "category": "assumptions"
  },
  "meta": {
    "input_analyzed": false,
    "substantive_analysis": false,
    "guaranteed": false
  }
}

The legacy result.reflection field contains the Teaching. reflection_id is its ID and category is its internal theme.

Endpoints

Method	Path	Purpose
GET	/v1/capabilities	Mode, limits, and current rails
GET	/v1/pricing	Price and current availability
POST	/v1/quote	Create a free fixed-price quote
POST	/v1/quotes/{id}/decline	Record an optional private quote decline
POST	/v1/ask	Create a demo or paid Consultation
GET	/v1/requests/{id}	Retrieve private status or result
GET	/v1/requests/{id}/receipt	Retrieve private commercial receipt
POST	/v1/requests/{id}/feedback	Record optional private outcome feedback
POST	/v1/requests/{id}/lightning	Create or refresh a Lightning invoice
POST	/v1/requests/{id}/lightning/verify	Verify Lightning payment
POST	/v1/requests/{id}/checkout	Create or resume card checkout

Safe retries and errors

Idempotency keys are secret creation credentials. Reuse a key only with its identical body. Never put keys or bearer tokens in URLs or public logs. After an uncertain payment response, inspect the existing request before creating another purchase.

Errors contain error.code, error.message, and error.correlation_id. Respect Retry-After on 429 responses. Retry temporary 503 responses with the same key and body.

Retention and help

Question content and Teaching text are available for 90 days. Request IDs alone do not grant access. Contact contact@senna-automation.com with a request ID and correlation ID, never an access token or payment credential.

Terms version: 2026-09-16-church. Terms · Privacy · Refunds.

Optional attribution and private outcomes

At quote creation, metadata.attribution accepts bounded voluntary UTM, integration, task, capability, agent-name, and budget declarations. These are self-reported evidence, never a price, Oracle-selection, identity, or spending-authorization input. Do not send raw referrers, URL queries, or sensitive information.

{"mode":"oracle","input":{},"metadata":{"attribution":{"integration":"agent","external_task_id":"task:planning_42","client_capabilities":["api","autonomous"],"agent_name":"Planning Agent"}}}

A quote owner can record a private voluntary decline with its quote_token; a completed, unexpired request owner can record private feedback with its access_token. Identical retries are safe. To revise a saved signal, include its current version. A settled quote cannot be declined, and no feedback remains unknown rather than negative.

curl https://churchofyahw.ai/v1/quotes/YOUR_QUOTE_ID/decline \
  -X POST -H 'Authorization: Bearer YOUR_QUOTE_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{"reason_code":"timing"}'

curl https://churchofyahw.ai/v1/requests/YOUR_REQUEST_ID/feedback \
  -X POST -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{"retrieval_reported":true,"usefulness":"helpful","task_continuation":"continued","problem_resolution":"unknown"}'