Research and reading · Bolls Bible + Quran.com

scripture.search

Full-text search or reference lookup in the Bible or the Quran. Results are verses with translation text; details returns the surrounding chapter.

Operation: POST /v1/capabilities/scripture.search/execute
operationId: executeScriptureSearch
Typical credits: 0
Search deadline: 15 s server-side
Paging: offset
Availability: ConfiguredChecked 2026-09-23 21:02 UTC

Cost basis: Free. Availability is reported per deployment by GET /v1/catalog (available). The timestamped snapshot describes configuration, not provider uptime or your account's enabled choices. Check the catalog with your own key before a call. Credits are explained under credits and limits.

Request

Body of POST /v1/capabilities/scripture.search/execute, JSON, validated against the ScriptureSearchRequest component of the public OpenAPI document. Defaults are applied server-side, so an omitted optional field behaves exactly as its default.

Request fields of scripture.search
Field	Type	Required	Default	Constraints and description
text	"bible" \| "quran"	yes
query	string	no		min length 1, max length 300 Full-text search phrase.
reference	string	no		min length 1, max length 60 Passage reference: "John 3:16-18" for the Bible, "2:255" or "2" for the Quran.
translation	string	no		min length 1, max length 20 Bible: Bolls translation code (default KJV; e.g. YLT, WEB, NIV). Quran: quran.com translation id (default 131, The Clear Quran).
num	integer	no	10	min 1, max 25 Results per page (1-25).

Unknown keys are rejected with 400 invalid_request.

Rules the schema cannot express

Checked after schema validation; violations return 400 invalid_request with a plain message.

Provide query or reference; an empty selector is refused.
An unparseable reference, an unknown book or an unknown Bible translation is refused with a violations[] entry.

Examples

Bible phrase

curl

curl -s -X POST https://api.powerups-ai.store/v1/capabilities/scripture.search/execute \
  -H "Authorization: Bearer $AIPA_API_KEY" -H "Content-Type: application/json" \
  -d '{"text":"bible","query":"love thy neighbour","translation":"KJV"}'

Bible reference

curl

curl -s -X POST https://api.powerups-ai.store/v1/capabilities/scripture.search/execute \
  -H "Authorization: Bearer $AIPA_API_KEY" -H "Content-Type: application/json" \
  -d '{"text":"bible","reference":"John 3:16-18"}'

Quran reference

curl

curl -s -X POST https://api.powerups-ai.store/v1/capabilities/scripture.search/execute \
  -H "Authorization: Bearer $AIPA_API_KEY" -H "Content-Type: application/json" \
  -d '{"text":"quran","reference":"2:255"}'

No recorded response is published for this capability yet. The envelope is the ExecuteResponse component (see sessions and records); the record keys below are what the adapter emits. A first call with the example above returns search_id, the records and the charge.

Result record

Every item in results[] carries record_id and title (contract, always present) and usually url and snippet. The keys below are the documented tier: produced deterministically by this capability, omitted when the source has no value, checked against recorded source fixtures in our test suite, and published as the ScriptureSearchRecord component (all optional, extra keys allowed) so generated clients type them. The wire schema itself still validates only the base keys. See stability tiers.

Record keys of scripture.search
Key	Type	Presence	Note
text	string	always	The verse text in the requested translation.
book	string	always
chapter	integer	always
verse	integer	always
translation	string	always
arabic	string	when the source has it	Quran only.

Follow-ups

Paging: Provider offset; more fetches the next slice from the source. Send { "search_id": "…", "action": "more" } while has_more is true; tolerate an empty page and stop after a bounded number of pages.
Update: Re-run with changed parameters (merged into the stored query); page state resets, search_id stays. Params accept any subset of the request fields (ScriptureSearchUpdateParams).
Record actions:
- details: The whole chapter around the verse.
Detail behaviour: Free provider lookup on first call; repeats are cached. details returns the surrounding chapter from the free source.

record action

curl -s -X POST https://api.powerups-ai.store/v1/follow-up \
  -H "Authorization: Bearer $AIPA_API_KEY" -H "Content-Type: application/json" \
  -d '{"record_id":"rec_…","action":"details"}'

Record detail objects of this capability are provider-shaped: documented by observation, not by schema. Full follow-up semantics: follow-up.

Typed client

With types generated from the public document (see types, client and samples) the call is path-keyed and the body is checked at compile time:

TypeScript (openapi-fetch)

const { data, error } = await client.POST("/v1/capabilities/scripture.search/execute", {
  body: {
    "text": "bible",
    "query": "love thy neighbour",
    "translation": "KJV"
  },
});
if (error) throw new Error(`${error.error.code}: ${error.error.message}`);
for (const record of data.results) console.log(record.record_id, record.title);