Developer Tools: API

This documentation describes version 1 of the API, which is deprecated. You probably want version 2 instead. If you're still using version 1, you must migrate before July 1, 2013.

Application Programming Interface (API)


The ABS Bible Search API is available via XML or JSON requests served over HTTP using RESTful resources. Accessing Bible passages via the API is a read-only process; you may access this content via HTTP GET requests. To interact with user-specific features like accounts, tags, and notes, you may read and write to the API using all four HTTP verbs (GET/POST/PUT/DELETE).

Because the ABS Bible Search API is accessible via HTTP, you may use a regular browser to view all GET requests for the API. If you are using the XML interface, we recommend using Mozilla Firefox or Google Chrome for this, since they will happily render XML in the browser. JSON responses can also be viewed in the browser, but they are harder to read without formatting. For many URLs in the ABS Bible Search application, you may simply append .xml or .js to the URL to retrieve the corresponding API response for that URL. For example, /GNT/Gen/1 becomes /GNT/Gen/1.xml to retrieve the XML version or /GNT/Gen/1.js to retrieve the JSON version.


All requests to the ABS API are authenticated via an existing ABS user account – you do not need a special API user account to access the API. All users have full read access to all Bible passages. For user-specific content such as account information, tags, and notes, users have full read and write access, but only to their own content.

API Authentication is done via an authentication token. If you do not have an API auth token already, please see the "How do I get access?" section of the Developer Tools: API page. Every request must include your API key. If necessary for your development environment, you may pass a dummy password along with your request.

Here is an example of how to use Curl to access our API. (The dummy password “X” is being passed with this request.)

curl -u #{your API token}:X -k

Remember to keep your authentication token private. Anything you can do via the website you can do via the API, so protect your API token as you would protect your username and password for the website. If you ever want to change your API token, simply change your account password via the account settings page, and your API token will be changed as well.


Each request to the API can be made with or without a version number. If no version is specified, the current default API version will be used for the response.

The current default API version is version 1.

The version is specified with a /vX/ URL segment at the beginning of any URL. For example, this URL uses the default version:

And this URL uses version 2:

If a version is specified that is out of range (either too high or too low), it will be clamped to the closest valid version.

Making Secure (SSL) Requests

Because every request sends along your authentication token, it is in your best interest to always make secure API requests to keep your token safe. This means using SSL by specifying 'https' as the protocol for your URLs instead of 'http'. You'll notice that all our examples have URLs beginning with ''. Access via non-SSL URLs still works, but is deprecated and not recommended.

Reading (HTTP GET requests)

There are two categories of actions used to read data from the ABS API: list and show. List actions return a collection of records (such as all versions of the Bibles ABS provides) and may sometimes be filtered by certain criteria described in this documentation. Each resource typically offers a single show action to return data about that individual resource (a particular book of a particular Bible version, for example). If a resource has a parent resource (a Version is the parent of a Book, for example), the child resource includes a parent node linking to the canonical URL of its parent. If a resource has sibling resources (e.g. next and previous chapters, if the resource is a Chapter), the resource will include next and previous nodes. A resource may have a next node, a previous node, or both. Sibling resources roll over to the siblings of parents and grandparents if necessary. For example, if a resource is the last chapter in a book, the next node will contain information about the first chapter in the next book.

You may access all list and show actions via GET requests. These are easily performed via either the browser or via command line:

Browser (load this URL in FireFox):

https://#{your API token}

Command line (using curl):

curl -u #{your API token}:X -k

If the read request is successful, the XML response will include the status code “200 OK.”

Note: Bible passages are only available via read requests. Write access is not available for Bible passages.

Searching (HTTP GET requests)

Fully automatic searches, where a general query is used and the site figures out the contents of the query, can be done via the search.xml endpoint. If the query looks like a passage search, the endpoint will redirect to the appropriate passage search url. If the query looks like a keyword search, the endpoint will redirect to the appropriate verse keyword search url.

Additionally, the user can specify that a search should only be considered a keyword search via a particular request to the Verses resources.

Writing (HTTP POST and PUT requests)

You may use the ABS API to create and update content that you, yourself, have created. This includes account information, tags, and notes. To perform these write requests, you will need to send an XML or JSON request to the ABS API along with the relevant HTTP verb for your action. Because of these requirements, it is not easy to interact with the ABS API using your browser to send these write requests. Instead, we recommend you use a command line tool like curl to play around with this portion of the ABS API interface.

To create new resources via the ABS API, send the resource encoded as XML or JSON. Be sure to also send the correct Content-type header with your request. This will be either “Content-type: application/xml” for XML requests or “Content-type: application/javascript” for JSON requests. Data should be sent to the ABS API as the raw POST or PUT body.


To create a new tag via the ABS API XML interface, do this (JSON examples are available on the complete documentation page for each endpoint):

curl -u #{your API token}:X -k -X POST -H 'Content-Type: application/xml' \
-d '<tagging><tag><name>peace</name></tag><references><reference><start>GNT:John.3.18</start><end>GNT:John.3.18</end></reference></references></tagging>' \

Successful creations respond with the status code “201 Created.” The response will also include the URL of the resource in the location header and the complete resource, formatted as XML. It’s helpful to use the returned resources attributes (especially the id attribute) to interact with the resource in subsequent requests.

You may update resources you have created by performing an HTTP PUT request. The resource attributes you pass with the request (as XML) will replace the attributes on file for that resource.

A sample tag update request:

curl -u #{your API token}:X -k -X PUT -H 'Content-Type: application/xml' \
-d '<tagging><tag><name>peace</name></tag></tagging>'

Successful update requests return the response code “200 OK.”


Error responses from the server will return a response code in the range 400-499. When appropriate, error responses will contain error messages formatted in either XML or JSON (depending on the requested content type) to explain what caused the error.

Deleting (HTTP DELETE requests)

You may delete content that you, yourself, have created by sending an HTTP DELETE request (in this example, to delete a tag):

curl -u #{your API TOKEN}:X -k -X DELETE

Note: The content-type header is not needed for DELETE requests, since you are not sending any XML to the ABS API.

Successful update requests return the response code “200 OK” and the updated object in the response body.

Successful delete requests return the response code “200 OK” and an empty response body.

Response codes

Successful requests

Successful requests will return HTTP response codes in the 200s.

Record selected, updated, or deleted
HTTP/1.1 200 OK
Record created
HTTP/1.1 201 Created

Unsuccessful requests

Unsuccessful requests will return HTTP response codes in the 400s.

Malformed request

If you submit poorly formed XML or JSON to the API, you will receive this response.

HTTP/1.1 400 Bad Request
Authentication credentials needed
HTTP/1.1 401 Unauthorized
Non-existent route or resource
HTTP/1.1 404 Not Found
Invalid data

When you try to create or update a record with invalid data, you will receive this response.

HTTP/1.1 422 Unprocessable Entity

API conventions

Throughout this documentation, the following conventions are in use:

  • #{text}: Indicates that this text should be replaced by your own data.
  • …: Indicates that a portion of the response has been omitted for brevity and clarity’s sake.
  • Green boxes: indicate that the contained text is part of the request portion of an example.
  • Orange boxes: indicate that the contained text is part of the response portion of an example.