API Documentation

Free key on Seeker, the free plan

Use the library from your own apps and AI agents. Browse collections, read books and periodicals in full, search every passage, and search the photos and illustrations.

Use of the API is governed by the API Terms of Use.

Interactive reference OpenAPI specification

API key

Every plan has keys, including Seeker, the free plan. Sign in, open your account page, and create a key.

Create an API key

Send the key with every request, either as an X-Api-Key header or as Authorization: Bearer followed by the key. Requests without a key are refused.

What each plan reaches

The plan of the account your API key belongs to sets what the key reaches and how many calls it makes a day.

API calls a day by plan
Plan	Calls a day	Reaches
Seeker Free	2,000	Search, authors, collections, the Bible, the dictionary, photos and illustrations, and Bible World images.
Believer	5,000	Adds reading works, Bible commentary, music, creating images and character sets.
Disciple	50,000	Everything, with higher limits.
Ambassador	200,000	Everything, with the highest limits.

Calls are counted for the whole account across its keys, and reset at 00:00 UTC. Every REST call counts; on the MCP server every tool call counts.

Believer and up

A key on a lower plan gets a 403 response with the error premium_required and upgradeUrl, a link to the plans. After you upgrade, the same key opens them within a minute.

GET /api/v1/library/search/passages/{id}: Open a search result: its text, the matched words and a link to it in the reader. Also /neighbours and the /blocks routes.
GET /api/v1/library/bible/commentary?reference=&group=: Bible commentary: for each verse of a reference, what Ellen G. White (egw) and the pioneers and periodicals (pioneers) say about it, as Markdown whose every sentence cites the library passages it rests on.
GET /api/v1/library/bible/commentary/groups: The writer groups that write commentary.
GET /api/v1/music/tracks?sort=&artist=: List the songs, by title or newest first, or one artist’s.
GET /api/v1/music/search?q=: Search songs by title, style, Scripture reference, artist or lyrics.
GET /api/v1/music/tracks/{id}: One song: lyrics, references, stream, cover and the files to download.
GET /api/v1/music/tracks/{id}/downloads/{downloadId}: Download one of a song’s files (a link good for 15 minutes).
GET /api/v1/music/albums: The albums, and /albums/{slug} for one album’s songs.
GET /api/v1/music/artists?q=: The artists, with how many songs each has.
POST /api/v1/bibleworld/generations: Create a Bible World image on your image credits.
GET /api/v1/bibleworld/character-sets: Your Bible World character sets.

In the MCP server: open_passage, read_around_passage, read_blocks, bible_commentary, generate_image, list_character_sets, get_character_set and the music tools. Their descriptions start with Believer and up.

Example:

curl -H "X-Api-Key: YOUR_API_KEY" "https://api.adventai.app/api/v1/library/bible/commentary?reference=Daniel%208:14"

See the plans

Set up an AI agent

Copy these instructions and paste them into your AI agent, replacing YOUR_API_KEY with your key. They explain how to connect and how to search and read the library.

# Advent AI Library — agent setup

You have read-only access to the Advent AI library: books and periodicals, readable in full and searchable by passage. What the key reaches follows its owner's plan: every plan, including Seeker (free), has search, authors, the Bible, the dictionary, the library's photos and illustrations and Bible World images; Believer and up adds reading works, Bible commentary, music, creating images and character sets.

Replace YOUR_API_KEY with a key from https://beta.adventai.app/account/library-api (sign in, then create a key).

API key: YOUR_API_KEY

## Preferred: MCP server

Add this MCP server (streamable HTTP):

```json
{
  "mcpServers": {
    "advent-ai-library": {
      "type": "http",
      "url": "https://api.adventai.app/mcp",
      "headers": { "Authorization": "Bearer YOUR_API_KEY" }
    }
  }
}
```

Claude Code: `claude mcp add --transport http advent-ai-library https://api.adventai.app/mcp --header "Authorization: Bearer YOUR_API_KEY"`

Tools: search_library, search_publications, count_matches, open_passage, read_around_passage, find_authors, get_author, get_author_works, browse_works, get_timeline, list_collections, get_collection, get_collection_authors, get_book, get_periodical, get_contents, read_blocks, resolve_work, get_library_stats, get_search_syntax, search_library_images, get_library_image.

The same server and key also open Bible World's Bible images: search_images, bible_passage_images, search_characters, get_character, and generate_image (which spends the key owner's image credits; get_credits shows the balance and where to buy more). Setup for those: https://bibleworld.ai/api

Believer and up (any other key gets premium_required with upgradeUrl — give the person that link):
- Reading works: open_passage, read_around_passage, read_blocks.
- bible_commentary: for each verse of a reference, what Ellen G. White and the pioneers and periodicals say about it, every sentence citing its passages.
- Music: search_music, list_music, get_music_track, get_music_download_links, list_music_albums, get_music_album, list_music_artists.
- generate_image (Bible World), which also spends image credits, and list_character_sets, get_character_set.

## Alternative: REST API

Base URL: https://api.adventai.app/api/v1/library
Send the key on every request: `X-Api-Key: YOUR_API_KEY`
OpenAPI spec: https://api.adventai.app/api/v1/openapi.json
Search syntax: https://api.adventai.app/api/v1/library/search/syntax
Photos and illustrations (every plan): https://api.adventai.app/api/v1/library/images/search?q= and /images/{id}
Believer and up: reading (/search/passages/{id}, /neighbours, /blocks), Bible commentary at https://api.adventai.app/api/v1/library/bible/commentary?reference=, music at https://api.adventai.app/api/v1/music

