API docs


Thanks for choosing the Documents API to build NLP solutions into your app or website. Getting started with a new API can be challenging, so we have created a step-by-step guide that walks you through how to make your first API calls and more.

Version 1.0
Endpoint /-api/documents/v1

Authentication

The current API supports Basic Authentication. Note that the username and password are secured via an HTTPS connection.

Import and annotate text

One of the most common scenarios using tagtog is to annotate text automatically. The API is the perfect way to automate this task.

Plain text POST

Annotates automatically plain text.

Parameters

Name Default Example Description
text - Antibody-dependent cellular cytotoxicity (ADCC), a key effector function for the clinical effectiveness of monoclonal antibodies, is triggered by the engagement of the antibody Fc domain with the Fcγ receptors expressed by innate immune cells such as natural killer (NK) cells and macrophages. Plain text
project - yourProjectName Name of the project
owner Username sending the request yourUsername (in this example we assume the user is also the owner of the project) Owner of the project you want to use
output visualize ann.json The format of the output you want to be returned by the API. API output formats.

Optional Parameters

Name Default Example Description
member master aka project official annotations john

Project member you want to use

Only applicable if the project has multiple team members

folder pool pool You can choose between the folders pool and test. More information

The example below imports plain text and retrieve the automatic annotations in ann.json format.

curl -u yourUsername:yourPassword -X POST -d 'text=Antibody-dependent cellular cytotoxicity (ADCC), a key effector function for the clinical effectiveness of monoclonal antibodies, is triggered by the engagement of the antibody Fc domain with the Fcγ receptors expressed by innate immune cells such as natural killer (NK) cells and macrophages.' 'https://www.tagtog.net/-api/documents/v1?project=yourProjectName&owner=yourUsername&output=ann.json'
import requests

tagtogAPIUrl = "https://www.tagtog.net/-api/documents/v1"

auth = requests.auth.HTTPBasicAuth(username='yourUsername', password='yourPassword')
params = {'project':'yourProjectName', 'owner': 'yourUsername', 'output':'ann.json'}
payload = {'text': 'Antibody-dependent cellular cytotoxicity (ADCC), a key effector function for the clinical effectiveness of monoclonal antibodies, is triggered by the engagement of the antibody Fc domain with the Fcγ receptors expressed by innate immune cells such as natural killer (NK) cells and macrophages.'}
response = requests.post(tagtogAPIUrl, params=params, auth=auth, data=payload)
print(response.text)

fetch('https://www.tagtog.net/-api/documents/v1?project=yourProjectName&owner=yourUsername&output=ann.json', {
    method: 'POST',
    headers: {'Authorization' : "Basic " + btoa('yourUsername' + ":" + 'yourPassword'),
              'Accept': 'application/json',
              'Content-Type': 'application/json',
             },
    body: JSON.stringify({'text':'Antibody-dependent cellular cytotoxicity (ADCC), a key effector function for the clinical effectiveness of monoclonal antibodies, is triggered by the engagement of the antibody Fc domain with the Fcγ receptors expressed by innate immune cells such as natural killer (NK) cells and macrophages.'})
}).then(response => response.json()).then(json => {
  console.log(json);
}).catch(function(error) {
  console.log('Error: ', error);
});

PubMed Abstracts POST GET

Import one or more PubMed abstracts and annotate them.

Parameters

Name Default Example Description
idType tagtogID PMID Type of Id. List of idTypes
ids - 23596191, 29438695 Comma-separated list of ids, all the same type. The response is limited to the last id imported.
project - yourProjectName Name of the project
owner Username sending the request yourUsername (in this example we assume the user is also the owner of the project) Owner of the project you want to use
output visualize ann.json The format of the output you want to be returned by the API. API output formats.

Optional Parameters

Name Default Example Description
member master aka project official annotations john

Project member you want to use

Only applicable if the project has multiple team members

folder pool pool You can choose between the folders pool and test. More information

The example below imports a list of PMIDs and retrieves the annotations of the last document in ann.json format.

curl -u yourUsername:yourPassword -X POST 'https://www.tagtog.net/-api/documents/v1?project=yourProjectName&owner=yourUsername&idType=PMID&ids=23596191,29438695&output=ann.json'
import requests

tagtogAPIUrl = "https://www.tagtog.net/-api/documents/v1"

auth = requests.auth.HTTPBasicAuth(username='yourUsername', password='yourPassword')
params = {'project':'yourProjectName', 'owner': 'yourUsername', 'idType':'PMID', 'ids':['23596191','29438695'], 'output':'ann.json'}
response = requests.post(tagtogAPIUrl, params=params, auth=auth)
print(response.text)

