API settings

Version 1.2
Endpoint /-api/settings/v1


Annotations Legend

GET a JSON map of annotation tasks ids to names (e.g. {"e_1": "Person"}).

Endpoint /-api/settings/v1/annotationsLegend?owner=...&project=...
Method GET
Output JSON

Input

None

Coding examples

curl -u yourUsername:yourPassword 'https://www.tagtog.net/-api/settings/v1/annotationsLegend?owner=yourUsername&project=yourProjectName'


Members management

Read members

Get the list of confirmed members & pending members in your project.

  • Method: GET
  • Endpoint: /-api/settings/v1/members?owner=...&project=...

Input (parameters)

Body: None

Output

Successful status code: 200 (OK)

Payload: JSON (application/json)

Name Example Description
members [{"username":"MyOrganization","role":{"name":"admin"},"inTeams":[]}, ...] Array of confirmed members in the project (including those added via teams).
pendingMembers [{"invitationToken":"invt-8ac3e282-3826-4f1f-a415-2cf1df30b3ce","role":{"name":"curator"},"email":"somebody@example.org"}, ...] Array of pending members in the project.
teams [{"name":"MyTeam1","defaultRole":{"name":"reader"},"members":[{"username":"test01","role":{"name":"reader"},"inTeams":[{"name":"MyTeam1"}]}]}] Array of teams in the project.

⚠️ Deprecation: the output field roleName was deprecated on 2020-11-01, and will be removed after 2021-05-01. Please use the new field: {"role":{"name":"..."}}.


Create members

Add a member (or team’s members) to your project.

  • Method: POST
  • Endpoint: /-api/settings/v1/members?owner=...&project=...

Input (parameters)

Body: JSON (application/json)

Type Name Default Examples Description
Body loginid   “John” or “MyTeam” Username or email address of the tagtog user you want to invite to your project to. Moreover, on tagtog OnPremises ENTERPRISE, you can also give the name of a team; in this case, all the team’s members will be added to the project.

If the users exist on tagtog, currently, they will be added immediately to your project without requiring confirmation from the users. This might change in the future.

If you give an email address that is not associated yet with a tagtog user, the email address will receive an invitation link to join tagtog and your project. Invited members who have not confirmed yet are called “pending members”.
Body roleName   “reader” Role (name) to give to the user.

Output

Successful status code: 205 (Reset Content; no payload)


Update members

Change the role of an existing & confirmed member (or all the members of an existing team) in your project.

  • Method: PUT
  • Endpoint: /-api/settings/v1/members/:loginid?owner=...&project=...

Input (parameters)

Body: JSON (application/json)

Type Name Default Examples Description
Path loginid   “John” or “MyTeam” Username or email of the project member to update. Moreover, on tagtog OnPremises ENTERPRISE, you can also give the name of a team; in this case all the existing team’s members will be updated.
Body roleName   “reviewer” New role (name) to give to the user.

Output

Successful status code: 205 (Reset Content; no payload)


Delete members

Remove an existing & confirmed member (or all the members of an existing team) from your project.

  • Method: DELETE
  • Endpoint: /-api/settings/v1/members/:loginid?owner=...&project=...

Input (parameters)

Body: None

Type Name Default Examples Description
Path loginid   “John” or “MyTeam” Username of the project member to delete.

Output

Successful status code: 205 (Reset Content; no payload)


Get pending members (only)

Get the list of pending members in your project.

  • Method: GET
  • Endpoint: /-api/settings/v1/pending-members?owner=...&project=...

Input (parameters)

Body: None

Output

Successful status code: 200 (OK)

Payload: JSON (application/json)

Name Example Description
pendingMembers [{"invitationToken":"invt-8ac3e282-3826-4f1f-a415-2cf1df30b3ce","role":{"name":"curator"},"email":"somebody@example.org"}, ...] Array of pending members in the project.

Delete pending member

Remove a pending member from your project.

  • Method: DELETE
  • Endpoint: /-api/settings/v1/pending-members/:invitationToken?owner=...&project=...

Input (parameters)

Body: None

Type Name Default Example Description
Path invitationToken   “invt-8ac3e282-3826-4f1f-a415-2cf1df30b3ce” Invitation token, which uniquely identifies the invitation to the pending member.

Output

Successful status code: 205 (Reset Content; no payload)


Update task distribution

Update the configuration of task distribution of your project.

  • Method: PUT
  • Endpoint: /-api/settings/v1/task-distribution?owner=...&project=...

