Developer Tools: API

This documentation describes version 1 of the API, which is deprecated. The functionality on this page has been removed in version 2 of the API.

Application Programming Interface (API)

Taggings

Taggings associate tags with verses and are owned by users.

Note: You may only view or manipulate your own taggings.

List

GET /user/taggings.xml

Returns all of your taggings. All of your tags and tagged verse references are included in the output of this request.

Example:

Request
XML
JSON
GET https://cy.bibles.org/user/taggings.xml
Response
<?xml version="1.0" encoding="utf-8"?>
        <taggings>
          <tagging id="702">
            <id>702</id>
            <user_id>1470</user_id>
            <tag_id>259</tag_id>
            <updated_at>Mon, 01 Nov 2010 15:04:53 -0500</updated_at>
            <created_at>Mon, 01 Nov 2010 15:04:53 -0500</created_at>
            <references>
              <reference>
                <start>GNT:John.8.11</start>
                <end>GNT:John.8.11</end>
                <created_at>Wed, 30 Nov -001 00:00:00 -0600</created_at>
                <updated_at>Wed, 30 Nov -001 00:00:00 -0600</updated_at>
              </reference>
            </references>
            <tag id="259">
              <id>259</id>
              <name><![CDATA[judgment]]></name>
            </tag>
          </tagging>
          <tagging id="709">
            <id>709</id>
            <user_id>1470</user_id>
            <tag_id>31</tag_id>
            <updated_at>Thu, 03 Mar 2011 17:32:37 -0600</updated_at>
            <created_at>Thu, 03 Mar 2011 17:32:37 -0600</created_at>
            <references>
              <reference>
                <start>GNT:John.8.4</start>
                <end>GNT:John.8.4</end>
                <created_at>Wed, 30 Nov -001 00:00:00 -0600</created_at>
                <updated_at>Mon, 21 May 2012 13:37:26 -0500</updated_at>
              </reference>
            </references>
            <tag id="31">
              <id>31</id>
              <name><![CDATA[peace]]></name>
            </tag>
          </tagging>
          <meta>
            <fums><![CDATA[<script>
        var _BAPI=_BAPI||{};
        if(typeof(_BAPI.t)==='undefined'){
        document.write('\x3Cscript src="'+document.location.protocol+'//d2ue49q0mum86x.cloudfront.net/include/fums.c.js"\x3E\x3C/script\x3E');}
        document.write("\x3Cscript\x3E_BAPI.t('5050d623401a37.06608516');\x3C/script\x3E");
        </script><noscript><img src="https://d3a2okcloueqyx.cloudfront.net/nf1?t=5050d623401a37.06608516" height="1" width="1" border="0" alt="" style="height: 0; width: 0;" /></noscript>]]></fums>
            <fums_tid>5050d623401a37.06608516</fums_tid>
            <fums_js_include>d2ue49q0mum86x.cloudfront.net/include/fums.c.js</fums_js_include>
            <fums_js><![CDATA[var _BAPI=_BAPI||{};if(typeof(_BAPI.t)!='undefined'){ _BAPI.t('5050d623401a37.06608516'); }]]></fums_js>
            <fums_noscript><![CDATA[<img src="https://d3a2okcloueqyx.cloudfront.net/nf1?t=5050d623401a37.06608516" height="1" width="1" border="0" alt="" style="height: 0; width: 0;" />]]></fums_noscript>
          </meta>
        </taggings>

GET /user/taggings/#{tag_name}.xml

Returns all of your taggings for the specified tag. The specified tag and all verse references you have tagged with it are included in the output of this request. Make sure you properly URL encode the tag name in the URL used for this request.

Example:

Request
XML
JSON
GET https://cy.bibles.org/user/taggings/peace.xml
Response
<?xml version="1.0" encoding="utf-8"?>
        <taggings>
          <tagging id="709">
            <id>709</id>
            <user_id>1470</user_id>
            <tag_id>31</tag_id>
            <updated_at>Thu, 03 Mar 2011 17:32:37 -0600</updated_at>
            <created_at>Thu, 03 Mar 2011 17:32:37 -0600</created_at>
            <references>
              <reference>
                <start>GNT:John.8.4</start>
                <end>GNT:John.8.4</end>
                <created_at>Wed, 30 Nov -001 00:00:00 -0600</created_at>
                <updated_at>Mon, 21 May 2012 13:37:26 -0500</updated_at>
              </reference>
            </references>
            <tag id="31">
              <id>31</id>
              <name><![CDATA[peace]]></name>
            </tag>
          </tagging>
          <meta>
            <fums><![CDATA[<script>
        var _BAPI=_BAPI||{};
        if(typeof(_BAPI.t)==='undefined'){
        document.write('\x3Cscript src="'+document.location.protocol+'//d2ue49q0mum86x.cloudfront.net/include/fums.c.js"\x3E\x3C/script\x3E');}
        document.write("\x3Cscript\x3E_BAPI.t('5050d687604830.91924572');\x3C/script\x3E");
        </script><noscript><img src="https://d3a2okcloueqyx.cloudfront.net/nf1?t=5050d687604830.91924572" height="1" width="1" border="0" alt="" style="height: 0; width: 0;" /></noscript>]]></fums>
            <fums_tid>5050d687604830.91924572</fums_tid>
            <fums_js_include>d2ue49q0mum86x.cloudfront.net/include/fums.c.js</fums_js_include>
            <fums_js><![CDATA[var _BAPI=_BAPI||{};if(typeof(_BAPI.t)!='undefined'){ _BAPI.t('5050d687604830.91924572'); }]]></fums_js>
            <fums_noscript><![CDATA[<img src="https://d3a2okcloueqyx.cloudfront.net/nf1?t=5050d687604830.91924572" height="1" width="1" border="0" alt="" style="height: 0; width: 0;" />]]></fums_noscript>
          </meta>
        </taggings>

