Reference / API v1

A small, explicit API.

Base URL: https://churchofyahw.ai. All API responses are UTF-8 JSON. The OpenAPI 3.1 specification describes the public contract.

An Oracle Consultation returns one random Teaching from the Canon. Existing API names stay compatible: request_id identifies the Consultation or sample; result.reflection, reflection_id, and category describe its Teaching. A free demo samples the Canon. No Offering or membership endpoint is currently available.

Endpoints

Method	Path	Purpose
GET	/v1/capabilities	Public discovery
GET	/v1/pricing	Current price and availability
POST	/v1/quote	Persist a free fixed-price quote
POST	/v1/ask	Create a Canon sample or paid Oracle Consultation
GET	/v1/requests/{id}	Retrieve private status/result
POST	/v1/requests/{id}/lightning	Obtain/refresh a Bitcoin Lightning invoice
POST	/v1/requests/{id}/lightning/verify	Refresh verified Bitcoin payment status
POST	/v1/requests/{id}/checkout	Create or resume hosted checkout

1. Get a 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 contains integer amount_cents, decimal-string amount, currency: "USD", expiry, description, terms version, and a secret quote_token. Quotes default to one hour and are free. A price change never alters an existing quote.

2. Create the request

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"}'

A paid request normally returns 402 Payment Required, with the request ID, bearer token, quote, and checkout endpoint. You may omit both quote fields to create a request with a fresh quote in one step. Input may be any JSON value; the optional question lives under input.question. Additional context, instructions, and metadata are stored but not analyzed. Quote matching includes these fields.

Supported metadata labels include source and agent_name; use non-sensitive values. Maximum request body: 16 KiB, nesting: 20 levels. Unsupported modes return 422. Caller-supplied prices never override the stored price.

3. Pay Bitcoin over Lightning

POST /v1/requests/{id}/lightning with your bearer token. The JSON response contains bolt11, amount_sats, network, and expires_at. A satoshi is one hundred-millionth of a bitcoin. Have your authorized, funded Lightning wallet pay the invoice once. The commercial price is in USD; the provider supplies the exact BTC amount and a short expiry. POST /v1/requests/{id}/lightning/verify to refresh server-verified payment state, no faster than every 5 seconds. GET the request to retrieve its saved result.

There is no shared deposit address and no card form in this flow. A normal on-chain BTC transfer cannot pay a Lightning invoice. The payer must already have a compatible wallet, funds, and spending authorization. The service never receives a wallet seed or sending credential. Do not ask a human to visit checkout if your wallet can pay directly.

If the BTC quote expires before sending, call the invoice endpoint again under the same request. If sending times out, first inspect your wallet and the existing request; creating another request could cause a second purchase. Each request locks to one payment method. A client-provided transaction ID, payment preimage, screenshot, or redirect is not accepted as payment proof.

Optional: card checkout

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

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

Checkout is one-time, card-only, provider-hosted, and may require a human. No card data is sent to this API. Checkout lasts one hour from initiation. Repeated checkout calls reuse the same session. If a request or checkout expires, inspect its status before deliberately creating another purchase.

{
  "request_id": "req_…",
  "status": "completed",
  "mode": "oracle",
  "result": {
    "reflection": "Which assumption is carrying the most weight?",
    "reflection_id": "ref_assumptions_01",
    "category": "assumptions"
  },
  "meta": {
    "input_analyzed": false,
    "substantive_analysis": false,
    "guaranteed": false
  }
}

States and recovery

payment_required → payment_processing / paid → completed. Other states: failed, expired, refunded. Payment is verified server-side. Failed paid fulfillment is retried automatically or refunded by support. The original purchased result remains unchanged across retries and Canon edits.

Poll every 3 seconds or slower, increase the interval, and stop at completed, failed, expired, or refunded. Retrieval is private and never shared through caches. After 90 days, status/transaction metadata can remain but content_expired: true and result: null indicate the retention window ended.

Errors and safe retries

Errors contain error.code, error.message, and error.correlation_id. Include the correlation ID when contacting support, but never the bearer token.

400: malformed JSON or missing/invalid idempotency key.
404: unknown route, request, or invalid bearer token.
409: changed retry body, changed/expired quote, quote already used, or closed checkout.
413 / 415 / 422: oversized body, wrong content type, or invalid input.
429: rate limit; honor Retry-After.
503: provider, storage, or service temporarily unavailable; retry with the same key.

Creation is limited to 20 requests/minute and reads to 120/minute per IP per Cloudflare location. These are abuse controls, not guaranteed global quotas. Public capability/pricing responses may be cached for 30 seconds; quotes always use authoritative configuration.

Versioning and help

API version v1; terms version 2026-09-16-church. Accept additive response fields. Contact support with the request ID and describe the issue. Terms · Privacy · Refunds.