## How to work with it

1. Call get_search_syntax (or GET /search/syntax) once before writing complex queries. Operators must be in CAPITALS: AND, OR, NOT, NEAR/n, BEFORE/n, "exact phrase", wildcards (work*), word families (go%), synonyms (love$).
2. Use count_matches to refine a query cheaply, then search_library for ranked passages.
3. Open a hit with open_passage and read around it with read_around_passage or read_blocks (Believer and up; on Seeker, the free plan, cite the hit's work and snippet).
4. For a period, use get_timeline to see where the material is, browse_works to list works by date, and dateFrom/dateTo (YYYY, YYYY-MM or YYYY-MM-DD) on any search; search_library can sort by date (sort=oldest or newest).
5. For questions about a person, use find_authors and get_author, then pass authorId to the search tools to search only their writing, or list their works with get_author_works.
6. Cite works by title and author, and link to https://beta.adventai.app/library/book/{uniqueId} or https://beta.adventai.app/library/periodical/{uniqueId}.
7. For pictures printed in the library (photographs, engravings, maps, charts and more), use search_library_images: the same query language over each picture's caption and what is in it, filtered by type, orientation, book or periodical, collection and date. Open one with get_library_image and give the person its pageUrl.

## Terms and limits

Use of the API is governed by the API Terms of Use: https://beta.adventai.app/library/api/terms

Calls a day, for the whole account across its keys: Seeker (free) 2,000, Believer 5,000, Disciple 50,000, Ambassador 200,000 (every REST call and every MCP tool call). Past that, calls answer daily_limit_reached with resetsAt (00:00 UTC) and upgradeUrl.
Per account: reads burst to 120 then 2 per second; searches burst to 30 then 1 every 2 seconds (Disciple twice that, Ambassador four times); 8 at once. On HTTP 429 rate_limited, wait the Retry-After seconds. Do not bulk-download the library.

MCP server

Agents that support the Model Context Protocol can connect directly. Add this server address to your agent or app, with your API key as a Bearer token:

https://api.adventai.app/mcp

In Claude Code, run:

claude mcp add --transport http advent-ai-library https://api.adventai.app/mcp --header "Authorization: Bearer YOUR_API_KEY"

The server offers tools to search, open passages, find authors and their works, browse collections and read works, plus a guide to the search language.

search_library_images and get_library_image find and open the photos and illustrations printed in the library, on every plan.

The same server and key also open Bible World: search its Bible images, use its character library and create new images on your image credits. Bible World API

Tools for Believer and up answer premium_required to keys on a lower plan.

REST endpoints

All endpoints use GET and return JSON. The base address is:

https://api.adventai.app/api/v1/library

/stats: Library size and publication date range.
/collections: The tree of collections.
/collections/{id}/works?offset=&limit=&sort=: Page through the works in a collection.
/collections/{id}/authors: The authors in a collection, most works first.
/authors?q=&sort=: Find authors by name, with their book and article counts.
/authors/{idOrSlug}: One author: biography, counts, first and last publication dates, and collections.
/authors/{id}/works?kind=&sort=: Page through an author’s books and articles.
/works?kind=&authorId=&collectionId=&dateFrom=&dateTo=&sort=: Browse published books, editions and articles by date range, kind, author and collection.
/timeline?authorId=&collectionId=: How many works were published each year.
/books/{uniqueId}: A book’s details and chapter outline.
/books/{uniqueId}/contents: A book’s blocks in reading order.
/books/{uniqueId}/blocks?from=&count=: Believer and up: read up to 200 blocks of a book’s text.
/periodicals/{uniqueId}: A periodical edition and its articles.
/periodicals/{uniqueId}/blocks?from=&count=: Believer and up: read an edition’s text.
/articles/{articleId}/blocks?from=&count=: Believer and up: read one article’s text.
/search?q=&authorId=&dateFrom=&dateTo=&sort=: Passage search by relevance or date, with filters for author, collections, a single work and publication dates (YYYY, YYYY-MM or YYYY-MM-DD).
/search/publications?q=: Search results grouped by book or edition.
/search/count?q=: How many passages match, without the results.
/search/passages/{id}?q=: Believer and up: open one result with its text and matched words.
/search/passages/{id}/neighbours: Believer and up: the passages before and after a result.
/images/search?q=&types=&orientations=&kind=&dateFrom=&dateTo=&sort=: Search the photos and illustrations by caption and by what is in them, with the same search language. Filter by type, shape, book or periodical, collection and publication date.
/images/{id}: One picture: its links, date, type, description, keywords, people, places, Bible passages and a link to it in the reader.

Example:

curl -H "X-Api-Key: YOUR_API_KEY" "https://api.adventai.app/api/v1/library/search?q=sabbath%20NEAR/5%20rest&limit=5"

Search language

Searches support phrases, AND, OR, NOT, proximity such as NEAR/5 and BEFORE/10, wildcards, word families and synonyms. Operators must be written in capitals.

Read the full search guide

Fair use

Calls a day follow your plan, for the whole account. Past them the response is 429 with the error daily_limit_reached and resetsAt. Each response carries X-Daily-Limit and X-Daily-Remaining.

Rates are per account: bursts of 120 reads and 30 searches, refilling 2 reads a second and a search every 2 seconds (Disciple twice that, Ambassador four times), and 8 at a time. Over a rate the response is 429 with a Retry-After header. Please cache responses and do not bulk-download the library.