Show

GET /taggings/#{tagging_id}.xml

Returns the tagging with the specified tagging ID. The tagging ID is a number and is returned when a tagging is listed. The associated tag and all of its verse references are included in the output of this request.

Example:

Request
XML
JSON
GET https://cy.bibles.org/taggings/709.xml
Response
<?xml version="1.0" encoding="utf-8"?>
        <taggings>
          <tagging id="709">
            <id>709</id>
            <user_id>1470</user_id>
            <tag_id>31</tag_id>
            <updated_at>Thu, 03 Mar 2011 17:32:37 -0600</updated_at>
            <created_at>Thu, 03 Mar 2011 17:32:37 -0600</created_at>
            <references>
              <reference>
                <start>GNT:John.8.4</start>
                <end>GNT:John.8.4</end>
                <created_at>Wed, 30 Nov -001 00:00:00 -0600</created_at>
                <updated_at>Mon, 21 May 2012 13:37:26 -0500</updated_at>
              </reference>
            </references>
            <tag id="31">
              <id>31</id>
              <name><![CDATA[peace]]></name>
            </tag>
          </tagging>
          <meta>
            <fums><![CDATA[<script>
        var _BAPI=_BAPI||{};
        if(typeof(_BAPI.t)==='undefined'){
        document.write('\x3Cscript src="'+document.location.protocol+'//d2ue49q0mum86x.cloudfront.net/include/fums.c.js"\x3E\x3C/script\x3E');}
        document.write("\x3Cscript\x3E_BAPI.t('5050d6f41a4e63.37598523');\x3C/script\x3E");
        </script><noscript><img src="https://d3a2okcloueqyx.cloudfront.net/nf1?t=5050d6f41a4e63.37598523" height="1" width="1" border="0" alt="" style="height: 0; width: 0;" /></noscript>]]></fums>
            <fums_tid>5050d6f41a4e63.37598523</fums_tid>
            <fums_js_include>d2ue49q0mum86x.cloudfront.net/include/fums.c.js</fums_js_include>
            <fums_js><![CDATA[var _BAPI=_BAPI||{};if(typeof(_BAPI.t)!='undefined'){ _BAPI.t('5050d6f41a4e63.37598523'); }]]></fums_js>
            <fums_noscript><![CDATA[<img src="https://d3a2okcloueqyx.cloudfront.net/nf1?t=5050d6f41a4e63.37598523" height="1" width="1" border="0" alt="" style="height: 0; width: 0;" />]]></fums_noscript>
          </meta>
        </taggings>

Create

POST /user/taggings.xml

Creates a tagging resource for the tag and verse reference you pass to it in the body of your XML request. You must pass either the tag name node or id node with your request.

The verse reference must have both a start and an end node, each representing a verse id marking the start and end of the passage you would like to tag. To tag a single verse, submit the same verse id as both the start and end values.

Example:

Request
XML
JSON
POST https://cy.bibles.org/user/taggings.xml
Content-Type
application/xml
Body
<tagging>
  <tag>
    <name>peace</name>
  </tag>      
  <references>
    <reference>
      <start>GNT:John.3.18</start>
      <end>GNT:John.3.18</end>
    </reference>
  </references>