fetch('https://www.tagtog.net/api/0.1/documents?project=yourProject&owner=yourUsername&idType=PMID&ids=23596191,29438695&output=ann.json', {
  method: 'POST',
  headers:  { 'Authorization' : "Basic " + btoa('yourUsername' + ":" + 'yourPassword'),
              'Accept': 'application/json',
              'Content-Type': 'application/json',
            },
}).then(response => response.json()).then(json => {
  console.log(json);
}).catch(function(error) {
  console.log('Error: ', error);
});

URL POST GET

Import the text content of a URL and annotate it.

Parameters

Name Default Example Description
url - https://en.wikipedia.org/wiki/Autonomous_cruise_control_system URL no annotate
project - yourProjectName Name of the project
owner Username sending the request yourUsername (in this example we assume the user is also the owner of the project) Owner of the project you want to use
output visualize weburl The format of the output you want to be returned by the API. API output formats.

Optional Parameters

Name Default Example Description
member master aka project official annotations john

Project member you want to use

Only applicable if the project has multiple team members

folder pool pool You can choose between the folders pool and test. More information

The example below imports a URL and retrieves the web link for the annotated document. That link redirects to the annotated document at the tagtog app.

curl -u yourUsername:yourPassword -X POST 'https://www.tagtog.net/-api/documents/v1?project=yourProjectName&owner=yourUsername&url=https://en.wikipedia.org/wiki/Autonomous_cruise_control_system&output=weburl'
import requests

tagtogAPIUrl = "https://www.tagtog.net/-api/documents/v1"

auth = requests.auth.HTTPBasicAuth(username='yourUsername', password='yourPassword')
params = {'project':'yourProjectName', 'owner': 'yourUsername', 'output':'weburl', 'url':'https://en.wikipedia.org/wiki/Autonomous_cruise_control_system'}
response = requests.post(tagtogAPIUrl, params=params, auth=auth)
print(response.text)

fetch('https://www.tagtog.net/-api/documents/v1?project=yourProjectName&owner=yourUsername&url=https://en.wikipedia.org/wiki/Autonomous_cruise_control_system&output=weburl', {
  method: 'GET',
  headers: {'Authorization' : "Basic " + btoa('yourUsername' + ":" + 'yourPassword')},
}).then(response => response.text()).then(text => {
  console.log(text);
}).catch(function(error) {
  console.log('Error: ', error);
});

Files POST

Import a file and annotate it.

Parameters

Name Default Example Description
files - text.txt, text2.txt List of files to annotate. Supported input formats
project - yourProjectName Name of the project
owner Username sending the request yourUsername (in this example we assume the user is also the owner of the project) Owner of the project you want to use
output visualize ann.json The format of the output you want to be returned by the API. API output formats.

Optional Parameters

Name Default Example Description
member master aka project official annotations john

Project member you want to use

Only applicable if the project has multiple team members

folder pool pool You can choose between the folders pool and test. More information

This example imports a file and retrieves the annotations in ann.json. You can extend it easily to upload multiple files.

import requests

tagtogAPIUrl = "https://www.tagtog.net/-api/documents/v1"

auth = requests.auth.HTTPBasicAuth(username='yourUsername', password='yourPassword')
params = {'project':'yourProjectName', 'owner': 'yourUsername', 'output':'ann.json'}
#you can append more files to the list in case you want to upload multiple files
files = [('file', open('files/text.txt', 'rb'))]
response = requests.post(tagtogAPIUrl, params=params, auth=auth, files=files)
print(response.text)

var input = document.querySelector('input[type="file"]')
var data = new FormData()
data.append('file', input.files[0])

fetch('https://www.tagtog.net/-api/documents/v1?project=yourProjectName&owner=yourUsername&output=ann.json', {
  method: 'POST',
  headers: {'Authorization' : "Basic " + btoa('yourUsername' + ":" + 'yourPassword')},
  body: data
}).then(response => response.text()).then(text => {
  console.log(text);
}).catch(function(error) {
  console.log('Error: ', error);
});

Search documents in a project GET

You can search using the documents API. Search across your pool folder and retrieve the matching documents. You can use it to augment your own search engine or simply create a new one. It is also very simple to use the search API to display statistics. Here we show you how to do it.

Learn how to build search queries here.

Parameters

Name Default Example Description
search - entity:GGP:P02649 Search query. Learn how to build queries here.
project - yourProjectName Name of the project
owner Username sending the request yourUsername (in this example we assume the user is also the owner of the project) Owner of the project you want to use

