Developer docs

Search

Keyword and semantic search over all public knowledge assets. Backed by Cloudflare Vectorize with Magisterium-enriched embeddings.

curl "https://humagnify.ai/api/assets/search?q=eucharist&type=prayer"

{
  "results": [
    {
      "id": "...",           // stable asset UUID — use this to fetch full content
      "type": "prayer",      // content type: study | reflection | guide | prayer | video | …
      "title": "Saint Thomas Aquinas Prayer After Communion",
      "topics": ["Eucharist", "thanksgiving"],  // tags extracted from content
      "isFree": true,        // false = paid via x402 (coming soon)
      "score": 0.733,        // cosine similarity 0–1; results below ~0.45 are filtered out
      "url": "https://humagnify.ai/prayer/...",   // human-readable page
      "api": "https://humagnify.ai/api/assets/..." // fetch full content or snippet from here
    }
  ],
  "semantic": true,          // true = vector search was used; false = keyword fallback
  "count": 1,
  "total": 1
}

Asset snippet

Structured summary of a single asset — optimized for agent consumption. Includes full content, related products, and payment details for paid assets.

curl "https://humagnify.ai/api/assets/{id}/snippet"

// Response
{
  "id": "...",              // stable asset UUID
  "type": "prayer",         // content type
  "title": "...",
  "topics": [...],          // tags extracted from content
  "language": "en",
  "isFree": true,           // false = paid via x402 (coming soon)
  "price": null,            // null if free; { amount, currency, protocol, network } if paid
  "reviewScore": 0.91,      // 0–1 quality score from automated content review
  "useCount": 42,           // number of times this asset has been accessed
  "occurredAt": null,       // ISO date the event/homily/pilgrimage took place (if applicable)
  "author": { "handle": "carloprayforus", "displayName": "Carlo" }, // null if no author profile
  "publication": { "slug": "crosslinkedword", "name": "CrosslinkedWord" }, // null for personal publications
  "relatedItems": [         // Catholic products from merchants relevant to this content
    {
      "id": "...",
      "title": "...",
      "brand": "The Catholic Company",
      "price": { "amount": 14.99, "currency": "USD" },
      "isFree": false,
      "url": "https://catholiccompany.com/...",
      "isSponsored": false
    }
  ]
}

Product discovery

Natural language product search across Catholic merchants. Humagnify is an aggregator — results link directly to merchant sites, enriched with knowledge graph entities and content.

curl -X POST "https://humagnify.ai/api/products/find" \
  -H "Content-Type: application/json" \
  -d '{ "intent": "rosary beads under $20 for a child" }'

// Response includes matched products enriched with
// relatedAssets (Humagnify content) and relatedEntities (knowledge graph).

Example intents:

• retreat houses in the midwest for men
• pilgrimage to Fatima departing from the east coast
• Catholic books for a teenager's confirmation gift

Entity graph

Every asset is tagged with real-world entities extracted at publish time — people, places, organizations, events, and more. Entity type is an open string (not a fixed enum) so the graph grows as new entity classes emerge from the content.

curl "https://humagnify.ai/api/entities?type=person&q=aquinas"

// Response
{
  "entities": [
    {
      "id": "...",
      "type": "person",           // open string — any type the classify model extracts
      "name": "Thomas Aquinas",
      "meta": { "bioUrl": "..." }, // type-specific: person→{bioUrl, personRole}, location→{city, state, country}, …
      "canonicalId": null,         // future: Wikidata QID, Catholic Encyclopedia slug
      "_count": { "assets": 8 }   // public assets linked to this entity
    }
  ],
  "count": 1
}

// Related entities (graph traversal)
curl "https://humagnify.ai/api/entities/{id}/related"

{
  "entity": { "id": "...", "type": "person", "name": "Thomas Aquinas" },
  "related": [
    { "id": "...", "type": "doctrine", "name": "Summa Theologica", "sharedAssets": 4 },
    { "id": "...", "type": "feast_day", "name": "Feast of St. Thomas Aquinas", "sharedAssets": 2 }
  ]
}

Asset snippet responses include the full entity list for that asset. Use entity IDs to traverse the graph without re-querying the search index.

Browse feed

Paginated JSON feed for agents that want to index or browse all content without targeted search. Supports cross-references, filtering, and pagination.