</tagging>
Response
<?xml version="1.0" encoding="utf-8"?>
<taggings>
  <tagging id="739">
    <id>739</id>
    <user_id>1470</user_id>
    <tag_id>31</tag_id>
    <updated_at>Wed, 12 Sep 2012 15:25:01 -0500</updated_at>
    <created_at>Wed, 12 Sep 2012 15:25:01 -0500</created_at>
    <references>
      <reference>
        <start>GNT:John.3.18</start>
        <end>GNT:John.3.18</end>
        <created_at>Wed, 12 Sep 2012 15:25:01 -0500</created_at>
        <updated_at>Wed, 12 Sep 2012 15:25:01 -0500</updated_at>
      </reference>
    </references>
    <tag id="31">
      <id>31</id>
      <name><![CDATA[peace]]></name>
    </tag>
  </tagging>
  <meta>
    <fums><![CDATA[<script>
var _BAPI=_BAPI||{};
if(typeof(_BAPI.t)==='undefined'){
document.write('\x3Cscript src="'+document.location.protocol+'//d2ue49q0mum86x.cloudfront.net/include/fums.c.js"\x3E\x3C/script\x3E');}
document.write("\x3Cscript\x3E_BAPI.t('5050ef9d0c5860.71598740');\x3C/script\x3E");
</script><noscript><img src="https://d3a2okcloueqyx.cloudfront.net/nf1?t=5050ef9d0c5860.71598740" height="1" width="1" border="0" alt="" style="height: 0; width: 0;" /></noscript>]]></fums>
    <fums_tid>5050ef9d0c5860.71598740</fums_tid>
    <fums_js_include>d2ue49q0mum86x.cloudfront.net/include/fums.c.js</fums_js_include>
    <fums_js><![CDATA[var _BAPI=_BAPI||{};if(typeof(_BAPI.t)!='undefined'){ _BAPI.t('5050ef9d0c5860.71598740'); }]]></fums_js>
    <fums_noscript><![CDATA[<img src="https://d3a2okcloueqyx.cloudfront.net/nf1?t=5050ef9d0c5860.71598740" height="1" width="1" border="0" alt="" style="height: 0; width: 0;" />]]></fums_noscript>
  </meta>
</taggings>

Update

PUT /taggings/#{tagging_id}.xml

Modifies a tagging resource identified by the given ID, with the tag and verse reference you pass to it in the body of your XML request. You may pass either the tag name node or id node with your request to update the tag used for the tagging.

The verse reference must have both a start and an end node, each representing a verse id marking the start and end of the passage you would like to tag. To tag a single verse, submit the same verse id as both the start and end values.

Example:

Request
XML
JSON
PUT https://cy.bibles.org/taggings/739.xml
Content-Type
application/xml
Body
<tagging>
  <tag>
    <name>peace</name> <!-- optional -->
  </tag>      
  <references>
    <reference>
      <start>GNT:Acts.8.34</start>
      <end>GNT:Acts.8.36</end>
    </reference>
  </references>
</tagging>
Response
<?xml version="1.0" encoding="utf-8"?>
<taggings>
  <tagging id="739">
    <id>739</id>
    <user_id>1470</user_id>
    <tag_id>31</tag_id>
    <updated_at>Wed, 12 Sep 2012 15:36:37 -0500</updated_at>
    <created_at>Wed, 12 Sep 2012 15:25:01 -0500</created_at>
    <references>
      <reference>
        <start>GNT:Acts.8.34</start>
        <end>GNT:Acts.8.36</end>
        <created_at>Wed, 12 Sep 2012 15:25:01 -0500</created_at>
        <updated_at>Wed, 12 Sep 2012 15:36:37 -0500</updated_at>
      </reference>
    </references>
    <tag id="31">
      <id>31</id>
      <name><![CDATA[peace]]></name>
    </tag>
  </tagging>
  <meta>
    <fums><![CDATA[<script>
var _BAPI=_BAPI||{};
if(typeof(_BAPI.t)==='undefined'){
document.write('\x3Cscript src="'+document.location.protocol+'//d2ue49q0mum86x.cloudfront.net/include/fums.c.js"\x3E\x3C/script\x3E');}
document.write("\x3Cscript\x3E_BAPI.t('5050f2554104f5.56323168');\x3C/script\x3E");
</script><noscript><img src="https://d3a2okcloueqyx.cloudfront.net/nf1?t=5050f2554104f5.56323168" height="1" width="1" border="0" alt="" style="height: 0; width: 0;" /></noscript>]]></fums>
    <fums_tid>5050f2554104f5.56323168</fums_tid>
    <fums_js_include>d2ue49q0mum86x.cloudfront.net/include/fums.c.js</fums_js_include>
    <fums_js><![CDATA[var _BAPI=_BAPI||{};if(typeof(_BAPI.t)!='undefined'){ _BAPI.t('5050f2554104f5.56323168'); }]]></fums_js>
    <fums_noscript><![CDATA[<img src="https://d3a2okcloueqyx.cloudfront.net/nf1?t=5050f2554104f5.56323168" height="1" width="1" border="0" alt="" style="height: 0; width: 0;" />]]></fums_noscript>
  </meta>
</taggings>

Delete

DELETE /taggings/#{tagging_id}.xml

Deletes the tagging identified by the specified ID. The tagging ID is a number and is returned when a tagging is listed.

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

Example:

Request
XML
JSON
DELETE https://cy.bibles.org/taggings/12.xml
Response
[Empty response body]


DELETE /user/taggings/#{tag_name}.xml

You may also delete all of your tags for a given tag name by passing the name in the request URL. Make sure you properly URL encode the tag name in the URL for this request.

Example:

Request
XML
JSON
DELETE https://cy.bibles.org/user/taggings/love.xml
Response
[Empty response body]