Optional Parameters

Name Default Example Description
page 0 1 Number: page number in a paginated search.
output search search

You can choose between search or csv

search (search response): use it to perform search queries.

csv: it ignores the query parameter and retrieve the id of each document and the status of each document (true if annotations are completed, false if not)


This example searches across your document pool to find documents that have at least one entity normalized to the gene P02649.

Search response format

Response format for search queries.

{
  "version": "String: this format's version, e.g. 0.1.0",
  "search": "String: user search query",
  "totalFound": "Number: total number of documents that match the search query",
  "pages": {
    //the search is paginated
    "current": "Number: paginated search's current page",
    "previous": "Number: paginated search's previous page; -1 if current page == 0",
    "next": "Number: paginated search's current page; -1 if current page is the last page",
  }
  "docs":
  [
    {
      "id": "String: full tagtogID -- Use this to download the document",
      "header": "String: title if the document has a natural title or otherwise an excerpt of the text's start",
      "anncomplete": "Boolean: status for the document's annotation completion",
      "updated": "String: date for the document' last update, in ISO_INSTANT format, e.g. 2017-02-23T08:31:40.874Z",
    },
    //next documents in the array of results...
  ]
}

Get existing documents GET

You can use the API to export documents already imported. You need the Id of the document before you get it. If you don't have this Id, you can find it using the search feature. You can export only 1 document within each request.

Parameters

Name Default Example Description
output visualization ann.json The format of the output you want to be returned by the API. API output formats.
idType tagtogID tagtogID Type of Id. List of idTypes
ids - aVTjgPL0x5m_xgJr3qcpfXcSoY_q-text Comma-separated list of ids, all the same type. The response is limited to the last id imported.
project - yourProjectName Name of the project
owner Username sending the request yourUsername (in this example we assume the user is also the owner of the project) Owner of the project you want to use

Optional Parameters

Name Default Example Description
member master aka project official annotations john

Project member you want to use

Only applicable if the project has multiple team members


This example exports a tagtog document into ann.json format. Notice that we don't use the parameter idType because it defaults to tagtogID, the type of the id used.

curl -u yourUsername:yourPassword 'https://www.tagtog.net/-api/documents/v1?project=yourProjectName&owner=yourUsername&ids=aVTjgPL0x5m_xgJr3qcpfXcSoY_q-text&output=ann.json'
import requests

tagtogAPIUrl = "https://www.tagtog.net/-api/documents/v1"

auth = requests.auth.HTTPBasicAuth(username='yourUsername', password='yourPassword')
params = {'project':'yourProjectName', 'owner': 'yourUsername', 'ids':'aVTjgPL0x5m_xgJr3qcpfXcSoY_q-text', 'output':'ann.json'}
response = requests.get(tagtogAPIUrl, params=params, auth=auth)
print(response.text)

fetch('https://www.tagtog.net/-api/documents/v1?project=yourProjectName&owner=yourUsername&ids=aVTjgPL0x5m_xgJr3qcpfXcSoY_q-text&output=ann.json', {
  method: 'GET',
  headers: {'Authorization' : "Basic " + btoa('yourUsername' + ":" + 'yourPassword')},
}).then(response => response.text()).then(text => {
  console.log(text);
}).catch(function(error) {
  console.log('Error: ', error);
});

Delete documents DELETE

You can delete documents in your project using the API. Fine-tune the search parameter to delete only those documents returned by the search query.

This request returns the number of documents deleted.

Parameters

Name Default Example Description
search - entity:GGP Search query to list the documents to remove. Learn how to build queries here
project - yourProjectName Name of the project
owner Username sending the request yourUsername (in this example we assume the user is also the owner of the project) Owner of the project you want to use

This example deletes all documents that contain at least one entity of type gene.

curl -u yourUsername:yourPassword -X DELETE 'https://www.tagtog.net/-api/documents/v1?project=yourProjectName&owner=yourUsername&search=entity:gene'
import requests

tagtogAPIUrl = "https://www.tagtog.net/-api/documents/v1"

auth = requests.auth.HTTPBasicAuth(username='yourUsername', password='yourPassword')
params = {'project':'yourProjectName', 'owner': 'yourUsername', 'search':'entity:gene'}
response = requests.delete(tagtogAPIUrl, params=params, auth=auth)
print(response.text)