Input (parameters)

Body: JSON (application/JSON)

Type Name Default Example Description
Body taskDistributionNumber   2 See docs.
Body taskDistributionMembers   ["yourUsername", "John", "Laura"] See docs.

Output

Successful status code: 200 (OK)

Payload: JSON (application/json)

Name Example Description
mapNewIds {} Not relevant; always empty.
newSettings See docs below New full settings json object of the project.


(Full) Settings management

Export Settings

Endpoint /-api/settings/v1/export?owner=...&project=...
Method GET
Output JSON

Input

None

Coding examples

curl -u yourUsername:yourPassword 'https://www.tagtog.net/-api/settings/v1/export?owner=yourUsername&project=yourProjectName'

Import Settings

Endpoint /-api/settings/v1/import?owner=...&project=...
Method POST
Output JSON; fields: mapNewIds, newSettings (the new imported project's JSON settings)

Input

JSON project settings, in the same format as returned by exporting the settings.

Coding examples

curl -u yourUsername:yourPassword -H "Content-Type: application/json" -XPOST 'https://www.tagtog.net/-api/settings/v1/import?owner=yourUsername&project=yourProjectName' -d @$HOME/Downloads/tagtog_yourUsername_yourProjectName.json


Folders management

For all folder operations, please note that pool must always be the root folder. More information.

Add folder

Endpoint /-api/settings/v1/folders/add?owner=...&project=...
Method POST
Output JSON; fields: mapNewIds (always empty), newSettings (the new project's JSON settings)

Input

Two variants in JSON format:

1) (Full) path:

Name Default Example Description
path - pool/new Full path of the new folder

2) Parent path & new folder name:

Name Default Example Description
parentPath - pool Full path up to the parent (included) of the new folder
newFolderName - new New folder name to be added to the parent path

In both cases, the parent path must have been already defined. In other words, in Unix jargon, mkdir is permitted, but not mkdir -p.

Coding examples

curl -u yourUsername:yourPassword -H "Content-Type: application/json" -XPOST 'https://www.tagtog.net/-api/settings/v1/folders/add?owner=yourUsername&project=yourProjectName' -d '{"path": "pool/new"}'
import requests

tagtogAPIUrl = "https://www.tagtog.net/-api/settings/v1/folders/add"

auth = requests.auth.HTTPBasicAuth(username="yourUsername", password="yourPassword")
params = {"owner": "yourUsername", "project": "yourProjectName"}
payload = {'parentPath': 'pool', 'newFolderName': 'myNewFolder'}
response = requests.post(tagtogAPIUrl, auth=auth, params=params, json=payload)
print(response.text)

Rename folder

Endpoint /-api/settings/v1/folders/rename?owner=...&project=...
Method POST
Output JSON; fields: mapNewIds (always empty), newSettings (the new project's JSON settings)

Input

Name Default Example Description
path - pool/new Full path of the existing folder to be renamed
newFolderName - newRenamed New folder name

The given path must exist. The last element of the path (in the example: “new”) is renamed to “newRenamed”

Coding examples

curl -u yourUsername:yourPassword -H "Content-Type: application/json" -XPOST 'https://www.tagtog.net/-api/settings/v1/folders/rename?owner=yourUsername&project=yourProjectName' -d '{"path": "pool/new", "newFolderName": "newRenamed" }'

Remove folder

Endpoint /-api/settings/v1/folders/remove?owner=...&project=...
Method POST
Output JSON; fields: mapNewIds (always empty), newSettings (the new project's JSON settings)

Input

Name Default Example Description
path - pool/newRenamed Full path of the folder to be deleted

The given path must exist. You can “delete multiple levels” at the same time. That is, if the folder path (in the example) pool/newRenamed/otherLevel existed, while deleting newRenamed, the folder otherLevel would also be deleted.

⚠️ CAUTION: all documents within the (possibly-multiple) deleted folders are also deleted! Make sure you do not delete valuable documents. At the moment there is no API to “move” documents between folders. However, the same can be implemented by 1) downloading, 2) removing, 3) reuploading to a different folder.

Coding examples

curl -u yourUsername:yourPassword -H "Content-Type: application/json" -XPOST 'https://www.tagtog.net/-api/settings/v1/folders/remove?owner=yourUsername&project=yourProjectName' -d '{"path": "pool/newRenamed" }'