Communio — Intercessory Prayer Network

The Communio engine is the relational heart of the Torch — the write engine through which applications connect intercessors with one another. It manages prayer intentions, sanitizes content before storage, and dispatches webhook notifications to tenant applications when a prayer is answered.

Authentication

All Communio endpoints use the same X-API-Key header as the read engines, but the key is validated against the communio.applications tenant registry rather than the general API key table. A standard API key will not work here.

Browse the Prayer Feed

GET /v1/communio/petitiones

Returns the public feed of active prayer intentions, paginated. Intentions marked is_private by the submitter are excluded.

Query parameters:

Parameter	Type	Default	Description
`page`	`int`	`1`	Page number
`limit`	`int`	`20`	Items per page
`category`	`str`	(optional)	Filter by theological category
`region`	`str`	(optional)	Filter by geographic region

Response: IntentioFeedResponse

{
  "items": [
    {
      "id": "uuid",
      "content_display": "For the healing of my father's illness.",
      "location_region": "Northeast USA",
      "category": "healing",
      "count_prayed": 47,
      "created_at": "2026-03-10T14:23:00Z"
    }
  ],
  "total": 312,
  "page": 1,
  "limit": 20
}

Privacy note: content_display is the sanitized version of the original text. All PII is stripped locally before storage — no text is sent to any external service. The raw content_original and external_user_ref are never returned via any public endpoint.

Get a Single Intention

GET /v1/communio/petitiones/{intention_id}

Path parameters:

intention_id — UUID of the intention

Response: IntentioPublic — single item in the same shape as feed items above.

Submit a Prayer Intention

POST /v1/communio/petitiones

Submits a new prayer intention. The request body must not contain any PII (full name, email, phone, location). The external_user_ref should be an anonymized hash of the user’s identity within your application — never a plaintext identifier.

Request body: IntentioCreate

{
  "external_user_ref": "sha256_of_your_user_id",
  "content_original": "Please pray for my mother who is ill.",
  "location_region": "Midwest USA",
  "category": "healing",
  "is_private": false
}

Field	Type	Constraints
`external_user_ref`	`str`	Anonymized hash. Never store PII here.
`content_original`	`str`	10–1,000 characters
`location_region`	`str?`	High-level region only
`category`	`str?`	Theological category
`is_private`	`bool`	If `true`, excluded from public feed

Pipeline: The submission is screened by a heuristic abuse filter, deduplicated against recent submissions from the same user (24-hour window), passed through a local NLP sanitizer (spaCy), and then stored. The stored record contains only the sanitized content_display text.

Rate limit: 50 submissions per hour per tenant key.

Response: 201 Created — IntentioPublic

Record an Intercession

POST /v1/communio/petitiones/{intention_id}/intercedere

Records that a user in your application has prayed for this intention. Increments the global count_prayed tally and dispatches a webhook to your registered endpoint.

Path parameters:

intention_id — UUID of the intention

Request body: IntercessioCreate

{
  "actor_user_ref": "sha256_of_your_intercessor_user_id"
}

Response: 200 OK

{
  "status": "recorded",
  "count_prayed": 48
}

Webhooks

When an intercession is recorded, the Torch dispatches a POST request to your registered webhook_url with the following payload:

{
  "event": "prayer_recorded",
  "intention_id": "uuid",
  "count_prayed": 48
}

Webhook delivery is best-effort. Your endpoint should respond with 2xx within 5 seconds. Retries are not currently implemented — handle missed events via the feed poll endpoints if strict delivery is required.

IntentioPublic — Full Schema

Field	Type	Notes
`id`	`UUID`	Intention ID
`content_display`	`str`	Sanitized prayer text
`location_region`	`str?`	High-level region
`category`	`str?`	Theological category
`count_prayed`	`int`	Total intercession count
`created_at`	`datetime`	Submission timestamp

N.B. Fields content_original and external_user_ref are never returned by any API response — they exist only in the service layer for processing and are redacted upon storage.