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.com/-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.com/-api/settings/v1/export?owner=yourUsername&project=yourProjectName'

Response example json, export settings

{
  "version" : "1.6",
  "domain" : "other",
  "language" : "English",
  "usePreSelections" : true,
  "usePreDeselections" : false,
  "usePreCaseSentive" : false,
  "useMachineLearning" : false,
  "nativePDF" : false,
  "autoSave" : false,
  "confirmLayer" : false,
  "taskDistributionNumber" : 0,
  "taskDistributionMembers" : [ ],
  "folders" : {
    "pool" : {
      "name" : "pool",
      "index" : 0,
      "children" : { }
    }
  },
  "requirements" : { },
  "webhooks" : { },
  "metas" : {
    "m_2" : {
      "id" : "m_2",
      "name" : "Type",
      "oldnames" : [ ],
      "description" : "A,B,C",
      "type" : "enum"
    }
  },
  "fields" : { },
  "relations" : { },
  "entities" : { }
}

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.com/-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.com/-api/settings/v1/folders/add?owner=yourUsername&project=yourProjectName' -d '{"path": "pool/new"}'

import requests

tagtogAPIUrl = "https://www.tagtog.com/-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)

Response example json, add folder to project

{
  "newSettings": {
    "version": "1.6",
    "domain": "other",
    "language": "English",
    "usePreSelections": true,
    "usePreDeselections": false,
    "usePreCaseSentive": false,
    "useMachineLearning": false,
    "nativePDF": false,
    "autoSave": false,
    "confirmLayer": false,
    "taskDistributionNumber": 0,
    "taskDistributionMembers": [],
    "folders": {
      "pool": {
        "name": "pool",
        "index": 0,
        "children": {
          "new": {
            "name": "new",
            "index": 10,
            "children": {}
          }
        }
      }
    },
    "requirements": {},
    "webhooks": {},
    "metas": {
      "m_2": {
        "id": "m_2",
        "name": "Type",
        "oldnames": [],
        "description": "A,B,C",
        "type": "enum"
      }
    },
    "fields": {},
    "relations": {},
    "entities": {}
  },
  "mapNewIds": {}
}

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.com/-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.com/-api/settings/v1/folders/remove?owner=yourUsername&project=yourProjectName' -d '{"path": "pool/newRenamed" }'