fetch('https://www.tagtog.net/-api/documents/v1?project=yourProjectName&owner=yourUsername&search=entity:gene', {
  method: 'DELETE',
  headers: {'Authorization' : "Basic " + btoa('yourUsername' + ":" + 'yourPassword')},
}).then(response => response.text()).then(text => {
  console.log(text);
}).catch(function(error) {
  console.log('Error: ', error);
});

output parameter

These are the different types of outputs supported by the API.

Name Description
visualize This is the default value. Choose to visualize the document resource returning the web page directly (web or web-editor-only if the User Agent is a recognized browser and a tagtog project information was given, i.e. web, or, respectively, no tagtog project was given, i.e., web-editor-only) or otherwise return the weburl (typically, the User Agent will be a command line program)
web Visual representation of the document and its annotations on the tagtog web interface (HTML page).
web-editor-only Analogously as web, yet without the information of a tagtog project, i.e., only the document editor layout. Useful in case you want to create iFrames in your web app.
weburl URL of the annotated document at tagtog web interface.
null Special output to signify that no document output is desired. A JSON response of the request will be returned instead. For example, when importing a document:
{
  "ok":1 //number of documents successfully changed,
  "errors":0 //number of documents with errors,
  "items": //list of documents changed
  [
    { "origid":"text",
      "names":["text.txt"],
      "tagtogID":"aOM6EFIvULWc6J.7MAYQB3V2sF84-text",
      "result":"created"}
  ],
  "warnings":[]
}

You can use this parameter, for example, if you need the API to return you the id of each document imported.

ann.json Annotations part of the anndoc format documentation.
html xml Content part of the anndoc format documentation.
text Document content in plain text.
csv List of the project's documents and their master (official) annotation status. Currently it works only with parameter search=*
docjson Format used internally by some users

idType parameter

Possible values for the parameter are described below.

Name Description
tagtogID This is the default value. tagtog-internal document id or docid (e.g. ai1AzDk4wQzbL.BKzlrA_CrK8gJi-text). Its use implicitly means that the document already exists in the associated project.
PMID PubMed ID.
PMCID PubMed Central ID.
WikipediaID Wikipedia ID. Cooming soon.
TweetID Tweet ID. e.g: 931029434814959616. Coming soon

API Clients

Python tagtog script

If you want to use an already built API client. You have the tagtog python API script to do many common operations in tagtog using the API: upload (also folders), search, and download documents!

usage: tagtog [-h] {upload,search,download} ...

tagtog official script to Upload & Search & Download documents. Version: 0.1.2
Author: tagtog (@tagtog_net) - Contact: Juan Miguel Cejuela (@juanmirocks) API
documentation: http://docs.tagtog.net/API.html

positional arguments:
  {upload,search,download}
    upload              Upload files to tagtog
    search              Search documents by query, e.g. `*` (all)
    download            Download documents by search query, e.g.
                        `updated:[NOW-1DAY to NOW]

optional arguments:
  -h, --help            show this help message and exit

Search

It uses the API to search documents in your project. Parameters can be consulted here or using tagtog.py search --help. You can learn how to build search queries here

The example below retrieves all the documents from your project.

python3 tagtog.py search '*' -u yourUsername -w yourPassword -p yourProjectName -o yourUsername

Upload

It uses the API to upload documents to your project.

Upload PMIDs

Parameters can be consulted here or using tagtog.py upload --help.

The example below upload the abstract from two PMIDs to your project. Remember to indicate which is the type of id (--idType or -i) for the document.

python3 tagtog.py upload 29539636,29531059 -u yourUsername -w yourPassword -p yourProjectName -o yourUsername -i PMID
Upload files

Parameters can be consulted using tagtog.py upload --help. You must include the parameter --extension or -e to indicate the extension of the files to upload (e.g. txt, pdf, etc.). These are the input files supported

The example below upload the PDF documents of a folder, to your project.

python3 tagtog.py upload ./myfolder -u yourUsername -w yourPassword -p yourProjectName -o yourUsername --extension pdf

The example below upload a single file to your project.

python3 tagtog.py upload ./myfile.txt -u yourUsername -w yourPassword -p yourProjectName -o yourUsername

Download

It uses the API to download documents from your project. In one call to the script you can download all documents matching a search query.

Parameters can be consulted using tagtog.py download --help.

You can indicate the folder where you can store the downloaded documents using the parameter --output_folder (it defaults to the folder where the script is running).

Use the parameter --output or -t to indicate the output type for the downloaded files.

You can learn how to build search queries here

The example below download the annotations (ann.json) for all the documents in a project.

python3 tagtog.py download '*' -u yourUsername -w yourPassword -p yourProjectName -o yourUsername --output_folder ./myDownloadFolder -t ann.json