API reference

Scripture

King James Version text, with how often the church has taught each passage.

GET/v1/scripture/lookup

Look up a verse, range or chapter#

Returns the text of a passage and how the church has taught it: how many times, by how many preachers, and the teachings that quote it. ref accepts a verse (John 3:16), a range (Romans 8:28-30) or a whole chapter (Psalm 23).

Folio carries the King James Version only. Omit translation or pass KJV; any other value answers 404.

Auth. A church API key. Needs the scripture:read scope, or a wildcard that includes it (machine:read, machine:*, * on a partner key). A partner key can call it for a customer church by sending X-Folio-Church.

Limits. Responses carry RateLimit-Limit and RateLimit-Remaining; a 429 carries Retry-After.

Auth: Church API key
Scope: scripture:read
Operation id: machineScriptureLookup

Parameters

Parameters
Name	In	Description
`ref` required	query	A verse, range or chapter such as John 3:16, Romans 8:28-30 or Psalm 23. (string, e.g. Romans 8:28)
`translation`	query	Optional. Folio has the King James Version (KJV) only; any other value is not found. (string)
`X-Folio-Church`	header	Partner keys only: run this call as one of your customer churches (its org_ id or slug). The church must be one of yours, the key must be allowed to act for it, and plan checks run against that church. (string, e.g. org_0192f7a8-3b1c-7d2e-9a40-5c6d7e8f9012)

Responses

Response data fields
Field	Type	Description
`book` required	`string`	The book of the Bible.
`chapter` required	`integer (int64)`	The chapter number.
`items` required	`object[]`	The teachings that quote the passage.
`items_truncated` required	`boolean`	Whether the list of teachings was cut short.
`notice` required	`string`	A note about the passage, when there is one.
`object` required	`string`	The object type.
`open_tensions` required	`integer (int64)`	How many unresolved differences between teachings the church has on the passage.
`ref` required	`string`	A scripture reference such as Romans 8:28.
`summaries` required	`object[]`	A summary for each verse.
`taught` required	`object`
`by_year` required	`object[]`	Teachings per year.
`first_year` required	`integer (int64)`	The first year the church taught the passage.
`last_year` required	`integer (int64)`	The latest year the church taught the passage.
`preachers` required	`integer (int64)`	How many different preachers taught it.
`teachings` required	`integer (int64)`	How many teachings quote the passage.
`translation` required	`string`	The translation code. Folio has KJV only.
`verse_end` required	`integer (int64)`	The last verse of the passage.
`verse_start` required	`integer (int64)`	The first verse of the passage.
`verses` required	`object[]`	The verses.
`whole_chapter` required	`boolean`	Whether the reference was a whole chapter.

200 Success. Look up a verse, range or chapter.

200 example

{
  "status": true,
  "message": "passage",
  "data": {
    "object": "passage",
    "ref": "Romans 8:28",
    "book": "Romans",
    "chapter": 8,
    "verse_start": 28,
    "verse_end": 28,
    "whole_chapter": false,
    "translation": "KJV",
    "verses": [
      {
        "n": 28,
        "text": "And we know that all things work together for good to them that love God, to them who are the called according to his purpose.",
        "teachings": 4
      }
    ],
    "taught": {
      "times": 4,
      "preachers": 2,
      "years": 3
    },
    "items": [],
    "items_truncated": false,
    "summaries": [],
    "open_tensions": 0,
    "notice": ""
  }
}

400 The request could not be read.

400 example

{
  "status": false,
  "message": "the page cursor is not valid",
  "error": {
    "code": "invalid_argument",
    "status": 400,
    "request_id": "req_b337770ecebe03b03a88a8998b59263d"
  }
}

401 The key or session is missing, invalid or expired.

401 example

{
  "status": false,
  "message": "That API key is not valid or has expired.",
  "error": {
    "code": "unauthenticated",
    "status": 401,
    "request_id": "req_b337770ecebe03b03a88a8998b59263d"
  }
}

403 The credential lacks the scope, the church is suspended, the feature is not in the plan, or the address is not allowed.

403 example

{
  "status": false,
  "message": "That API key does not have the required scope.",
  "error": {
    "code": "permission_denied",
    "status": 403,
    "request_id": "req_b337770ecebe03b03a88a8998b59263d"
  }
}

404 The reference is not a Bible passage, or the translation is not installed.

404 example

{
  "status": false,
  "message": "That reference or translation was not found.",
  "error": {
    "code": "not_found",
    "status": 404,
    "request_id": "req_b337770ecebe03b03a88a8998b59263d"
  }
}

409 Conflict, including a duplicate Idempotency-Key still being processed.

409 example

{
  "status": false,
  "message": "A request with this Idempotency-Key is still running.",
  "error": {
    "code": "conflict",
    "status": 409,
    "request_id": "req_b337770ecebe03b03a88a8998b59263d"
  }
}

422 A field failed validation, or an Idempotency-Key was reused with a different body.

422 example

{
  "status": false,
  "message": "A field is not valid.",
  "error": {
    "code": "validation",
    "status": 422,
    "request_id": "req_b337770ecebe03b03a88a8998b59263d"
  }
}

429 Rate limited. Wait Retry-After seconds.

429 example

{
  "status": false,
  "message": "Too many requests. Wait before trying again.",
  "error": {
    "code": "rate_limited",
    "status": 429,
    "request_id": "req_b337770ecebe03b03a88a8998b59263d"
  }
}

500 Something went wrong. Quote error.request_id.

500 example

{
  "status": false,
  "message": "Something went wrong. Quote the request id to support.",
  "error": {
    "code": "internal",
    "status": 500,
    "request_id": "req_b337770ecebe03b03a88a8998b59263d"
  }
}

Code samples

curl -X GET "$FOLIO_API_URL/v1/scripture/lookup?ref=Romans+8%3A28" \
  -H "Authorization: Bearer $FOLIO_API_KEY"

GET/v1/scripture/translations

List Bible translations#

Lists the installed translations. Today that is the King James Version only, with its edition, licence and attribution.